Skill model

A skill is a program, not a markdown file: <leaf>.cue is a typed model with its own logic and validation, and SKILL.md is rendered from it.

The model carries what prose cannot: typed routing and pipeline edges that must agree across skills, entry roles with their registers, a permission manifest, interface bindings for every program the skill calls, a smoke declaration, title states, the changelog. Every load validates all of it, so a wrong role, a route to nowhere, an undeclared tool or a version without its changelog row does not render. The file sits in the leaf dir, named after it (skills/quality/railroad-review/railroad-review.cue); payloads/<entry-id>.md holds template bodies. SKILL.md renders from both at deploy, never committed; only repo-scoped values wait for invocation (Interfaces and environment). Layout: Skills directory.

Everyday use

skill-render loads, validates and checks the model; re-saves <leaf>.cue canonically (CUE formatter, fixed field order); writes payloads, deletes orphans; stores the deployed body's token count on the newest changelog row. A failed check writes nothing. Root passes follow per-dir saves.

File shape

Top-level fields of <leaf>.cue. The schema (internal/skillgraph/schema.cue) refuses a model missing a required one.

Frontmatter and changelog

From skills/smart/qq/qq.cue:

changelog: [{
  date:    "2026-10-02"
  version: "1.0.4"
  text:    "Dropped the help-only Eval section — --help shows the smoke and eval declared beside the skill."
  tokens:  809
}, {
  date:    "2026-09-28"
  version: "1.0.3"
  text:    "Routing and Model are typed blocks in skill.cue; the Pipeline line renders from declared edges"
  tokens:  809
}]
frontmatter: [{
  key:   "name"
  value: " qq"
}, {
  key:   "version"
  value: " 1.0.4"
}, {
  key:   "format"
  value: " 2"
}, {
  key:   "allowed-tools"
  value: " Glob, Grep, Read"
}]

Sections and entries

Section kind: context, phase or route. A route section carries pred (when it applies) and exactly one anchor: replaces: <ids> (entries it substitutes) or between: <after>..<before> (splice point).

Flow entry with clauses, skills/verdict/investigate/investigate.cue:

sections: [{
  title: "2. Run"
  blocks: [{
    entry: {
      id: "SKILL-INVESTIGATE-RUN-004b"
      post: ["claims_ruled"]
      pred:      "claims_deduped"
      role:      "substep"
      statement: "RULE each claim `holds | refuted | needs-measurement` in Stage B, watching full funnel."
      title:     "Stage B Rulings"
    }
  }]
}]

Route section, skills/feature/fdesign/fdesign.cue, blocks elided:

{
  title: "Nightly route"
  blocks: […]
  kind:     "route"
  pred:     "mode = nightly"
  replaces: "GATE-001 + CODE-005 + CODE-009 + HANDOFF-001"
}

args block {rows: [{name, form?, default?, effect}]} → the ## Args table:

args: {
  rows: [{
    name:    "topic"
    default: "default slice"
    effect:  "context slice(s) injected; `--no-context` skips all — [Topic use](#skill-qq-context-001)"
    form:    "`topic:<name>`, repeatable"
  }]
}

Routing and model blocks

routing: {
  pipeline: {
    standalone: true
  }
  preconditions: ["one question in the invocation"]
  purpose: "answer a single question fast and cheaply."
  routes: [{
    for: "a subject to talk through"
    use: "/discuss"
  }, {
    for: "an answer that needs sources and citations"
    use: "/research"
  }]
}

model: {
  effort: "low"
  reason: "single lookup, short answer"
  tier:   "mid-tier"
}

Title block

Session-title states of the skill's approval gates. Deploy renders them to title.json beside SKILL.md, not into it.

title: {
  states: {
    "CODE-READY": {
      entry:   "SKILL-FDESIGN-CODE-005"
      meaning: "code gate presented — approve the Changes or request a change"
    }
    "DESIGN-READY": {
      entry:   "SKILL-FDESIGN-GATE-001"
      meaning: "design gate presented — approve or revise the design"
    }
  }
}

Smoke block

The skill's smoke test, never rendered into any file or deployed. The smoke runner loads the model and resolves every default in memory.

skills/feature/fimplement/fimplement.cue, check list shortened; fdesign expects {anchors: [...], minChecks: 0.4} instead:

smoke: {
  env: {
    CHECK: "go test ./internal/smoke/..."
  }
  expect: {
    check: ["go", "test", "internal/smoke/greeting.go", "internal/smoke/greeting_test.go", …]
  }
  fixture: {
    tree: "tree"
  }
  invoke: "fimplement-smoke.md"
  limits: {
    minutes: 45
    usd:     8.0
  }
}

Pipeline edges

pipeline: {standalone?, edges?: [{kind, skill, route?, optional?, needs?}], note?} places a skill among the others. standalone: also runs on demand outside the chain. route: a route of the edge's skill (/fdesign master).

