# Skill Writer

> Comprehensive guide for creating high-quality skills for Claude. Use when building a new skill, writing a SKILL.md, designing skill frontmatter, planning skill structure, debugging trigger issues, or reviewing an existing skill for improvements. Covers standalone skills, MCP-enhanced skills, and skill-tree programmatic skills.

- Skill: `alexngai/skill-writer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alexngai/skill-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexngai/skill-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alexngai (https://skillmd.com/u/alexngai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexngai/skill-writer

---


# Skill Writer

Create well-structured, effective skills that trigger reliably, follow Anthropic's progressive disclosure model, and produce consistent results.

## Core Concepts

A skill is a folder containing instructions that teach Claude to handle specific tasks or workflows. Skills eliminate the need to re-explain preferences, processes, and domain expertise in every conversation.

### Progressive Disclosure (Three Levels)

1. **YAML frontmatter** (always in system prompt): Enough for Claude to decide *when* to load the skill
2. **SKILL.md body** (loaded when relevant): Full instructions and guidance
3. **Linked files** (loaded as needed): References, scripts, assets in subdirectories

This minimizes token usage while maintaining specialized expertise.

### Design Principles

- **Composability**: Skills run alongside other skills. Never assume exclusive context.
- **Portability**: Skills work across Claude.ai, Claude Code, and API without modification (given environment dependencies are met).
- **Progressive complexity**: Start simple, add depth through references.

## Instructions

### Step 1: Define Use Cases

Before writing anything, identify 2-3 concrete use cases.

For each use case, document:
- **Trigger**: What the user says or does
- **Steps**: The multi-step workflow required
- **Result**: The concrete outcome produced

Determine which category the skill falls into:

| Category | Purpose | Example |
|----------|---------|---------|
| Document/Asset Creation | Consistent, high-quality output | frontend-design, docx, pptx |
| Workflow Automation | Multi-step processes with methodology | skill-creator, sprint-planner |
| MCP Enhancement | Workflow guidance for MCP tool access | sentry-code-review |

### Step 2: Create the Folder Structure

```
your-skill-name/
├── SKILL.md              # Required - main instruction file
├── scripts/              # Optional - executable code (Python, Bash)
├── references/           # Optional - detailed docs loaded as needed
└── assets/               # Optional - templates, fonts, icons
```

Critical naming rules:
- Folder: **kebab-case only** (`my-skill-name`)
- File: **exactly** `SKILL.md` (case-sensitive, no variations)
- No `README.md` inside the skill folder
- No spaces, underscores, or capitals in folder name

### Step 3: Write the YAML Frontmatter

The frontmatter is *the most important part* - it determines whether Claude loads the skill.

Minimal required format:

```yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
```

#### The `name` Field

- kebab-case only, no spaces or capitals
- Must match the folder name
- Never use "claude" or "anthropic" as a prefix (reserved)

#### The `description` Field (Critical)

Structure: `[What it does] + [When to use it] + [Key capabilities]`

Must include BOTH:
1. What the skill does
2. When to use it (trigger conditions with specific phrases)

Constraints:
- Under 1024 characters
- No XML angle brackets (`<` or `>`)
- Include specific tasks/phrases users would actually say
- Mention relevant file types if applicable

**Good descriptions:**

```yaml
# Specific + actionable + trigger phrases
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files, asks for
  "design specs", "component documentation", or "design-to-code handoff".

# Clear value proposition + triggers
description: End-to-end customer onboarding workflow for PayFlow.
  Handles account creation, payment setup, and subscription management.
  Use when user says "onboard new customer", "set up subscription",
  or "create PayFlow account".
```

**Bad descriptions:**

```yaml
# Too vague - won't trigger
description: Helps with projects.

# Missing triggers - Claude won't know when to load
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user-facing triggers
description: Implements the Project entity model with hierarchical
  relationships.
```

#### Optional Fields

```yaml
license: MIT                              # For open-source skills
compatibility: Requires Python 3.10+      # 1-500 chars, environment needs
allowed-tools: "Bash(python:*) WebFetch"  # Restrict tool access
metadata:                                 # Custom key-value pairs
  author: Your Name
  version: 1.0.0
  mcp-server: server-name
  tags: [automation, productivity]
```

#### Security Restrictions

Forbidden in frontmatter:
- XML angle brackets (`<` `>`) - prevents prompt injection
- Skills named with "claude" or "anthropic" prefix

### Step 4: Write the Instructions Body

After the frontmatter, write instructions in Markdown.

#### Recommended Structure

```markdown
# Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
\`\`\`bash
python scripts/fetch_data.py --project-id PROJECT_ID
\`\`\`
Expected output: [describe what success looks like]

(Add more steps as needed)

## Examples

### Example 1: [Common Scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]
```

