skills/ is the source of truth for every skill; the skills sync renders it one way into the home dirs.
The Go skills sync (internal/skills, via configserver -sync-skills) deploys each skill flat to ~/.claude/skills/<leaf> and ~/.codex/skills/. Model file: Skill model.
The scanner skillgraph.Discover reads this tree; the leaf dir name is the skill's identity.
skills/
├── vocabulary.cue plain files at the root: ignored by sync (vocabulary.cue is the shared atom registry)
├── <leaf>/ first-level dir holding <leaf>.cue: a skill
│ └── <leaf>.cue
└── <group>/ first-level dir without one: a group directory
└── <leaf>/ subdir holding <leaf>.cue: a skill
└── <leaf>.cue
A dir still holding skill.cue fails the scan.
| File | Holds | Deployed |
|---|---|---|
| <leaf>.cue | Source: canonical CUE, no comments, named after its dir. Frontmatter field list (name, description, author, version, optionally allowed-tools, acdsl-context, plan-template), sections with entries (typed fields on format 3), changelog, optional skill-local atoms. Edit as text; make skill-render SKILL=<name>. | Never; rendered into SKILL.md |
| changelog (in <leaf>.cue) | Only changelog, newest first; frontmatter version equals the newest row (ACDSL-SKILL-001). | Never |
| payloads/<entry-id>.md | [payload] entry fence bodies, exact bytes. | Never |
| smoke/ | Optional. smoke block fixtures. | Never |
| reference files | Optional. Read at run time. | Yes |
| workflows/*.js | Optional. The fronting skill's orchestration scripts (Workflows). | Yes |
| agents/*.md | Optional. Skill-owned agent definitions. | To ~/.claude/agents/ with the skill, not into its dir |
Typed entries in <leaf>.cue, checked by the model on every load and by ACDSL-SKILL-005. Deploy renders each as a heading line, the statement as its own paragraph.
**SKILL-<NAME>-<TOPIC>-NNN[a-z]?** `[role]` **<Title>** <statement>
| Topic | Where |
|---|---|
| Routing and Model | Typed routing, model blocks; make skills-check checks their pipeline edges agree. |
| Inspecting the model | make skill-export SKILL=<name> (JSON). |
| Authoring doctrine | AGENTS.md § Skill authoring. |
| Skill registration and ordering | Skill map. |
One-way, repo → home dirs: each model renders in process and ships with the dir's other files.
| Deployed file | What |
|---|---|
| SKILL.md | Deploy render, formal clauses stripped. |
| help-test.md | How to run the smoke and eval; read only by --help. |
| title.json, enforce.json | Rendered from the model: title.json only with Session helpers installed and the skill's title-set@1 variable set, enforce.json only with Permission gate and heartbeat installed. |
| other files of the dir | Copied. |
| never shipped | <leaf>.cue, payloads/, eval/, smoke/. |
| Case | Sync does |
|---|---|
| selection | Deploys chosen skills whose requires the installed component set meets, each rendered for that set. A skill with an unset required install-scoped variable is skipped unconfigured, the same on every platform. |
| aliases | One copy per declared alias (Aliases). |
| .smine-deployed | Marks every written dir. |
| other installed dirs | Kept, listed. |
| -sync-prune | Moves only marked dirs to the trash, ~/.claude/smine/trash/ (Trash). |
| unmarked or locally modified dir | Under a deployed name: trashed before the write. |
| -sync-variant | Variant rendering. |
| make skill-bundle | Standalone bundle for the empty component set. |
Workflow scripts drive Claude Code's Workflow tool: deterministic multi-agent orchestration. Plain JavaScript, not run under Node: a sandboxed harness interpreter without filesystem, network or Node API access. Scripts are pure control flow; their subagents do all real work.
Bundled with its fronting skill at skills/<group>/<leaf>/workflows/<name>.js, invoked by path, resolved against the skill's base dir (holding its SKILL.md, stated at skill load).
Workflow({scriptPath: '<skill base dir>/workflows/<name>.js', args: ...})
| Rule | Detail |
|---|---|
| Why bundled | Travels with the skill on sync; independent of the working directory. |
| No name mode | {name: ...} deliberately unused: resolves only scripts under .claude/workflows/, which this repo does not maintain. |
| Background | Run ID at once; progress in /workflows, result as a task notification. |
args | Verbatim as a global: real JSON values, not stringified. |
| Entry point | The skill, not the workflow, unless debugging (smine-mine, investigate, railroad-review). |
The only orchestration primitives inside a script:
| Primitive | Does |
|---|---|
| agent(prompt, opts) | Spawns a subagent, awaits its result. opts.schema (JSON Schema) forces structured output, validated and retried at the tool-call layer, returned parsed. null if skipped or terminally dead. |
| parallel(thunks) | Concurrent behind a barrier (waits for all); failed thunks → null. |
| pipeline(items, ...stages) | Per-item stage chains, no inter-stage barrier; default for multi-stage fan-out. |
| phase(title), log(msg) | Progress grouping, UI narration. |
| workflow(nameOrRef, args) | Another workflow inline as a sub-step (saved name or {scriptPath}), sharing the parent's concurrency cap, agent counter, token budget. One nesting level: a child cannot call workflow(). |
| budget | {total, spent(), remaining()}: the turn's token target from a user "+500k"-style directive; hard ceiling, agent() throws once spent. Enables budget-scaled fleets, while (budget.total && budget.remaining() > N) loops. budget.total is null without a target: always guard on it, or the loop runs to the agent cap. |
| agent() option | Effect |
|---|---|
| model, effort | Per call; effort low–max. |
| isolation: 'worktree' | Fresh git worktree; expensive, only for parallel file mutation. |
| agentType | Custom subagent from the Agent-tool registry. |
| label, phase | Progress UI. |
| Constraint | Detail |
|---|---|
| Concurrency | ≤ min(16, cores−2) agents at once, excess queued; lifetime cap 1000 per workflow. |
| Determinism | Date.now(), Math.random(), argless new Date() throw (would break resume). |
| No user input | A workflow cannot pause for it, hence every workflow here is skill-fronted. |
| meta block | Every script opens with a pure-literal export const meta = {name, description, phases}. |
| Resume | Re-invoking with resumeFromRunId replays the unchanged agent() prefix from cache, re-running edited or new calls only. Same script and args: full cache hit. |
"Dynamic workflow" is Anthropic's product name for the whole feature; the official docs apply it to every script, static or not. Useful axis (investigation 2026-07-24, sessions/investigations/baseline-dynamic-workflows.md): dynamic in shape iff the agent() call set is not a pure function of script text plus args.
| Tier | Agent set | In this repo |
|---|---|---|
| T0 static | Fixed at parse time. | Unoccupied; former analyze is now output-gated smine-mine (T2). |
| T1 arg-shaped | From args, before the first agent runs. | railroad-review. |
| T2 output-gated | Spawning depends on agent outputs. | investigate (Stage-B verifier shard count from the deduped claim count), fdesign refute (tie-break agent only on split verdicts). Skill evaluation: headless roots via go run ./cmd/skilleval, no workflow. |
| T3 iterative, convergent | Loop predicate reads outputs or budget: loop-until-dry, budget loops, threshold-gated widening, adversarial multi-verifier voting. | Supported by the tool contract, unoccupied. railroad-review's approve-loop is the dispatcher-driven station protocol, one invocation per round (human gates cannot live in a workflow); the workflow stays T1. |
Determinism is orthogonal: T3 too stays resume-replayable; dynamic means data-dependent, never nondeterministic. No repo script uses budget or a while loop yet; railroad-review uses pipeline() for its per-direction lane→dedup→refute chain.
Authoritative sources, in order:
/deep-research; its Agent SDK TypeScript reference covers tool-invocation params only.workflowSizeGuideline, 2.1.186 agent({schema}) validation-loop fix.Analyze fan-out of /smine-batch, spawned from the root session (/smine dispatcher or direct /smine-batch) after Select planned the batches.
| Part | Contract |
|---|---|
| Script | skills/smine/smine-batch/workflows/mine.js |
| args | {sessions, subagents?, skillDir}: sessions = pending list of make sessions ARGS="pending …"; skillDir = smine-batch base dir with the deployed SKILL.md. Throws on non-object, empty sessions, missing skillDir. |
| Does | One smine-miner per pending session (parallel, effort medium) reads <skillDir>/SKILL.md, follows its 2. Analyze substeps (plus the Subagent mining substeps under subagents); the skill is root-only, never loaded via the Skill tool. Each writes its session record sessions/<repo>/<YYYY-Www>/<id>.json, checked by make sessions ARGS="check <path> --context <transcript>", which merges a Claude session transcript's used-context record. One fan-out level: miners spawn no agents. |
| Returns | {refs[]}, per session {id, path, failed, skipped?, dataGaps?, note?}. |
Planner fan-out of /smine-problems: one smine-planner (effort high) per direction and artifact kind runs that planner skill's plan route, returns {kind, target, change, notes}, writes nothing.
| Part | Contract |
|---|---|
| Script | skills/smine/smine-problems/workflows/plan.js |
| args | {requests[]}, each {candidateId, directionIndex, planner, candidate}; planner ∈ smine-skills, smine-context, smine-routines, smine-acdsl, smine-permissions, else throws. |
| Returns | {plans[]}: request keys plus plan (null if the planner returned nothing). |
Fans out N independent investigations of one open analysis or data question, re-verifies each load-bearing claim against its actual primary source, merges into one baseline with a refuted-hypotheses register. /investigate fronts it, resolving question, inputs, fan-out width. Script: skills/verdict/investigate/workflows/investigate.js.
| Arg | Required | Meaning |
|---|---|---|
| question | yes | String. |
| inputs | yes | String of fetchable sources: paths, live or archived URLs, prod-query targets. |
| artifactsDir | yes | Absolute session-scratchpad path outside every worktree, for investigator artifacts; never the repo. |
| priorArtifact | no | Existing analysis, as investigation #1. |
| investigators | no | Default 3, cap 8. |
Throws on missing question or inputs, missing or non-absolute artifactsDir, investigators over the cap.
| Stage | Does |
|---|---|
| A, Fan-out | investigators general-purpose agents, one parallel() barrier. Each reads inputs first, ranks hypotheses, names the primary source of every load-bearing claim; never reads siblings (anti-anchoring). |
| B, Re-verify (v1.2) | Dedups claims across runs, crediting every raising run; shards of ≤8, one medium-effort verifier each, in parallel. Each fetches every claim's actual primary artifact, never a prior run's summary; rules holds | refuted | needs-measurement, watching the full funnel. Shard verdicts union into one verification register. |
| C, Merge | One high-effort agent writes the baseline: fact-vs-hypothesis labels, refuted-hypotheses register, credited net-new findings, discrimination plan. |
| Measurement gate | needs-measurement claims return as open_measurements with concrete prod queries. Subagents cannot pause for you: the fronting skill surfaces them, re-invokes with resumeFromRunId once your results return as binding facts. |
Returns {investigators, failed, verification, baseline}: surviving investigator outputs, failed run ids, verification register, merged baseline, each per its agent's result schema. No survivor: verification: null, baseline: null.
Fixed artifact filenames, <artifactsDir>/inv-N.md: a second run on the same artifactsDir overwrites the previous reports. Move them before re-invoking.
One station-protocol round, one stage file per spawn under skills/quality/railroad-review/workflows/: review fanned out to n lanes per direction in isolated worktrees; same-defect claims collapsed by lightweight groupers (per direction, then across); every claim second-confirmed by a capped pool of fresh refuters and verifiers; one station review, single review.json handoff; round worktrees and branches cleaned up.
/railroad-review fronts it; multi-agent only (solo removed in v7.0). The dispatcher (the session running the skill) owns everything around the per-round invocations:
{base, head, baseCommit, headCommit, commitsAhead, scope?, riskMap?, chunks?, refute?, ignore?, artifactsDir, diffFiles, round, directions?, lanes?, contextRefs?, focus?, laneModel?, laneEffort?, rejectedFindings?, testPairs, specPaths?}
| Arg | Required | Meaning |
|---|---|---|
| base | yes | Confirmed diff base (string). |
| head | yes | Branch or commit under review. |
| baseCommit | yes | Resolved merge-base fork point of base and head, never the base tip; each worktree verifies it as ancestor. |
| headCommit | yes | Review head, pinned once per round; each worker checks it out before reviewing, or renames onto it when HEAD already equals it. Snapshot scopes (wip, all): the dispatcher's snapshot commit descending from the checkout HEAD, pinned alike. |
| commitsAhead | yes | Positive integer; empty diff: stop and report, no fan-out. |
| artifactsDir | yes | Absolute session-scratchpad path outside every worktree; artifacts under round-{r}/. |
| diffFiles | yes | Changed files, git diff --name-only <baseCommit> <headCommit> narrowed by paths: the coverage baseline. |
| round | yes | 1-based; namespaces artifacts and branch names. |
| testPairs | yes | The round's rules pairs output: test files, each changed file's counterparts. |
| scope | no | Default branch; snapshot scopes wip, all. |
| riskMap | no | Dispatcher's per-file risk tiering (SKILL PROC-007), injected into every lane's attention briefing. |
| chunks | no | Experimental chunked fan-out (SKILL MODES-005): dispatcher-partitioned {name, files[]} array; lanes run per direction × chunk, reading only their chunk; contracts chunk-exempt. Absent: unchunked. |
| refute | no | Loglevel-style severity threshold (SKILL ROUND-007): candidates at or above it get a fresh refuter. blocker, major (default), minor, nit, info, or none: no refuter stage, all claims through the batched verification pool. |
| ignore | no | Ledger threshold (SKILL STATION-004c): claims at or below it ledgered ignored after the gate, hidden there, never fixed or blocking. blocker, major, minor, nit, info, or none (default): all ledgered open. |
| directions | no | Default all but critical, diff-pruned by the dispatcher, from the eight known. Minimum 1; one direction is a valid round. |
| lanes | no | Default 2. |
| focus | with special-focus | For the special-focus direction. |
| laneModel, laneEffort | no | Override for judgment workers: lanes, groupers, refuters, verifiers. |
| stationModel, stationEffort | no | Station's; else opus, high effort. |
| rejectedFindings | no | Rejection ledger content, injected into every lane and the station merge so rejected findings never return. |
| specPaths | no | Dispatcher's spec copies under artifactsDir (round-{r}/spec-<n>-<basename>); other paths throw in a stage. The checklist stage turns them into one correctness checklist grouped per spec. |
Every agent names its model: mechanical (provision, cleanup, build-test) sonnet, low effort; judgment the bracket model or opus.
| # | Stage | Does |
|---|---|---|
| 1 | Fan-out | pipeline() over directions. Per direction lanes railroad-lane-<direction> agents spawn freely; the Workflow runtime runs ≤16 at once, queuing the rest. Each lane: isolated worktree pinned at headCommit, branch claude-review/<runNs>-{direction}-l{i}-r{round}-{hash6} (-a<n> from a re-spawn's second attempt on); review-only (no edits, no plan mode); blind to sibling lanes; walks exactly its direction's checklist from the railroad-review SKILL.md; writes a JSON-only findings artifact under round-{r}/; returns structured findings. |
| 2 | Lane coverage | Read-gate enforced. Before dispatch smine-rules lanes writes a per-lane manifest <artifact>.lane-manifest.json ({artifact, direction, files, partners, root, walk}). The hook denies the lane's artifact write until every manifest file is fully read; the allowed write emits <artifact>.coverage.json, the measured coverage record. coverage_gaps: unfinished lanes' assignments. |
| 3 | Dedup per direction | Lightweight grouper (text-only, no worktree, lane model, low effort) groups same-defect claims; the script assembles survivors deterministically: best-argued, max group severity, merged_from provenance, unplaced claims kept. A finding id used by two lanes gets a lane suffix, no shadowing. |
| 4 | Refutation | Pipelined per direction: each deduped claim at or above the threshold goes to a fresh refuter (worktree, branch claude-review/refute-{finding-id}-r{round}-{hash6}, lane model and effort) briefed to refute it per the skill's Probe protocol (probe or cheapest artifact, both-directions test rule); returns confirmed | debunked | unverified with artifacts. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS caps only the nightly Agent-tool route, never workflow runs. |
| 5 | Cross-direction dedup | One more grouper unions all directions' claims; the script assembles survivors, lists absorbed cross-direction pairs as duplicates, carries refuter verdicts to the survivor. Opposing member verdicts leave it verdict-less. |
| 6 | Verification | Verdict-less claims, severity-descending, in batches of VERIFY_BATCH = 4 to verifiers: refuter prompt verbatim, branch claude-review/verify-b{k}-r{round}-{hash6}. A lost refuter's claim joins a verifier immediately. |
| 7 | Build and tests | smine-rules buildtest at base and head, in the foreground before the round. |
| 8 | Station merge | One barrier agent (stationModel, else the session model, high effort), own worktree forked after the fan-out from the dispatcher's checkout, branch claude-review/station-r{round}-{hash6}. Rules below. |
| 9 | Cleanup | smine-rules cleanup by the dispatcher: worktrees on the run's branch prefix salvaged, removed unforced; each run branch deleted only after its diff is saved. |
| Station rule | Detail |
|---|---|
| Pre-mapped merge | Script drafts the mechanical merge: binding verdicts as draft dispositions, cross-direction duplicates as duplicate-of, probe→fixture→verdict index as draft_probes. The station echoes drafts, judging exceptions only: ledger or known matches, internally inconsistent verdicts, lost-verdict claims (re-read adversarially itself). |
| Dispositions | Exactly one per claim and duplicate: confirmed | unverified | rejected-with-reason | duplicate-of | debunked. |
| Severities | Spec-vs-code conflicts resolve against decisions.md. Severities arrive frozen: lane-assigned, raised at most once by dedup, never re-graded. |
| Outputs | Fix route per confirmed finding (human | auto-fix); permanent checks naming durable guards for recurring finding classes; definition-of-done walk; undemonstrated high-risk suspicions in escalations. |
| Handoff | round-{r}/review.json, the single handoff; no review.md. A session-model agent renders a human-readable version from it on demand. |
| Summary check | Station input travels in the script-built prompt; the station returns a short summary only. The script checks dispositions, funnel, red-build cap, coverage-gap cap: a failed station pin fails the round, no retry; else a violation re-runs the station once to fix review.json in place. |
round.js returns {round, void, station, clean, conservation, corrections, abortedLanes, deadDirections, unsettled, branches}.
| Field | Meaning |
|---|---|
| void | true, no handoff: every planned lane aborted. |
| station | Station stage's return: handoff names round-{r}/review.json; blocking counts NEW confirmed findings MINOR or worse above the ignore level (NIT, INFO never block). |
| clean | Handoff exists, nothing blocks, no lane aborted, funnel lost no claim. |
| branches | Every branch the round created, for cleanup. |
Fixes, fix check and ledgers are dispatcher steps after the round (SKILL Fixes section), not in this return.
Dimension-by-dimension fan-out of /context-bootstrap: one agent per dimension and chunk mines candidate context entries; a verifier pass re-checks them against the tree; the skill renders the report.
| Part | Contract |
|---|---|
| Script | skills/context/context-bootstrap/workflows/context-bootstrap.js |
| args | {dimensions[], lanes?, laneModel?, laneEffort?, repo?, ide?}; each dimension carries its chunk list with a ready-made spec. lanes: parallel miner cap (default 1); repo: read-only foreign checkout; laneModel: must be a generated subagent model. |
| Returns | {confirmed[], refuted[], unverified[]}: candidates by verifier verdict; refuted ones carry a refutation note. |
ground.js: /fdesign's one grounding round, at most agents agents, one per area, answering its questions with path:line facts and stale statements. refute.js: the refute round, two blind refuters over the claim ledger, one tie-break agent over split claims. Both in skills/feature/fdesign/workflows/.
| Script | args | Returns |
|---|---|---|
| ground.js | {base, areas[{area, questions[]}], ide?, agents?, model?, effort?}; more areas than agents throws. | {areas[], empty} |
| refute.js | {planPath, verdictDir, claims[], ide?} | {verdicts[], debunked[], unverified[]}; unverified includes claims whose agents were lost. |
/heartbeat-demo's stage spawning the heartbeat-demo-worker agent, which writes the demo artifact from the producer value; the skill's enforce anchors fire on this launch.
| Part | Contract |
|---|---|
| Script | skills/orchestration/heartbeat-demo/workflows/demo.js |
| args | {value, artifactsDir}: producer's value, scratch dir; either missing throws. |
| Returns | {artifact}: artifact path; null if the worker returned nothing. |
meta.name + .js, at skills/<group>/<leaf>/workflows/; several spawns, one file each (railroad-review).