Pipeline line: standalone; <from> → **<name>** → <to>; spawned by …; spawns …; escalates to … — <note>. skillmodel render checks every edge across the skills root: skill exists, other end agrees.

pipeline: {
  edges: [{
    kind:  "from"
    skill: "fdesign"
  }, {
    kind:     "from"
    skill:    "overlap"
    optional: true
  }, {
    kind:  "to"
    skill: "package-commit"
  }, {
    kind:  "spawnedBy"
    skill: "fleet"
  }, {
    kind:  "escalates"
    skill: "restack"
    needs: ["agentwt"]
  }]
}

What is enforced where

Five layers: shape in the schema, cross-references in the check, agreement between skills in the root render.

Formal clauses

pred: boolean expression over atoms (risk_map and dispatch_prepared, mode = nightly). post: atoms the entry makes true when it fires. internal/skillmodel.Derive turns them into the semantic model without judgment.

An entry without clauses is uncovered, not an error. make model-analyze SKILL=<name> runs the solver on the derived model. Clauses must always parse; on the strict tier every atom must also resolve against the skill's atoms or skills/vocabulary.cue (ACDSL-SKILL-013).

An atom's source marks an input the world sets: | -separated parts, each one of these.

A runtime part names an anchor and capture of the skill's own enforce block, so heartbeat's check and the model read one value. Shared atoms (skills/vocabulary.cue) take none; anything else fails the load. Format-3 and shared atoms live only while a stop, rule or quality pred, a route section pred or a query reads them; a step's pred keeps nothing alive. Format-2 locals live with any pred.

skills/quality/railroad-review/railroad-review.cue, strict tier; fdesign's enum atom role reads Args via source: "arg: master => master | arg: derived => derived".

atoms: {
  base_build_red: {
    sort:   "state"
    source: "runtime: base_health.base_build != ok"
  }
  plan_mode: {
    sort:   "state"
    source: "session"
  }
  recommendation: {
    kind: "enum"
    members: ["APPROVE", "CONDITIONAL", "REJECT"]
    sort:   "state"
    source: "runtime: review_json.recommendation"
  }
  void_rounds: {
    kind:   "int"
    sort:   "count"
    source: "runtime: ledger.void_rounds"
  }
}

Fields

A format-3 entry carries no labelled bullet: its statement is prose plus at most one inline command; its mechanics are the fields record, rendered after it as * <key>: <value> bullets in this order.

