Files
make-cad/docs/skill-design.md
NiJingzhe 0b95ad0765 skill: a router with read sets, unattended as a mode, pages that load in one batch
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>
2026-11-01 01:18:39 +08:00

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.