writing-skills

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 }