| name | skill-authoring |
| description | Apply this pack's normative skill-design contract to create, consolidate, or review canonical skills. Use when authoring a SKILL.md, choosing an archetype, or running the pack acceptance gate. |
Skill Authoring
The four files under references/ are the pack's single normative skill-design contract. Repository instructions outrank this contract, and the contract outranks a golden example when they differ. For A32, the accepted pilot artifacts are reports/pilot/herdr.md and reports/pilot/code-quality.md; current package copies are not the examples.
Route
Select one mode first and read only its reference. Read validation-and-acceptance.md before declaring a package complete.
| Mode | Select when | Read |
|---|
existence-and-ownership | deciding whether an idea earns a slot, cut, or merge target | references/existence-and-ownership.md |
package-and-routing | writing frontmatter, active instructions, modes, references, or a router | references/package-and-routing.md |
evidence-and-safety | handling volatile facts, private topology, paths, secrets, scripts, or operational rules | references/evidence-and-safety.md |
validation-and-acceptance | checking a completed package, archive, collision matrix, or composition boundary | references/validation-and-acceptance.md |
Workflow
- Read the repository instructions and establish the canonical owner before editing prose.
- Select exactly one mode from the table; use a second mode only where its decision surface is required.
- Ensure the pre-rewrite original of every touched skill is committed to git before changing it.
- Keep
SKILL.md to routing, shared workflow, non-default rules, stops, output, and selected-reference conditions.
- Run
bin/validate-skill.sh <skill-dir> <archetype> from the repository root and record its literal result.
- Produce an acceptance report with the collision matrix, A01--A35, preservation ledger, the pre-rewrite git ref, and the correct package-versus-catalog verdict.
Hard rules
- Treat the four references as one contract, not optional advice or independent rule sets.
- If two references disagree, stop and reconcile this directory before accepting a package; historical reports never override it.
- Do not create a standing skill for generic knowledge, a compatibility alias, or a one-off setup note; cut it or merge its delta into the named owner.
- Verify volatile behavior from repository state, live help/status, then primary documentation; do not mirror public manuals or API matrices.
- Never put secret values, literal personal-home paths, or guessed machine facts in canonical content.
- Do not edit
manifest.json, providers/, or installed views unless the task explicitly includes composition; provider trees are symlink farms rebuilt by bin/link, never edited by hand.
Output
Report the canonical owner, chosen archetype, selected modes or targets, pre-rewrite git ref, validation result, acceptance evidence, and whether the result is PACKAGE-CONFORMS, CATALOG-CONFORMS, or blocked.
