skill-creator

What this skill does

# Skill Creator

## Overview

This skill provides guidance for creating effective skills.
Use it to design, restructure, or harden a skill so it triggers correctly, stays lean, and contains the non-obvious guidance that actually changes Claude's behavior.

## Core Mental Model

Treat a skill as a folder-based capability, not just a markdown note. A strong skill gives Claude non-obvious knowledge, reusable tools, and just enough structure to execute well without being railroaded.

Optimize for the delta from Claude's default behavior:
- Add information Claude would not reliably infer on its own
- Add gotchas, edge cases, and failure patterns
- Add reusable scripts, templates, and references when they save turns or improve reliability
- Keep the top-level skill lean and use the filesystem for progressive disclosure

A mediocre skill restates obvious steps.
A strong skill changes what Claude can do or how reliably it can do it.

## What High-Value Skills Usually Do

Most strong skills fall primarily into one category. Prefer a clean primary category instead of blending several unrelated ones.

1. Library and API reference
   - Explain how to use an internal or external library, SDK, CLI, or framework correctly
   - Focus on footguns, edge cases, unsupported patterns, and working examples

2. Product verification
   - Explain how to test or verify behavior using tools like Playwright, tmux, screenshots, videos, or assertions
   - Often worth extra investment because verification quality compounds across many tasks

3. Data fetching and analysis
   - Connect Claude to dashboards, SQL systems, warehouse schemas, observability stacks, or canonical joins
   - Include identifiers, lookup tables, and common analysis workflows

4. Business process and team automation
   - Automate recurring operational workflows like standups, recap posts, ticket creation, or status reporting
   - May benefit from durable logs or prior-run artifacts for consistency

5. Code scaffolding and templates
   - Generate boilerplate or project structure for recurring implementation patterns
   - Usually pair well with assets and scripts

6. Code quality and review
   - Enforce review checklists, testing expectations, style guidance, or quality gates

7. CI/CD and deployment
   - Handle deploy workflows, flaky CI retries, PR checks, gradual rollout steps, and rollback procedures

8. Runbooks
   - Map symptoms or alerts to investigation steps, tools, dashboards, and report formats

9. Infrastructure operations
   - Support routine maintenance and operational tasks with explicit guardrails

If a proposed skill does not fit any of these categories, verify that it is still a real repeatable capability instead of a one-off note.

## Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```text
skill-name/
├── SKILL.md
├── scripts/      # executable helpers
├── references/   # detailed docs loaded on demand
├── templates/    # reusable output structures
├── assets/       # boilerplate files, sample outputs, images, fixtures
├── config.json   # optional user/team-specific configuration
└── logs/ or data/ if truly needed for local state
```

Use the folder structure deliberately:
- Put concise trigger and workflow guidance in SKILL.md
- Put long API details, schemas, and reference material in references/
- Put deterministic helpers in scripts/
- Put repeatable output structures in templates/
- Put boilerplate and sample resources in assets/
- Put user- or team-specific configuration in config.json when needed

When persistent writable data is required across upgrades, prefer `${CLAUDE_PLUGIN_DATA}` instead of storing state directly inside the shipped skill folder.

## Progressive Disclosure

Design the skill so Claude reads only what is needed:

1. Frontmatter is always visible
2. SKILL.md is loaded when the skill triggers
3. References, scripts, and assets are discovered and loaded only when useful

This means:
- Keep SKILL.md high-signal and relatively lean
- Move detailed reference material out of the main file
- Tell Claude what files exist and when to use them
- Avoid duplicating the same information in multiple places

Good pattern:
- SKILL.md says that detailed API signatures live in `references/api.md`
- SKILL.md says a reusable helper exists at `scripts/fetch_metrics.py`
- Claude pulls those in only when the task actually needs them

## Description Field: Write for Triggering, Not for Marketing

The description field is for the model, not for a human catalog page.
It should describe when the skill should trigger.

Write descriptions that mention:
- The kinds of requests that should activate the skill
- Important file types, systems, or domains involved
- Failure modes the skill helps with
- Whether the skill is for creation, debugging, verification, migration, review, or operations

Prefer trigger-oriented wording like:
- "Use this skill when..."
- "Guide for creating or updating... when..."
- "Apply when working with..."

Avoid vague summaries like:
- "Helpful skill for PDFs"
- "Utilities for data work"

## Gotchas Are Mandatory

A gotchas section is often the highest-signal part of the skill.

Include:
- Known failure patterns Claude has hit before
- Tool-specific footguns
- Misleading docs or defaults
- Incompatible approaches
- Cases where the obvious solution is wrong in this environment

If the skill is mostly knowledge, prioritize gotchas over generic explanation.
Start small if needed: one excellent gotcha is more valuable than pages of boilerplate.

## Avoid Railroading

Describe what tools and approaches are available and when each is useful. Only enforce a rigid sequence when safety or correctness requires it.

## Prefer Scripts Over Repeated Prose

If Claude keeps rewriting the same helper logic, ship it as a script instead of describing it. Scripts are better when they provide deterministic reliability, lower token usage, or easier composition. Do not stop at describing what a helper should do when the helper can be shipped directly.

## Verification Skills Deserve Extra Care

Verification skills compound in value. When relevant, include driving scripts, assertions on expected state, screenshot/video capture, and structured result output. A good verification skill gives Claude a repeatable way to prove the feature works, not just "test the feature".

## Configuration, State, and Hooks

- **Configuration**: Store user- or team-specific constants (Slack channel IDs, environment names, dashboard identifiers) in `config.json` when needed.
- **State**: Only persist state when it materially improves outcomes. Prefer `${CLAUDE_PLUGIN_DATA}` for durable writable state.
- **Hooks**: Prefer on-demand hooks tied to the skill instead of globally annoying restrictions.

## Skill Creation Process

Follow this process in order unless there is a clear reason to skip a step.

### Step 1: Collect Trigger Examples

Understand how the skill should actually be invoked.
Gather or propose concrete examples such as:
- what users would say
- what files or systems are involved
- what successful output looks like
- what commonly goes wrong today

Ask only a few focused questions at a time.
A skill is ready to design once there is a clear picture of the recurring task and its trigger patterns.

### Step 2: Choose the Skill Category and Delta

Identify the primary category from the list above.
Then identify the delta from Claude's default capabilities:
- What does Claude currently get wrong?
- What knowledge is missing?
- What repetitive work should be packaged?
- What verification or safety guardrails are needed?

If there is no meaningful delta, the task may not need a skill.

### Step 3: List Reusable Components

For each representative example, decide what should live in:
- SKILL.md
- scripts/
- references/
- templates/
- assets/
- config.json
- `${CLAUDE_PLUGIN_DATA}`

Use this rule of thumb:
- Put guidance in SKILL.md
- Put detail in references/