skill-writer is the canonical workflow for creating, updating, synthesizing, and iteratively improving agent skills in this repository.
Its primary purpose is to prevent shallow skill authoring by forcing high-value source coverage, explicit provenance, focused runtime instructions, and validation before completion.
It is also a meta-router: before authoring, it must choose the simplest adequate execution shape for the target skill and only then decide which artifacts are needed.
New skill creation from local, external, or mixed sources.
Existing skill updates that affect runtime behavior, structure, trigger precision, references, or validation.
Research-first synthesis for proposed skills.
Iteration from positive examples, negative examples, review feedback, validation results, and observed agent behavior.
Registration and validation for this repository’s canonical skills/<skill-name>/ layout and other discovered layouts.
Choosing between execution shapes such as inline guidance, reference-backed expert, script-backed workflow, router, subagent-fork, hook-backed, asset-template, or hybrids.
Assessing when provider-specific mechanics are justified and documenting portability constraints.
Out of scope:
Acting as the runtime instructions for the skills it creates.
Storing full source inventories, raw examples, or changelog history directly in SKILL.md.
Replacing repository-level instructions in AGENTS.md, README.md, or CONTRIBUTING.md.
Creating per-skill aliases or symlink skills in this repository.
Guaranteeing compatibility with provider-specific skill extensions unless they are explicitly scoped and documented.
Primary users: agents and humans authoring or maintaining reusable agent skills.
Common user requests: “create a skill”, “write a skill”, “update this skill”, “improve from examples”, “synthesize a skill from docs”, “maintain skill docs”, or “validate/register this skill”.
Should not trigger for: ordinary code review, generic documentation edits, PR writing, commit creation, or implementation work that does not create or modify an agent skill.
Runtime references should be direct children of references/; use filename prefixes for related leaves and list every bundled reference directly from SKILL.md.
references/evidence/ contains durable positive/negative examples when future iterations need them.
scripts/ contains validation automation.
assets/ is unused unless a future skill-authoring workflow needs static templates or media.
EVAL.md, evals/axis.config.json, and evals/scenarios/ test changes to skill-writer itself. Keep eval files outside runtime SKILL.md routing.
Skill evals use AXIS as the open source harness, with AXIS’s built-in codex adapter exercising the Codex codex exec --json path rather than a repo-local runner script.
The validator checks only structural requirements and a high-threshold advisory size warning; it cannot prove that a generated skill is semantically complete.
The validator intentionally does not classify skills, parse source coverage, enforce SPEC headings, judge trigger quality, or exhaustively validate provider-specific optional frontmatter fields.
Semantic evaluation requires representative cases and reviewer judgment; it is not fully automated by the structural validator.
Prose density, source adaptation quality, advanced-shape contracts, and precision rely on authoring judgment and review.
Source discovery can still miss private operational knowledge if it is not present in local files, accessible issue/PR history, or supplied context.
Provider-specific skill extensions may drift; skill-writer treats them as compatibility guidance unless a skill is intentionally provider-specific.
Update SKILL.md when the required runtime workflow, branch conditions, or output contract changes.
Update references/execution-shapes.md when new skill mechanics or orchestration patterns become important.
Update the relevant flat file under references/ when a specific routed leaf changes.
Update SPEC.md when intent, scope, user/trigger context, evidence model, validation expectations, limitations, or maintenance rules change.
Update SOURCES.md when source inventory, decisions, coverage, gaps, or changelog entries change.
Update references/evidence/ when preserving examples for future iteration or regression tracking.
Update EVAL.md, evals/axis.config.json, and evals/scenarios/ when eval case format, rubric dimensions, AXIS settings, or regression cases for skill-writer change.