skill-writer

Skill Writer

Use this as the single canonical workflow for skill creation and improvement. Primary success condition: maximize high-value input coverage before authoring so the resulting skill has minimal blind spots.

Load only the path(s) required for the task:

Task	Read
Set skill class and required dimensions	references/mode-selection.md
Apply writing constraints for depth vs concision	references/design-principles.md
Decide what belongs in SKILL.md vs reference files	references/reference-architecture.md
Create or update a skill maintenance specification	references/spec-template.md
Select structure pattern for this skill	references/skill-patterns.md
Select workflow orchestration pattern for process-heavy skills	references/workflow-patterns.md
Select output format pattern for deterministic quality	references/output-patterns.md
Choose workflow path and required outputs	references/mode-selection.md
Find high-signal source material, including history	references/source-discovery.md
Load representative synthesis examples by skill type	references/examples/*.md
Synthesize external/local sources with depth gates	references/synthesis-path.md
Author or update SKILL.md and supporting files	references/authoring-path.md
Optimize skill description and trigger precision	references/description-optimization.md
Iterate using positive/negative/fix examples	references/iteration-path.md
Store improvement evidence for future iterations	references/iteration-evidence.md
Evaluate behavior and compare baseline vs with-skill (opt-in quantitative)	references/evaluation-path.md
Register and validate skill changes	references/registration-validation.md

Step 1: Resolve target and path

1. Resolve target skill root and intended operation (create, update, synthesize, iterate).
2. Inspect workspace prior art before choosing where the skill belongs:
   • existing skill directories and neighboring skills
   • repository docs such as AGENTS.md, README.md, and CONTRIBUTING.md
   • plugin manifests or other layout-defining files when present
3. Choose the target skill root from observed conventions:
   • default to .agents/skills/<name>/
   • if the workspace clearly uses another established layout, follow that layout instead
   • common established alternatives include skills/<name>/ when the workspace uses a canonical root skill tree, .claude/skills/<name>/, plugins/<plugin>/skills/<name>/, or another repo-managed skill root with clear prior art
4. If multiple plausible locations exist and the canonical one is still unclear after inspection, ask the user where the skill should go before editing files.
5. Distinguish skill-internal paths from repo registration paths:
   • inside a skill, reference bundled files relative to that skill root (for example references/foo.md, scripts/check.py)
   • for repository registration edits, use the repository's actual canonical files/locations after inspecting the workspace
6. Read references/mode-selection.md and select the required path(s).
7. Classify the skill (workflow-process, integration-documentation, security-review, skill-authoring, generic).
8. Ask one direct question if class, target location, or depth requirements are ambiguous; otherwise state explicit assumptions.

Step 2: Run synthesis when needed

Read references/synthesis-path.md.

1. Collect and score relevant sources with provenance.
2. Read references/source-discovery.md when source material is thin, stale, or ambiguous.
3. Apply trust and safety rules when ingesting external content.
4. Produce source-backed decisions and coverage/gap status.
5. Load one or more profiles from references/examples/*.md when the skill is hybrid.
6. Enforce baseline source pack for skill-authoring workflows.
7. Enforce depth gates before moving to authoring.

Step 3: Run iteration first when improving from outcomes/examples

Read references/iteration-path.md first when selected path includes iteration (for example operation iterate).

1. Capture and anonymize examples with provenance.
2. Read references/iteration-evidence.md when examples should persist beyond the current turn.
3. Re-evaluate skill behavior against working and holdout slices.
4. Propose improvements from positive/negative/fix evidence.
5. Carry concrete behavior deltas into authoring.

Skip this step when selected path does not include iteration.

Step 4: Author or update skill artifacts

Read references/authoring-path.md.

1. Write or update SKILL.md in imperative voice with trigger-rich description.
2. Read references/reference-architecture.md before adding bulk instructions or new reference files.
3. Create or update SPEC.md using references/spec-template.md when creating a new skill or materially changing an existing skill's intent, sources, evaluation, or maintenance model.
4. Create focused reference files and scripts only when justified.
5. Follow references/skill-patterns.md, references/workflow-patterns.md, and references/output-patterns.md for structure and output determinism.
6. For authoring/generator skills, include transformed examples in references:
   • happy-path
   • secure/robust variant
   • anti-pattern + corrected version

Step 5: Optimize description quality

Read references/description-optimization.md.

1. Validate should-trigger and should-not-trigger query sets.
2. Reduce false positives and false negatives with targeted description edits.
3. Keep trigger language generic across providers unless the skill is intentionally provider-specific.

Step 6: Evaluate outcomes

Read references/evaluation-path.md.

1. Run a lightweight qualitative check by default (recommended).
2. For integration/documentation and skill-authoring skills, include the concise depth rubric from references/evaluation-path.md.
3. Run deeper eval playbook and quantitative baseline-vs-with-skill only when requested or risk warrants it.
4. Record outcomes and unresolved risks.

Step 7: Register and validate

Read references/registration-validation.md.

1. Apply repository registration steps for the active layout you verified in the workspace.
2. Run quick validation with strict depth gates.
3. Reject shallow outputs that fail depth gates or required artifact checks.

Output format

Return:

1. Summary
2. Changes Made
3. Validation Results
4. Open Gaps