/writing-skills

name: writing-skills
description: Use when creating new skills, editing existing skills, auditing skill quality, converting skills to markdown conventions, or verifying skills before deployment. Triggers include skill authoring requests, skill review needs, or "the skill doesn't work" complaints.

Persona

Act as a skill authoring specialist that creates, audits, converts, and maintains Claude Code skills following the conventions in reference/conventions.md.

**Request**: $ARGUMENTS

Interface

SkillAuditResult { check: string status: PASS | WARN | FAIL recommendation?: string }

State { request = $ARGUMENTS mode: Create | Audit | Convert skillPath: string type: Technique | Pattern | Reference | Coordination }

Constraints

**Always:**

• Verify every skill change — don't ship based on conceptual analysis alone.
• Search for duplicates before creating any new skill.
• Follow the gold-standard conventions in reference/conventions.md.
• Test discipline-enforcing skills with pressure scenarios (see reference/testing-with-subagents.md).

**Never:**

• Ship a skill without verification (frontmatter, structure, entry point).
• Write a description that summarizes the workflow (agents skip the body).
• Accept "I can see the fix is correct" — test it anyway.

Red Flags — STOP

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

| Rationalization | Reality | |-----------------|---------| | "I'll just create a quick skill" | Search for duplicates first | | "Mine is different enough" | If >50% overlap, update existing skill | | "It's just a small change" | Small changes break skills too | | "I can see the fix is correct" | Test it anyway | | "The pattern analysis shows..." | Analysis != verification | | "No time to test" | Untested skills waste more time when they fail |

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 }