0b95ad0765
The skill entry is rebuilt around how an agent reads: SKILL.md is a 94-line router whose route table gives the batch to read for each workflow; the first batch is 488-881 compiled lines (was a median of 1,493). Long workflows are split into role pages (single-part 1157 -> outline + role pages, drawing-reconstruction 586 -> outline + stage pages); ql-playbook and notebook-runtime are split by job. Every workflow has Read now / Read when / Unattended mode, and discipline/operating-modes.md says what replaces each gate when nobody can answer. New: scan-reconstruction workflow, core-rules.md (rule IDs), parallel-read blocks for claudecode, zcode, opencode and codex. docs/skill-design.md is the contract; skillbuild --check enforces it (src/simplecadapi/skill/lint.py, opt in through [lint] in skillproj.toml). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
137 lines
8.0 KiB
Markdown
137 lines
8.0 KiB
Markdown
# The skill: design contract
|
|
|
|
`docs/skill/` is the skill an agent loads to use SimpleCADAPI. This file is the contract its pages follow. The rules here
|
|
are checked by `python tools/skillbuild.py --check` (see "Checks"), so a page that breaks one fails the build.
|
|
|
|
## What the skill optimises for
|
|
|
|
1. **Few agent turns.** An agent reads what a step needs in **one parallel batch** and then works. Pages are small and
|
|
have one job so they can be loaded separately, and the router tells the agent which pages belong together.
|
|
2. **A small reading budget.** The first batch of any route is at most **1,200 compiled lines** (router, the two
|
|
always-read pages, the workflow page and its `Read now` files); every later batch stays under the same bound. (Measured before this design: a median of 1,493 lines and 7 files read before the first write, p90 2,501
|
|
lines and 20 files.)
|
|
3. **One home for each rule.** A rule is stated once, with its reason; other pages link to it.
|
|
4. **Two modes.** Every workflow runs interactive or unattended (`references/discipline/operating-modes.md`).
|
|
5. **Four curated targets.** The skill compiles to seven harness targets; `zcode`, `opencode`, `claudecode` and `codex` are
|
|
written for. `omp`, `dsh` and `kimicode` are compiled from the same sources and must pass the checks, with generic wording.
|
|
|
|
## The layers
|
|
|
|
```text
|
|
SKILL.md router: start here, route table with read sets, always-on rules (<= 130 lines)
|
|
references/workflows/ one lifecycle per task; each has Read now / Read when / Unattended mode
|
|
references/workflows/<name>/ the role or stage pages of a long workflow, loaded when the role starts
|
|
references/domains/ capabilities (what the SDK offers for a kind of task)
|
|
references/discipline/ reasoning, invariants, rules (core-rules, operating-modes, the notebook rules ...)
|
|
references/docs/guides/ how the runtime works
|
|
references/docs/api|stdlib|core/ generated signatures (never hand-edited)
|
|
```
|
|
|
|
## Page contracts
|
|
|
|
**Every hand-written page** (everything but `docs/api`, `docs/stdlib`, `docs/core`) is at most **300 lines** (`SKILL.md`
|
|
at most **130**). A longer page is split by job, not trimmed. The one exception is a versioned run contract (its first lines
|
|
say `Contract ID:`), which an external harness reads whole.
|
|
|
|
**Domain and discipline pages** open, within their first 8 lines, with `**Read when:** <the trigger>.` Nothing else is
|
|
required of their body.
|
|
|
|
**Workflow pages** (`references/workflows/*.md`) have these sections, with exactly these headings:
|
|
|
|
```markdown
|
|
## Read now (one parallel batch)
|
|
| File | Why |
|
|
| --- | --- |
|
|
| `domains/requirement-refinement.md` | ... |
|
|
|
|
## Read when
|
|
| When | File |
|
|
| --- | --- |
|
|
| a Role starts | `workflows/<name>/role-1-....md` |
|
|
|
|
## Unattended mode
|
|
| Interactive gate | Unattended replacement |
|
|
| --- | --- |
|
|
| Role 1 consent gate | ... |
|
|
```
|
|
|
|
- `Read now` lists every file the first batch needs besides the always-read pages, **including the workflow's own role-1/first-stage page**; paths are
|
|
written relative to `references/` (for example `domains/part-modeling.md`) and in backticks, one per table row.
|
|
- `Read when` lists everything else with its trigger; nothing is read "just in case".
|
|
- `Unattended mode` has one row for **every** place the workflow asks a person, waits for one, or needs a second reviewer
|
|
(search the old text for `⛔`, "ask", "user", "consent", "confirm", "question", "review"), using the replacements in
|
|
`discipline/operating-modes.md`. A workflow with no such place says so in one sentence.
|
|
- `core-rules.md` and `operating-modes.md` are read on every route (the router says so), so `Read now` does not list them.
|
|
- The compiled lines of `SKILL.md` + `core-rules.md` + `operating-modes.md` + the workflow page + its `Read now` files are at
|
|
most **1,200** (checked per target; the lint prints the sizes with `--read-budget`).
|
|
|
|
**The router's route table** repeats the workflow page plus its `Read now` set in its own column, so an agent can issue the batch
|
|
straight from the table without opening the workflow first. The two must agree (checked).
|
|
|
|
## Parallel reading
|
|
|
|
The router tells the agent to read a batch in one go. How is per target (compile blocks in `SKILL.md`):
|
|
|
|
- `claudecode`, `zcode`: all `Read` calls of the batch in one message.
|
|
- `opencode`: all `read` calls of the batch in one response.
|
|
- `codex`: one shell command that prints the batch: `cd <skill dir> && tail -n +1 a.md b.md c.md` (each file is preceded by a
|
|
`==> name <==` header).
|
|
- `omp`, `dsh`, `kimicode`: the generic sentence ("request the whole batch together if your tools allow it").
|
|
|
|
Pages that name API pages for a step list them as one batch too (`Read now` / a `Read when` row), never "read as needed".
|
|
|
|
## Splitting and merging rules (no loss)
|
|
|
|
- **Move, do not rewrite.** When a long page is split, each rule, table row, example, checklist item and `skill:if` block
|
|
survives in exactly one new page (or is deleted as a verbatim duplicate of text kept elsewhere, and the report says
|
|
where). Changing meaning is a separate, labelled edit.
|
|
- The old page's name stays as the outline (workflow or guide) so links keep working; the outline links to the new pages.
|
|
- Stable file names are in the file map below. Cross-links between owners only use the names listed there.
|
|
|
|
## File map
|
|
|
|
Names in **bold** are new.
|
|
|
|
```text
|
|
SKILL.md
|
|
references/README.md generated tables + this layering
|
|
references/SDK_OVERVIEW.md, ql-playbook.md, scadpkg-format.md
|
|
**references/ql-recipes.md** the recipes split out of ql-playbook.md
|
|
references/workflows/
|
|
single-part-modeling.md outline, Role 5 (export), failure routes
|
|
single-part-modeling/**role-1-requirements.md, requirements-template.md, role-2-plan.md,
|
|
role-3-verifier.md, verifier-contract-patterns.md, role-4-build.md**
|
|
assembly-product-build.md step-reconstruction.md engineering-drawing.md export-and-translation.md
|
|
**scan-reconstruction.md** a mesh, point cloud or images as the source
|
|
drawing-reconstruction.md outline
|
|
drawing-reconstruction/**(role / stage pages, the owner chooses the names)**
|
|
references/domains/ the 11 existing pages (drawing-inspection may gain a template page)
|
|
references/discipline/
|
|
**core-rules.md** **operating-modes.md** feature-tree-convention.md notebook-cell-design.md feature-ordering.md
|
|
geometric-validation.md datums-and-coordinate-systems.md mechanical-modeling.md manufacturing-boundaries.md
|
|
assembly-positioning.md failure-and-repair.md requirement-and-cad-brief.md verifier-scripts.md
|
|
references/docs/guides/
|
|
notebook-runtime.md run, parameters (<= 300 lines)
|
|
**notebook-composition-and-cache.md** composing notebooks, the cell cache, library parts
|
|
**product-export.md** package export, downstream targets
|
|
```
|
|
|
|
## Checks (`tools/skillbuild.py --check`, tests in `test/test_skill_lint.py`)
|
|
|
|
1. every path a page names (backticked or in a link, under `references/`) exists;
|
|
2. `references/README.md` lists exactly the workflows, domains and discipline pages that exist;
|
|
3. every hand-written page is reachable from `SKILL.md` through links;
|
|
4. line limits (300 per page, 130 for `SKILL.md`);
|
|
5. every workflow has the three sections above and every domain/discipline page has `**Read when:**`;
|
|
6. the route table's read set equals the workflow's `Read now` set;
|
|
7. the read budget (1,200 compiled lines, see "Workflow pages") for each route and each target;
|
|
8. the four curated targets' compiled `SKILL.md` contains the parallel-read instruction;
|
|
9. no unresolved `skill:if` / `skill:endif`.
|
|
|
|
## Changing the skill
|
|
|
|
Run `python tools/skillbuild.py --check`. To see what a harness gets, `python tools/skillbuild.py --target opencode`
|
|
(output goes to `skills/simplecadapi-opencode/`, which git ignores). Behaviour is measured, not assumed: the
|
|
agents' traces (Langfuse) give the lines read before the first write and the rules broken; a change that adds reading
|
|
needs a reason in its commit message.
|