Writing Skills

Red Flags — STOP

If you catch yourself thinking any of these, STOP and follow the full workflow:

Reference Materials

• reference/conventions.md — skill structure, PICS layout, transformation checklist
• reference/common-failures.md — failure patterns, anti-patterns, fixes
• reference/output-format.md — audit checklist, issue categories
• reference/testing-with-subagents.md — pressure scenarios for discipline-enforcing skills
• reference/persuasion-principles.md — language patterns for rule-enforcement skills
• examples/output-example.md — concrete output example
• examples/canonical-skill.md — annotated skill demonstrating all conventions

Workflow

1. Select Mode

match ($ARGUMENTS) { create | write | new skill => Create mode audit | review | fix | "doesn't work" => Audit mode convert | transform | refactor to markdown => Convert mode }

2. Check Duplicates (Create mode only)

Search existing skills:

1. Glob: plugins/*/skills/*/SKILL.md
2. Grep description fields for keyword overlap.
3. If >50% functionality overlap: propose updating existing skill instead.
4. If <50%: proceed with new skill, explain justification.

3. Create Skill

1. Run step 2 (Check Duplicates).
2. Determine skill type (Technique, Pattern, Reference, Coordination).
3. Read reference/conventions.md for current conventions.
4. Write SKILL.md following PICS + Workflow structure.
5. Run step 6 (Verify Skill).

4. Audit Skill

1. Read the skill file and all reference/ files.
2. Read reference/output-format.md for audit checklist.
3. Identify issue category and root cause, not just symptoms.
4. Propose specific fix.
5. Test fix via subagent before proposing — don't just analyze.
6. Run step 6 (Verify Skill).

5. Convert Skill

1. Read existing skill completely.
2. Read reference/conventions.md for the transformation checklist.
3. Apply each checklist item.
4. Verify no content/logic was lost in transformation.
5. Run step 6 (Verify Skill).

6. Verify Skill

Verify frontmatter: Read first 10 lines — valid YAML? name + description present?

Verify structure: Grep for ## headings — PICS sections present?

Verify size: Line count < 500? If not, identify content to externalize.

Verify conventions: Read reference/conventions.md and check compliance.

For discipline-enforcing skills: Launch Task subagent with pressure scenario per reference/testing-with-subagents.md.

7. Present Result

Format report per reference/output-format.md.

Entry Point

match (mode) { Create => steps 2, 3, 7 Audit => steps 4, 7 Convert => steps 5, 7 }