writing-skills

What this skill does

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

**Violating the letter of the rules is violating the spirit of the rules.**

## Routing

**Pattern:** Skill Steps
**Handoff:** none
**Next:** none

## Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

```
TaskCreate for EACH task below:
- Subject: "[writing-skills] Task N: <action>"
- ActiveForm: "<doing action>"
```

**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. Review and improve
7. Test with real usage

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

**Execution rules:**
1. `TaskUpdate status="in_progress"` BEFORE starting each task
2. `TaskUpdate status="completed"` ONLY after verification passes
3. If task fails → stay in_progress, diagnose, retry
4. NEVER skip to next task until current is completed
5. At end, `TaskList` to confirm all completed

## 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](../../references/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](../../references/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](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: starts with "Use when...", third person, does not summarize workflow
- 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

Required sections: Overview, Routing, Task Initialization, Tasks (with verification each), Red Flags, Common Rationalizations, Flowchart, References. See [references/patterns.md](references/patterns.md) for full template.

### Verification

Can answer YES to all:
- [ ] Description starts with "Use when..."
- [ ] Description does NOT summarize workflow
- [ ] Body < 300 lines
- [ ] Has Task Initialization section
- [ ] Has Red Flags section
- [ ] 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