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:

references/mode-selection.md

references/design-principles.md

references/skill-patterns.md

references/workflow-patterns.md

references/output-patterns.md

references/mode-selection.md

references/examples/*.md

references/synthesis-path.md

references/authoring-path.md

references/description-optimization.md

references/iteration-path.md

references/evaluation-path.md

references/registration-validation.md

Step 1: Resolve target and path

1. Resolve target skill path and intended operation (

   create

   ,

   update

   ,

   synthesize

   ,

   iterate

   ).
2. Read

   references/mode-selection.md

   and select the required path(s).
3. Classify the skill (

   workflow-process

   ,

   integration-documentation

   ,

   security-review

   ,

   skill-authoring

   ,

   generic

   ).
4. Ask one direct question if class 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. Apply trust and safety rules when ingesting external content.
3. Produce source-backed decisions and coverage/gap status.
4. Load one or more profiles from

   references/examples/*.md

   when the skill is hybrid.
5. Enforce baseline source pack for skill-authoring workflows.
6. Enforce depth gates before moving to authoring.

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

Read

references/iteration-path.md

iteration

iterate

1. Capture and anonymize examples with provenance.
2. Re-evaluate skill behavior against working and holdout slices.
3. Propose improvements from positive/negative/fix evidence.
4. 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. Create focused reference files and scripts only when justified.
3. Follow

   references/skill-patterns.md

   ,

   references/workflow-patterns.md

   , and

   references/output-patterns.md

   for structure and output determinism.
4. 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 Codex and Claude.

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

When to Use

Use this skill when tackling tasks related to its primary domain or functionality as described above.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.