Toolbox skills are adjacent, independently complete roles. They compose through user intent, layered prompts, and shared conversation state. A skill does not invoke a peer skill or depend on a peer package.
Give each judgment one owner. Overlap is limited to the evidence needed at a seam.
| Role | Owned question | Exit state |
|---|---|---|
| Understand | What happens, in what causal order, and why? | Covered, skipped, and uncertain areas are explicit. |
| Judge and own | Does the work fit the developer's preferences and intent? | Each area is accepted, changed, skipped, or uncertain. |
| Transform | How does an accepted target replace the current shape safely? | One bounded change is proven and old residue is handled. |
The current skills that own these roles are listed in the hub taxonomy. Keep that mapping outside skill bodies.
A role receives an exact Surface, the active causal position, settled decisions, and material uncertainty. It returns its own exit state in conversation or in the artifact. The next role starts from that state without restarting settled work.
Source drift invalidates evidence, not accepted intent. Rebind the Surface, recheck affected anchors, and resume at the same causal position.
- A skill body owns its complete operating contract and works when installed alone.
- Frontmatter describes its trigger, result, and nearest non-goals. The description is the routing interface.
- Stable cross-cutting vocabulary lives in
references/and is reached through a GitHub raw pointer. - Skill-local references contain only details owned by that skill.
- Peer skill trees are not shared libraries. Do not link to a peer
SKILL.mdor peerreferences/path. - Layered skills apply their own contracts to the same Slice, Artifact, Surface, or Seam. They do not command one another.
- Tool, platform, and permission requirements remain explicit at the action that needs them.
| Primitive | Meaning | Examples |
|---|---|---|
| Slice | Bounded work unit | src/auth/**, plan section, feature slug |
| Artifact | Written object on disk or in the thread | plan, PRD, ADR draft, pasted proposal |
| Surface | Bound material under examination | branch, PR, paths, snapshot, document |
| Lens | Review or critique stance | security, brand fit, premises |
| Seam | Public test boundary | module API, CLI entry, HTTP handler |
| Repro | On-demand failing signal | test command, CI log, reproduction steps |
| Closure | The active role considers its work settled | understood, accepted, proven, transferred |
- Give each active role the minimum relevant facts, sources, and success criteria.
- Prefer paths, URLs, section names, and other pointers when the source remains available.
- Omit empty fields and unrelated conversation history.
- Keep independent first passes free from sibling conclusions.
- Narrow an oversized Slice at a real ownership boundary.
Load this reference only when skill ownership, composition, or dependency placement is in question.