> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Skill definitions
> The frontmatter-rich runbook.md file that teaches a coding agent how to generate Ntropii workflows for a specific domain.
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
```yaml theme={null}
---
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.
```yaml theme={null}
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](/get-started/tenant-architecture) 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:
```yaml theme={null}
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](/get-started/tenant-architecture) renders as a config form, and what the runbook reads via `ntro.capabilities.config` at runtime.
```yaml theme={null}
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
"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.
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.
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.
Runs `ntro workflow test` (the [local test harness](/deploy-and-run/testing-locally)) to confirm the runbook executes against fixtures. Iterates if scenarios fail.
## Available skills today
Three skills ship in the [`runbook-templates` repo](https://github.com/ntropii-com/runbook-templates), 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](/get-started/how-it-works): the LLM gets better at *generating* the deterministic code, even though it's not in the runtime loop.
## Related
`NtroWorkflow` and `@runbook.step` — the SDK primitives a generated runbook uses.
Wire your agent to consume these skills.