writing-skills

name	writing-skills
description	Creates and improves Claude Code skills following the official Anthropic spec and house standards. Use when creating new skills, modifying existing skills, or improving skill quality. Use when user says "create a skill", "write a skill", "add capability". Use when a repeated pattern should become reusable.

Writing Skills

Overview

Writing skills IS structured documentation creation for process guidance.

Analyze requirements clearly, design skill structure thoughtfully, implement with precision, validate functionality, and iterate based on feedback.

Core principle: Clear requirements and structured design lead to effective skills that truly guide agent behavior.

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks: 0. Fetch latest official skill spec

1. Analyze requirements
2. Design skill structure
3. Implement SKILL.md
4. Add references (if needed)
5. Validate structure
6. REFACTOR - quality review
7. Test with real usage

Announce: "Created 8 tasks (0–7). Starting execution..."

Skill Creation Process

Phase	Focus	What You Do
Requirements	Understanding	Analyze what capability is needed and why
Design	Structure	Plan skill organization, triggers, and content
Implementation	Creation	Write skill following design and best practices
Validation	Testing	Verify skill works correctly in real scenarios
Improvement	Refinement	Iterate based on feedback and usage patterns

Task 0: Fetch Latest Official Spec

Goal: Pull the current Anthropic skill spec before designing — never trust cached memory.

Action:

Skill tool: fetching-claude-docs
  component: skill
  question: "frontmatter fields (name, description), description trigger
             format, SKILL.md structure, references/ progressive disclosure,
             skill activation"

Verification: Received YAML with source: https://code.claude.com/docs/en/skills.md and non-empty spec_excerpt. Use as authoritative reference; if any rule in this SKILL conflicts with the fetched spec, the fetched spec wins.

Task 1: Analyze Requirements

Goal: Understand what skill to create and why. Present full analysis to user for confirmation.

Analyze and answer ALL questions below:

• What capability does this skill teach?
• What triggers should activate it? (specific phrases, symptoms)
• Is this reusable across projects, or project-specific?
• Does a similar skill already exist?
• What are the key design decisions? List alternatives considered and chosen approach with rationale.

External search (optional): If claude-skills-mcp available, search for existing community skills to adapt.

MANDATORY: Present analysis to user. Display ALL answers above in full detail, then ask user to confirm before proceeding. Do NOT summarize into a single sentence. Do NOT skip to next task without explicit user approval.

Verification: User has reviewed the full analysis and confirmed the direction.

Task 2: Design Skill Structure

Goal: Plan the skill's organization, triggers, and content.

Before drafting, walk through prompt-design-principles.md:

• 5-skeleton framework — every skill needs Role, Scope, Workflow, Standards, Completion. Confirm each has concrete content planned.
• Failure-mode reverse engineering — the Red Flags section should reflect specific failures you've observed or can predict, not generic warnings.
• Conditional dispatch — list task variants the skill handles and per-variant behavior before writing absolute rules.
• Creative-constraint balance — explicitly decide what can vary (form, solution options) vs. what must be fixed (process, verification, tool order).
• Completion semantics — the final task must have a binary pass/fail check, not a narrative "done" signal.

Design considerations:

1. What specific capability does this skill provide?
2. When should the skill be triggered? (specific phrases, symptoms)
3. What are the key tasks and workflow steps?
4. What supporting materials are needed? (references, examples)

Structure planning:

• Clear trigger conditions in description
• Logical task sequence
• Verification criteria for each task
• Red flags and common mistakes

Verification: Have clear design plan with triggers, tasks, and structure defined.

Task 3: Implement SKILL.md

Goal: Create the skill following the design plan and best practices.

Skill Structure

skill-name/
├── SKILL.md           # Required (<300 lines)
├── scripts/           # Optional: executable tools
└── references/        # Optional: detailed docs

If the skill includes scripts: Use project's primary language if detectable (check package.json, go.mod, Cargo.toml, pyproject.toml, etc.); default to Python when unclear. Read cross-platform-scripts.md for mandatory cross-platform rules (paths, shell commands, line endings).

Naming Convention

Gerund form (verb + -ing): writing-skills, processing-pdfs

• Lowercase, hyphens, numbers only
• Max 64 characters
• Avoid: helper, utils, anthropic, claude

SKILL.md Format

See references/spec.md for full frontmatter specification (fields, arguments, model selection, context:fork).

Context and Agent Selection

Use Case	context	agent	Rationale
Inline knowledge (conventions, patterns)	(none)	(none)	Runs in main conversation, Claude applies alongside current context
Analysis or exploration task	fork	Explore	Isolated context, read-only tools, prevents context pollution
Planning task	fork	Plan	Isolated context, research-focused
Task with side effects (deploy, commit)	fork	(none)	Isolated from main conversation, uses general-purpose agent
Default for most skills	(none)	(none)	Runs inline, cheapest, fastest

