Skill definitions

A skill definition is the contract between a domain expert and a coding agent. It tells the agent:

What this workflow does, when to use it, and how it fits into the broader fund-ops process
What steps it has, what each step does, and how each step renders to a human reviewer
What configuration the workflow accepts at runtime
Which template files to generate and what each one is responsible for

In Ntropii, a skill definition is a runbook.md file with YAML frontmatter and a markdown body, sitting at the root of each runbook directory.

Where skills live

runbook-templates/
└── runbooks/
    ├── nav-monthly/
    │   ├── runbook.md          ← the skill definition
    │   ├── templates/
    │   │   ├── workflow.py     ← generated from the skill
    │   │   ├── activities.py
    │   │   └── models.py
    │   └── tests/
    │       └── test_scenarios.py
    ├── document-ingest/
    │   └── ...
    └── nav-monthly-journals/
        └── ...

Each runbook directory has exactly one runbook.md. The coding agent reads it, then writes (or updates) the files in templates/ to satisfy the skill.

Anatomy of a skill definition

Frontmatter — identity

---
id: rb-nav-monthly
slug: nav-monthly
name: Monthly NAV (Real Estate)
description: >
  Monthly NAV cycle for a real estate SPV. Parent workflow that dispatches
  document-ingest and nav-monthly-journals.
classification: REAL_ESTATE_OPS
tags:
  - NAV
  - Monthly
  - Real Estate
  - Parent Workflow
jurisdictions:
  - UK
  - Jersey
  - Luxembourg
version: 0.1.0
state: DRAFT
author: Ntropii

The identity block is what shows up in tenant UIs and search. Tags and jurisdictions feed the skill library’s filters.

Frontmatter — steps

Each step describes one stage of the workflow. The agent uses these to produce the NtroWorkflow subclass and its activities.

steps:
  - id: period_open
    label: Open Period
    activity: open_period
    component: LOADING
    timeout_minutes: 1
    description: Initialise the period, validate COA, lock entity config

  - id: ingest_documents
    label: Ingest Documents
    child_workflow: document-ingest
    cardinality: many
    component: DATA_TABLE
    responsibility: accountant
    timeout_minutes: 1440
    config:
      columns:
        - {key: source, label: Source, type: text}
        - {key: status, label: Status, type: badge}
    description: >
      Dispatch one document-ingest child per expected document. The step
      advances when all children complete.

Two step shapes: activity (a Python callable on the worker) and child_workflow (dispatches another runbook). The component field tells the Tenant UI how to render the step’s progress and review screen — LOADING, DATA_TABLE, SUMMARY, APPROVAL, etc.

Frontmatter — templates

A manifest of files the agent should generate, with a one-line responsibility for each:

templates:
  - {path: templates/workflow.py,    description: NavMonthlyWorkflow class with child_workflow dispatch}
  - {path: templates/activities.py,  description: open_period and emit_period_summary activities}
  - {path: templates/models.py,      description: NavMonthlyContext, PeriodSummary, ExpectedDocument}
  - {path: templates/requirements.txt, description: pinned ntro deps}

The agent generates all of these. Anything in templates/ that isn’t listed here is treated as bespoke and left alone.

Frontmatter — config schema

JSON Schema for the runtime configuration the workflow accepts. This is what the Tenant UI renders as a config form, and what the runbook reads via ntro.capabilities.config at runtime.

config_schema:
  global:
    period:
      type: string
      pattern: "^\\d{4}-\\d{2}$"
      description: NAV period in YYYY-MM
    coa_required_accounts:
      type: array
      items: {type: string}
      default: ["200"]
  steps:
    ingest_documents:
      expected_documents:
        type: array
        items:
          type: object
          properties:
            source: {type: string}
            schema_slug: {type: string}

Two scopes: global (applies to the whole run) and steps.X (applies to one step). The config form in the UI groups fields by scope.

Markdown body — when to use, workflow patterns, edge cases

After the frontmatter, the markdown body is for the agent’s grounding. Standard sections:

When to use — selection criteria. “Use this when an SPV needs a monthly NAV with HITL review at two checkpoints.”
Workflow patterns — code skeleton showing the canonical structure. Anchors the agent so the generated code matches house style.
Edge cases / variants — known forks. “If the GL is hand-maintained instead of in Xero, replace the post step with a download_link.”

The body is unstructured prose — the agent reads it the same way a human would.

How a coding agent uses this

Reads the skill

“I want a monthly NAV runbook for Acme SPV.” The agent finds runbooks/nav-monthly/runbook.md, reads the frontmatter and body, and now knows the step structure, the config schema, and the templates it needs to produce.

Reads existing templates as reference

The agent looks at the existing templates/workflow.py, activities.py, and models.py in nav-monthly to ground itself in the SDK calling conventions — which ntro.capabilities to import, how to call data.get_data_plane(), where @runbook.step decorators go.

Generates / adapts the templates

Either creates a new runbook directory (if the request is novel) or modifies the existing templates (if the request is “tweak this one for Acme’s specific schema”). The output is plain Python — no AI in the runtime.

Validates locally

Runs ntro workflow test (the local test harness) to confirm the runbook executes against fixtures. Iterates if scenarios fail.

Available skills today

Three skills ship in the runbook-templates repo, all DRAFT state and battle-testable:

Slug	Purpose	Type
`nav-monthly`	Monthly NAV cycle for a real-estate SPV	Parent workflow
`document-ingest`	Inbound document → AI extraction → HITL approval → store	Child workflow
`nav-monthly-journals`	TB + extracted docs → propose allocation journal → HITL approval	Child workflow

Use these as starting points. Forking and adapting is the expected pattern — Ntropii’s value is in the skill structure and the SDK that runbooks compose, not in shipping a one-size-fits-all NAV.

What the correction corpus does

When a fund accountant corrects a coding agent’s output during PR review (a wrong GL classification, a missing edge case, a misnamed field), that correction is captured with full context: skill slug, jurisdiction, error category, resolution. The corpus feeds back into future skill executions — over time, the same skill applied to similar tenants generates fewer errors before the human ever sees the PR. This is the long arc of the compiled-agent model: the LLM gets better at generating the deterministic code, even though it’s not in the runtime loop.

Workflows overview

NtroWorkflow and @runbook.step — the SDK primitives a generated runbook uses.

Coding agents

Wire your agent to consume these skills.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

Skill definitions

Where skills live

Anatomy of a skill definition

Frontmatter — identity

Frontmatter — steps

Frontmatter — templates

Frontmatter — config schema

Markdown body — when to use, workflow patterns, edge cases

How a coding agent uses this

Available skills today

What the correction corpus does

Workflows overview

Coding agents

​Where skills live

​Anatomy of a skill definition

​Frontmatter — identity

​Frontmatter — steps

​Frontmatter — templates

​Frontmatter — config schema

​Markdown body — when to use, workflow patterns, edge cases

​How a coding agent uses this

​Available skills today

​What the correction corpus does

​Related

Workflows overview

Coding agents

Where skills live

Anatomy of a skill definition

Frontmatter — identity

Frontmatter — steps

Frontmatter — templates

Frontmatter — config schema

Markdown body — when to use, workflow patterns, edge cases

How a coding agent uses this

Available skills today

What the correction corpus does

Related