#### Writing Style Rules

- **Imperative/infinitive form**: "To accomplish X, execute Y" or "Load this skill when Z"
- **Avoid second person**: Do NOT write "You should..." or "If you need..."
- **Be specific and actionable**: Include exact commands, parameters, expected outputs
- **Use bullet points and numbered lists** for scanability
- **Put critical instructions at the top** using `## Important` or `## Critical` headers

#### Error Handling

Always include error handling:

```markdown
## Common Issues

### MCP Connection Failed
If "Connection refused" appears:
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Service] > Reconnect
```

#### Progressive Disclosure in Practice

Keep SKILL.md focused on core instructions (under 5,000 words). Move detailed documentation to `references/`:

```markdown
Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling
```

#### Combating Instruction Drift

For critical validations, prefer bundling a script over relying on language instructions:

```markdown
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past
```

For deterministic checks, use `scripts/validate.py` instead of prose instructions.

### Step 5: Choose an Implementation Pattern

Select the pattern that fits the skill's workflow. See `references/patterns.md` for detailed examples.

| Pattern | Use When |
|---------|----------|
| Sequential Workflow | Multi-step processes in specific order |
| Multi-MCP Coordination | Workflows spanning multiple services |
| Iterative Refinement | Output quality improves with iteration |
| Context-Aware Selection | Same outcome, different tools per context |
| Domain Intelligence | Specialized knowledge beyond tool access |

### Step 6: Test the Skill

#### Triggering Tests
Run 10-20 test queries. Target: skill triggers on 90%+ of relevant queries.

Should trigger:
- Obvious task descriptions
- Paraphrased requests
- Domain-specific terminology

Should NOT trigger:
- Unrelated topics
- Queries better served by other skills

Debug triggering: Ask Claude "When would you use the [skill name] skill?" and compare against expected triggers.

#### Functional Tests
- Valid outputs generated
- API/MCP calls succeed
- Error handling works
- Edge cases covered

#### Performance Comparison
Compare with and without the skill:
- Number of back-and-forth messages
- Failed API calls
- Total tokens consumed
- User corrections needed

### Step 7: Iterate

Skills are living documents. Watch for:

**Undertriggering** (skill doesn't load when it should):
- Add more trigger phrases to the description
- Include technical keywords and synonyms

**Overtriggering** (skill loads for unrelated queries):
- Add negative triggers: "Do NOT use for simple data exploration"
- Be more specific about scope
- Clarify boundaries with other skills

**Execution issues** (inconsistent results):
- Make instructions more specific
- Add error handling
- Move verbose content to references

## Skill-Tree Programmatic Skills

When creating skills for the skill-tree library (as opposed to SKILL.md files), structure them with these fields:

```typescript
{
  id: "kebab-case-id",
  name: "Human-Readable Name",
  version: "1.0.0",
  description: "Short description for semantic matching (1-2 sentences)",
  problem: "What problem this skill solves",
  triggerConditions: [
    { type: "error", value: "Cannot find module", description: "ES module import failure" },
    { type: "keyword", value: "typescript, import", description: "TypeScript imports" },
    { type: "pattern", value: "\\.(ts|tsx)$", description: "TypeScript files" }
  ],
  solution: "Step-by-step solution in imperative form",
  verification: "How to verify the skill worked",
  examples: [
    { scenario: "Description", before: "Before state", after: "After state" }
  ],
  tags: ["typescript", "modules"],
  status: "active"
}
```

Trigger condition types:
- `error`: Error message patterns (regex)
- `keyword`: Comma-separated keywords
- `pattern`: Regex for file paths or content
- `context`: Contextual description
- `custom`: Freeform condition

## Quality Checklist

Before shipping, verify against `references/quality-checklist.md`.

Quick validation:
- [ ] Folder is kebab-case, SKILL.md exists (exact spelling)
- [ ] Frontmatter has `---` delimiters, `name` and `description` fields
- [ ] Description includes WHAT it does and WHEN to use it
- [ ] No XML tags anywhere in frontmatter
- [ ] Instructions are specific and actionable (not vague)
- [ ] Error handling included for common failure modes
- [ ] Examples provided for primary use cases
- [ ] SKILL.md is under 5,000 words
- [ ] Detailed docs moved to references/
- [ ] Tested: triggers correctly, doesn't overtrigger, produces correct output