/skill-writer

Skill Writer Specification

Intent

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.

Scope

In scope:

• 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.

Users And Trigger Context

• 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 Contract

• Required first actions:
  • Resolve the target skill root and operation.
  • Inspect local repository conventions before deciding where files belong.
  • Classify the skill and select the minimum required workflow paths.
  • Select a primary execution shape and default to the simplest adequate option.
  • Keep validation lightweight and structural unless project conventions require more.
• Required outputs:
  • Summary.
  • Changes Made.
  • Validation Results.
  • Open Gaps.
• Non-negotiable constraints:
  • SKILL.md frontmatter is first line and name matches the directory.
  • description contains realistic trigger language.
  • SKILL.md remains an orchestration/index layer for complex skills.
  • Runtime guidance should prefer dense structures such as tables, checklists, templates, and examples over explanatory prose.
  • Material skill changes explicitly name the selected execution shape.
  • Advanced mechanics are justified and include portability notes.
  • Supporting runtime references are focused, flat under references/, listed in SKILL.md, and loaded conditionally.
  • Source provenance and decisions live in SOURCES.md.
  • Durable positive/negative examples live in references/evidence/.
  • SPEC.md records the maintenance contract for new or materially changed skills.
  • Lightweight structural validation runs before completion.
  • A post-change precision pass runs after any skill artifact change.
  • Semantic output quality is evaluated with repo-level evals rather than encoded in the structural validator.
• Expected bundled files loaded at runtime:
  • references/mode-selection.md
  • references/execution-shapes.md
  • references/synthesis-path.md
  • references/iteration-path.md
  • references/authoring-path.md
  • references/reference-architecture.md
  • references/spec-template.md
  • references/description-optimization.md
  • references/registration-validation.md
  • references/source-adaptation.md
  • references/skill-evals.md
  • flat references/*.md files listed in SKILL.md
  • scripts/quick_validate.py

Source And Evidence Model

Authoritative sources:

• Local skill-writer runtime files: SKILL.md, references/**/*.md, scripts/quick_validate.py.
• Repository policy: AGENTS.md, README.md, CONTRIBUTING.md, plugin manifests, and registration settings.
• Agent Skills specification and official skill authoring guidance.
• Current official provider docs for any provider-specific mechanics being recommended.
• Official orchestration guidance for routing, delegation, and reasoning-model planning patterns.

Useful improvement sources:

• positive examples: successful generated skills, review-approved skill changes, and validation passes that demonstrate desired behavior
• negative examples: shallow generated skills, overloaded SKILL.md files, catch-all references, missing provenance, failed validation, false triggers, or review feedback
• commit logs/changelogs: repeated fixes, reversions, migrations, and changes that explain why a rule exists
• issue or PR feedback: reviewer comments about missing coverage, confusing trigger language, poor file placement, or insufficient validation
• validation results: structural checks, review findings, and observed behavior from real skill use

Data that must not be stored:

• secrets, credentials, or tokens
• raw customer data
• private URLs or identifiers that are not needed for reproduction
• large copied source documents or long copyrighted excerpts
• unredacted personal data from examples, logs, issues, or commits

Reference Architecture

• SKILL.md contains the top-level workflow, path-loading table, branch points, universal constraints, and output contract.
• SKILL.md acts as a meta-router for the authoring process: class selection, shape selection, and path selection happen before writing.
• SPEC.md contains this maintenance specification.
• SOURCES.md contains source inventory, decisions, coverage matrix, open gaps, and changelog.
• references/ contains focused flat workflow guidance, routed leaf references, templates, rubrics, and class-specific authoring requirements.
• 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.

Validation

• Lightweight validation:
  • Run uv run skills/skill-writer/scripts/quick_validate.py skills/skill-writer.
  • Inspect changed references for focused scope, direct discoverability, and absence of host-specific paths.
  • Verify that the selected execution shape is explicit and that advanced mechanics, if any, are justified.
  • Run the post-change precision pass and summarize what was replaced, narrowed, moved, deleted, or added with reason.
• Holdout examples:
  • Keep durable holdout examples in references/evidence/holdout-set.md when repeated regressions appear.
  • Do not tune directly against holdout examples until they are intentionally moved to the working set.
• Acceptance gates:
  • Validator passes with no errors.
  • New or changed workflow rules are represented in the correct artifact.
  • SOURCES.md records source-backed decisions and any remaining gaps.
  • SPEC.md is updated when intent, scope, evidence model, validation, or maintenance expectations change.

Known Limitations

• 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.

Maintenance Notes

• 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.