Links are tokens: [[SECTION-NNN]] within the skill, [[SKILL-X-SECTION-NNN]] across; the render derives [Title · SECTION-NNN](#skill-<leaf>-<section>-<nnn>). Legal in statements, item texts, fields.ref, Args default/effect cells, Routing purpose, preconditions and route use; never in payload bodies (exact bytes). Below format 3 the param label and [Title](#anchor) links stay legal.

From skills/quality/railroad-review/railroad-review.cue: a script spawn; the Build and test step's fields (SKILL-RAILROADREVIEW-ROUND-016).

entry: {
  id:      "SKILL-RAILROADREVIEW-WALK-004"
  channel: "script"
  fields: {
    ref: ["TPL-008"]
    script: "workflows/checklist.js"
  }
  role:      "spawn"
  statement: "INVOKE `workflows/checklist.js` — one `railroad-checklist` agent per direction lacking a checklist: contracts on a moved head, over the diff; correctness in round 1 without checklist, over the spec."
  title:     "Checklist agents"
}

fields: {
  flags: "--repo <dispatcher toplevel> --root <artifactsDir parent>/wt --branch claude-review/<runNs>-buildtest-r{r} --salvage <artifactsDir>/salvage"
  forwards: [{
    arg:  "expect-head-red"
    flag: "--skip"
  }]
  mints: {
    branch: "claude-review/<runNs>-buildtest-r{r}"
  }
  timeout: 600000
}

Interfaces and environment

A skill never names a smine program: every tool, command or path it calls is a variable bound to one catalog interface. One skill thus runs on a full install, a partial one, or a colleague's machine with their own tools.

The catalog

skills/interfaces.cue holds interfaces and providers, loaded with every skill like vocabulary.cue. An interface is one capability a skill calls.

A provider names a program and the versions it implements: {id, program, binary?, component?, implements, probe: ["interfaces"]}. component: install component shipping it, on PATH on every OS it installs on; binary: path the probe runs when it is off PATH (toolpolicy, a hook binary). Version and scope limits: Checks.

interfaces: [{
  id:      "test"
  version: 1
  kind:    "command"
  scope:   "repo"
  summary: "Runs the repo's full test suite."
  example: "go test ./..."
  invocation: {cwd: "repo-root", args: "none", stdin: "none", timeout: "20m"}
  result: {exit: {"0": "pass", other: "fail"}, stdout: "diagnostic"}
  validate: {resolves: true}
}]
providers: [{
  id:        "toolpolicy"
  program:   "toolpolicy"
  binary:    "~/.claude/hooks/bin/toolpolicy"
  component: "gate"
  implements: ["permission-check@1", "permission-freeze@1"]
  probe: ["interfaces"]
}]

Binding

env: {
  PLAN_SECTIONS: {interface: "plan-sections@1", required: true}
  CHECK: {interface: "check@1"}
}

Text references $SKILL_<SKILL>_<KEY>; scope decides where.

A reference fits its interface's kind:

Values

Deploy fills each variable from the first set source:

1. The deploy process's SKILL_<SKILL>_<KEY> environment variable.
2. The install record's SKILL_<SKILL>_<KEY> row (skills.variables, config server skill page).
3. Repo-scoped interfaces: the global default (skills.defaults, keyed by interface id, Environment tab's global defaults card).
4. The provider of the bound version: its PROVIDER_<ID> environment variable, its PROVIDER_<ID> row, then its catalog program if its component is in the render's set. A nil set, the canonical deploy, counts every component installed.
5. Unset.

A provider row moves all of a program's capabilities at once; a SKILL_ row pins one.

Repo-scoped placeholders

For the Claude home a repo-scoped variable is never resolved, so never unset, at deploy (source invocation); it skips nothing there. Its reference renders as a harness placeholder reading SKILL_<SKILL>_<KEY> from the session's environment at invocation. The entry whose statement or payload reads it, else each reading item, becomes one fenced block the harness runs before sending the skill content:

```!
awk 'BEGIN { if (ENVIRON["SKILL_FIMPLEMENT_CHECK"] == "") { print "SKILL_FIMPLEMENT_CHECK: not set - <summary>, e.g. go vet ./... - <hint>"; exit 2 }; printf "%s", "\052\052SKILL-FIMPLEMENT-COMMIT-002\052\052 after \140" ENVIRON["SKILL_FIMPLEMENT_CHECK"] "\140 is green \342\200\224 one Bash call per line" }'
```

Value rules

Deploy probes each provider it fills from, once per executable per run: <program> interfaces (or binary) prints {"interfaces": [...]}, the sorted versions it implements; all six binaries answer. A failed check leaves the variable unset, with a cause in the deploy log and on the skill page.

required keeps its effect; the skip line carries the cause.

A Skill(<leaf>) grant or pipeline edge to a skill the render cannot deploy (unmet requires, unset required variable) drops too. Set values fill as text in SKILL.md and copied sibling files, regex-quoted in enforce patterns, JSON-escaped elsewhere in enforce.json (reasons, recovery texts).

An allowed-tools rule reading a repo-scoped variable stays as text only when the render's set holds gate. The gate fills it per session from the session repo's values (skillenv.Resolve, the hook's resolution) and drops what it cannot fill; without the gate (the bundle) the rule drops. Neither deploy nor gate derives a permission rule from a value.

Checks

Deploy

The skills sync (internal/skills, configserver -sync-skills) renders for one component set and value map: the install record's components and skill rows (skills.variables, skills.providers, skills.defaults), on every writer path. The config server reads the record per request, so the Overview Sync, an apply and a skill-page save all deploy with the rows on disk.

The bundle

make skill-bundle writes the standalone bundle to dist/skills for the empty component set: install-scoped values from the shell's exports, repo-scoped ones as placeholders with the shell hint. A skill ships unless it requires a component, carries a license key or lacks a required install-scoped value.

Index dist/skills/README.md: per shipped skill, what the full install adds (summaries of its unset optional install-scoped variables); per skipped skill, what it needs.

- <leaf> (skipped): needs <ref> from the <component> component

Runtime placement lines

Runtime placement fields render into the deployed frontmatter after the authored fields: answered-by:, docker:, enable-delegation:, enforce-permissions:. With answeredBy: "hook" the skillhelp hook answers every typed invocation with answer.md plus the feature catalog; the model check requires a payload entry and refuses flow entries.

Z3 analysis

Because the model is typed, its rules can be questioned: a format-2 skill is a controlled-English rulebook (MUST, NEVER, If ⇒ STOP, VERIFY), and modeled, z3 answers whether rules contradict, whether an entry is unreachable, and "if a and b hold, can c?"

What the analysis layer is

An optional per-skill analysis tier (one <leaf>.cue field): authoring contract plus compile-time test suite. No runtime effect: deploy strips clause lines; the executing agent never sees them.

The pieces, bottom-up

Atoms build expressions, expressions clauses; clauses derive the model, queries question it.

Atom

One named, typed fact about a run.

Shared atoms: skills/vocabulary.cue, alias phrases mapping one wording to one atom. A skill's own: the atoms map of its <leaf>.cue, same shape:

atoms: {<id>: {sort, kind?, members?, source?, aliases?}}

source is a closed grammar; free text fails the load. runtime binds an enforce anchor's capture, so heartbeat's check and the model read one value.

arg: <row>[ => <member>]
session
environment
runtime: <anchor>[.<capture>[ = <literal> | != <literal>]]

An unread atom fails make skills-check; delete it and its clauses.

Expression

An expression (expr) is a condition over atoms: and, or, not, => (implies), parentheses, comparisons; +/- and number literals on ints.

remaining_budget < round_cost
lanes_returned = lanes_spawned
mode = nightly
apply_level >= medium
base_provided and base_unresolvable

The last: "a base was given and could not be resolved."

Clauses

An entry's pred/post fields in <leaf>.cue, written once when authoring. SKILL.md renders them as code lines directly above the headline, no blanks between, each ending in the markdown hard break \ so they stay separate lines, not one paragraph:

`{pred: <expr>}` \
`{post: <atoms>}` \
<entry headline>

Model

In memory, never committed, derived 100% mechanically from the clauses.

No translation layer, review pass or committed semantic-model artifact: a pure function of <leaf>.cue plus skills/vocabulary.cue, structurally drift-free. Each invariant and transition keeps its entry id, so solver answers point at <leaf>.cue and SKILL.md entries.

Query

A JSON file in the skill's queries/: one question, frozen to re-ask forever.

Reading the answers

Can the review ask the user?

make model-query SKILL=railroad-review EXPR='not asks_user'

verdict: unsat
core: SKILL-RAILROADREVIEW-EXEC-002

EXEC-002 is the invariant not asks_user: no state with the review asking is reachable.

The battery

skillmodel check <skill dir> (make model-check SKILL=<name>) runs it on the derived model, one line per finding, then a summary:

<skill dir>: <severity> <check>: <message>

Complete bound

Posts grant only bool atoms; int and enum atoms never change in a run. So a run changes state at most min(P, G) times, plus one step to fire the target.

complete bound = min(P, G) + 1
G = the number of granted bool atoms
P = the number of transitions granting at least one

An unsat reach verdict at that bound is therefore a proof, not a sample. P and G count only the cone of influence: atoms an effective guard, effective invariant or the question (assumes, check) mentions, closed over exclusivity groups. Unread atoms, such as observation atoms, get no step copies and don't inflate it.

smt and solve default to it; an explicit lower --bound or query bound runs, warning its unsat is no proof.

Route anchors

Anchors are solver semantics, not just drawing.

Ad hoc queries

skillmodel query --expr '<expr>' <skill dir> (make model-query SKILL=<name> EXPR='<expr>'): does the model imply the expression? The solver asserts effective invariants, exclusivity axioms and not <expr>, no soft clauses.

Validity, unlike a committed static query file's satisfiability (assume + check, sat = possible). Exit 0 on either verdict, 2 on error or unknown.

Where it runs

The make targets in The commands (make audit: validate only) and the config server graph view, on page load. The read-only graph view shows atoms with grant and read counts, the enforce declaration, the tier in its toolbar (tier: strict — <n> atoms, <m> queries or tier: annotations) and an all-warnings button listing every battery finding and structural warning. Edit the model as <leaf>.cue text.

The commands

Start with make model-analyze ("run it, see it"); the rest answer narrower questions.

Dead-entry check

solve --reach unsat: no run ever fires the entry, because

• its guard contradicts the rules;
• nothing grants an atom its pred needs;
• an obligatory stop blocks the way there;
• a replaces route takes its place whenever it could fire.

At the default complete bound that is a proof (DEAD — unreachable within the complete bound); a lower --bound warns and prints only unreachable within bound <n>. A query file commits such a question with reach (an entry id) and optional bound in place of check. The battery's reach check already covers every entry and stop.

The diagram

diagram draws the whole skill as Mermaid; section kinds come from each heading's {section: …} line, kind-less skills render all-phase as before.

Authoring section kinds

Boundary principle: a section ends where its last granted output lands; prose on the next section's internals goes there.

Workflow stage files

Programmatic stages are workflow files under workflows/: one per spawn, or a composition nesting others (railroad-review's round.js: lanes, dedup, verify, station). The dispatcher invokes the file at its spawn entry; the script channel names it.

Inputs and refs

Closed producer/consumer system: an atom guarding flow is granted by a step's post or declared an input by its source (grammar under Atom). skillmodel check enforces producer-or-input on the model tier; the graph view shows inputs as invocation tiles in a column left of the structure.

Refs point into vocabulary (defs, payloads) or own-section wiring, never cross-section control flow: sequencing belongs to the condition system. A route may ref the entries its anchor clause names.

Graph view

Current state and edges