author-skills
Author the bodies of a package's stub skills (skills/<name>/SKILL.md) and references (references/<name>.md) from its principles / evidence / source, then promote the package from status: draft to read
SKILL.md.claude/skills/author-skills/SKILL.md
GitHubPurpose
A generated package ships with stubs: cli stubs scaffolds every
knowledge_partition.skills / references entry as a STATUS: STUB placeholder, and nothing
fills them — so packages stay at status: draft forever. This skill is the missing producer:
it authors each stub body grounded in that package's own principles / evidence / source
(not invented), then promotes the package to status: ready. Output is validated by
validate_skill_authoring.py (status-gated) and re-checked by faithfulness + quote-scan.
Input
profile.yaml—knowledge_partition.{skills,references}(what to author),always_on,supported_modes,quality_bar,forbidden_behaviours,status, rights status.- Tier 1+:
principles/principles.yaml(entries whoseoperational_mapping.skill== the slug), theirderived_from_claims→analysis/claims.jsonl→evidence/evidence-records.yaml→source_anchors→ source markdown (viasource_text). - Tier 0: profile
always_on+when_to_use+ source markdown directly (no principle layer).
Procedure
For each stub or status: stale doc (use the same slug generate_stubs chose — see
planned_slugs; a stale doc is one Step 9 flagged because its grounding drifted, re-author it
exactly like a stub):
- Gather grounding. Tier 1+: collect the principle(s) mapped to this slug, their evidence
records, and the cited source anchors. Tier 0: collect the relevant
always_onrules + source. - Author the body from that grounding only:
- Skill (
skills/<slug>/SKILL.md, ≤ 500 lines / 5,000 tokens):## Purpose,## When to use,## Procedure(the repeatable/branching steps that justified extraction),## Inputs,## Output,## References(link sibling reference docs),## Provenance. - Reference (
references/<slug>.md): the actual table / taxonomy / rubric / checklist the entry names, plus a Provenance line. No## Procedure(that is what makes it a reference).
- Skill (
- Set frontmatter to
authored-doc-v1:name,kind,status: ready, andprovenance(principles/claims/source_anchors— real IDs; empty arrays are valid at Tier 0). - Respect rights + faithfulness.
distillation-onlysource → no verbatim (quote-scan must stay green). No statement stronger than its evidence (faithfulness check). - Remove the stub markers (
STATUS: STUB,TODO: author) — astatus: readybody that still contains them fails validation.
When all skills and references are authored:
Stamp the drift baseline so Step 9 can detect future staleness:
python -m tools.subagent_factory.cli stale <slug> --stampThis writes
provenance.authored_from_digest(a sha256 over each body's cited principle + claim statements) into everyreadydoc. Deterministic; run it as the final authoring step.Run
python -m tools.subagent_factory.validate_skill_authoring subagents/<slug>(no FAIL),quote_scan, and faithfulness. Only then set profilestatus: ready, bumpagent_version, add a CHANGELOG entry, and re-export the adapter (cli export <slug>).
Output
Authored skills/<slug>/SKILL.md + references/<slug>.md bodies and a package promoted to
status: ready. Must pass cli validate <slug> (the gate runs validate_skill_authoring
status-gated: with status: ready, every stub remaining is a FAIL).
Caveats
- Derive, do not invent. A Tier 1+ body must trace to the principle/evidence it cites in
provenance. The validator proves shape + mapping; faithfulness + quote-scan guard substance. - Author the agent one file at a time via the
skill-authoragent (itsWriteis locked to the single target file). Thestatus: draft → readyflip is done here, under the gate — never by the per-file agent. - Opt-in. Default authoring runs at release / on request, not on every campaign PDF (cost: one LLM pass per skill + reference).
stalestatus (source drift, Phase 12) re-opens a body for re-authoring; clear it by re-running this skill.