When to use context: fork:

• Skill generates large output that would pollute main context
• Skill is a self-contained task (not reference material)
• Skill needs different tools than the main conversation

When NOT to use context: fork:

• Skill provides conventions or guidelines (needs main context to apply them)
• Skill content is reference material for ongoing work
• Skill needs access to conversation history

Key rules:

• Name: gerund form, lowercase, hyphens only, max 64 chars
• Description: [What it does]. [Key capabilities]. Use when [triggers]. — third person, does not enumerate workflow steps
• Body: < 300 lines, detailed content goes to references/
• Parallel tool calls: when skill tasks involve independent reads, searches, or writes, explicitly state "run these tool calls in parallel" so the agent fans out instead of serializing

Body Structure

Essential sections: Overview, Tasks (with verification each), References. Add only when they earn their place: Routing (only when the skill hands off to other skills — omit if Handoff/Next would be "none"), Task Initialization (multi-step flows), Red Flags / Common Rationalizations (real rationalization risks). No flowchart required. See references/patterns.md for the template.

Verification

Can answer YES to all:

• Description states what the skill does, then "Use when..." triggers
• Description does NOT enumerate workflow steps
• Body < 300 lines
• Task Initialization present if the flow is multi-step
• Red Flags present if there are real rationalization risks
• Has verification criteria for each task

Task 4: Add References (if needed)

Goal: Move detailed content to references/ for progressive disclosure.

When to extract:

• API documentation (100+ lines)
• Detailed examples
• Edge case handling
• Background theory

Keep in SKILL.md:

• Core workflow
• Task definitions
• Red Flags and Rationalizations
• Quick reference tables

Verification: SKILL.md is < 300 lines. All detailed content has a reference link.

Task 5: Validate Structure

Goal: Verify skill structure is correct.

Use scripts/validate_skill.py to run automated validation:

python3 "${CLAUDE_SKILL_DIR}/scripts/validate_skill.py" <path/to/skill>

Manual checklist if script unavailable:

• Frontmatter has name and description
• Name is gerund form, lowercase, hyphens only
• Description states what the skill does, then "Use when..." triggers
• Body < 300 lines
• All reference links work
• If context: fork: model explicitly specified (inherit = anti-pattern in plugin skills)

Verification: Validation passes with no errors.

Task 6: REFACTOR - Quality Review

Goal: Have skill reviewed by skill-reviewer subagent.

Agent tool:
- subagent_type: "rcc:skill-reviewer"
- prompt: "Review skill at [path/to/skill]"

Interpret YAML output:

• pass: true → Proceed to Task 7
• pass: false → Fix all issues listed, re-run reviewer, repeat until pass: true

This is the improvement phase: Address issues and refine quality based on reviewer feedback.

Verification: skill-reviewer returns YAML with pass: true.

Task 7: Test with Real Usage

Goal: Verify skill works in practice.

Process:

1. Start new Claude Code session (fresh context)
2. Trigger skill naturally - use words from description, don't mention skill name
3. Verify skill activates
4. Verify agent follows instructions correctly
5. Run original pressure scenario WITH skill - agent should now comply

Verification:

• Skill activates when triggered naturally
• Agent follows skill instructions
• Agent passes pressure scenario that failed in baseline

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "Skip requirements analysis, I know what's needed"
• "Description can enumerate the workflow steps"
• "300 lines is too restrictive"
• "Skip reviewer, the skill is obviously good"
• "Testing is overkill for a simple skill"
• "I'll add Red Flags later"
• "Task list is too bureaucratic"

All of these mean: You're about to create a weak skill. Follow the process.

Common Rationalizations

Excuse	Reality
"I know what agents need"	You know what YOU think they need. Baseline reveals actual failures.
"Baseline testing takes too long"	15 min baseline saves hours debugging weak skill.
"Description only needs triggers"	Description = what it does + when to load. Body = how. Claude picks among 100+ skills by capability statement.
"More content = better skill"	More content = more to skip. Concise + references = better.
"Red Flags are negative"	Red Flags prevent rationalization. Essential for discipline skills.
"TaskCreate is overhead"	TaskCreate prevents skipping steps. The overhead IS the value.

References

• references/spec.md - Frontmatter specification
• references/patterns.md - Common skill patterns
• references/examples.md - Before/after examples
• references/persuasion-principles.md - Authority language research
• references/testing-with-subagents.md - Baseline testing methodology
• ../../references/prompt-design-principles.md - 5-skeleton framework, failure-mode reverse engineering, conditional dispatch, creative-constraint balance, completion semantics