skill-generate holds the base every skill is built from: the rules (references/skill-authoring.md) and the templates a new skill is scaffolded from (assets/skill-template.md, assets/action-template.md). Both still teach the format onboard abandoned. Until they are fixed, nothing propagates: a skill generated today copies the old pattern, and every later cleanup has no rule to follow.
The base contradicts the shipped skill
onboard ships the new pattern on next. The template a new skill copies teaches the old one.
|
assets/skill-template.md |
onboard/SKILL.md on next |
| Action table |
# | Action | Role | Input — 4 columns |
# | Action | Does — 3 columns |
| Flow |
a prose sentence |
a mermaid diagram |
| References |
flat, "Plain paths, no @" |
nested: references/state/, order/, run/ |
| Load cost |
nothing |
the entire point |
And the rules say nothing either. Checked on next:
- Zero occurrence of
nested or a references/<group>/ path. R3 still reads "References one level deep", while onboard ships 11 nested references.
- Zero occurrence of
always-on, per path, conditional, or load cost. No rule constrains what one run reads.
- The only size rule is R4:
SKILL.md <= 500 lines — a file ceiling that aidd-orchestrator:00-async-dev clears with a 131-line router while being the heaviest skill in the repo at 1915 lines. It measures a file where the cost lives in a path.
Scope
The rules — references/skill-authoring.md
- Sanction nested references. State when a group earns a directory: a load boundary, not a topic.
- Name the always-on surface: the
description is the only content loaded when a skill is not invoked. Everything else is on demand.
- Replace the R4 file ceiling with a budget on what one run reads, and say how an author measures it.
- State the split rule: split A from B only when a path needs A without B. Co-loaded content stays one file.
The templates — assets/skill-template.md, assets/action-template.md
- Drop the
Input column from the action table; an action's input lives in its own ## Input.
- Show the flow as a schema, not prose.
- Show a nested reference group, so the shape is copied rather than explained.
The skill itself
- 378 lines, 10 files.
skill-authoring.md (64 lines) is read by all five generators, so its weight is paid five times over. tool-paths.md (57 lines) is a lookup table an action reads whole to use one row.
Acceptance criteria
skill-generateholds the base every skill is built from: the rules (references/skill-authoring.md) and the templates a new skill is scaffolded from (assets/skill-template.md,assets/action-template.md). Both still teach the formatonboardabandoned. Until they are fixed, nothing propagates: a skill generated today copies the old pattern, and every later cleanup has no rule to follow.The base contradicts the shipped skill
onboardships the new pattern onnext. The template a new skill copies teaches the old one.assets/skill-template.mdonboard/SKILL.mdonnext# | Action | Role | Input— 4 columns# | Action | Does— 3 columns@"references/state/,order/,run/And the rules say nothing either. Checked on
next:nestedor areferences/<group>/path. R3 still reads "References one level deep", whileonboardships 11 nested references.always-on,per path,conditional, orload cost. No rule constrains what one run reads.SKILL.md <= 500 lines— a file ceiling thataidd-orchestrator:00-async-devclears with a 131-line router while being the heaviest skill in the repo at 1915 lines. It measures a file where the cost lives in a path.Scope
The rules —
references/skill-authoring.mddescriptionis the only content loaded when a skill is not invoked. Everything else is on demand.The templates —
assets/skill-template.md,assets/action-template.mdInputcolumn from the action table; an action's input lives in its own## Input.The skill itself
skill-authoring.md(64 lines) is read by all five generators, so its weight is paid five times over.tool-paths.md(57 lines) is a lookup table an action reads whole to use one row.Acceptance criteria
onboardships, not the old one.onboardalready uses, soonboardstops being a violation of its own contract.skill-generateobeys its own new rules.