create-skill

Create Skill

Create well-structured Claude Code skills that integrate with the agent system.

When to Use

• Creating a new skill from scratch
• Improving or refactoring an existing skill
• Adding capabilities to the agent system
• Standardizing skill format across the codebase

Dependencies

Load these skills:

• thinking.md - For decomposing complex skill requirements
• create-agent.md - Reference for agent creation (skills live alongside agents)

Design Principles

1. Conciseness Priority

Only include context Claude does not already have. Skip:

• General programming knowledge
• Common patterns Claude knows well
• Explanations of basic concepts

Focus on:

• Project-specific conventions
• Domain knowledge unique to your system
• Non-obvious integration points

2. Description Field Drives Triggering

The YAML description field is the most critical element for skill invocation. It must:

• Include action words that match how users ask for help
• Mention "when to use" conditions
• Stay under 20 words while being specific

Good: "Create or improve Claude Code skills. Use when building new skills or refining skill instructions."

Bad: "A skill for creating skills" (too vague, no trigger conditions)

3. Progressive Disclosure

4. Degrees of Freedom

Match constraint level to task fragility:

For skills, err toward medium fragility - provide structure but allow judgment.

Skill File Structure

Required: YAML Front Matter

---
name: "[Skill Name]"
description: "[Action-oriented trigger phrase. Include when-to-use conditions. Under 20 words.]"
---

Required: Core Sections

# [Skill Name]

[One-line purpose statement.]

## When to Use

- [Trigger condition 1]
- [Trigger condition 2]
- [Trigger condition 3]

## Dependencies

- **[skill-name].md** - [Why this dependency exists]
- (Or: "None - this is a core skill")

## [Main Content Sections]

[The actual skill content - frameworks, patterns, checklists, templates]

## Output Format

[Expected output structure when using this skill]

Optional: Enhancement Sections

## Book Triggers

Reference: [[books/{domain}.md]]
- Apply "[Book]" for [specific application]

## Integration

How this skill connects to other skills:
- With [other-skill]: [how they work together]

## Anti-Patterns

- [What to avoid when using this skill]

Skill Template

Use this template when creating new skills:

---
name: "[Skill Name]"
description: "[Short action-oriented trigger with when-to-use conditions]"
---

# [Skill Name]

[One-line description of what this skill does.]

## When to Use

- [Trigger condition - be specific]
- [Another trigger condition]
- [When NOT to use, if helpful]

## Dependencies

- **[dependency].md** - [Why needed]
- (Or: "None - this is a core skill")

## Book Triggers

Reference: [[books/{relevant-domain}.md]]
- Apply "[Book Name]" for: [specific application]

## [Primary Content Section]

[Main instructions, frameworks, or patterns. This is the meat of the skill.]

### [Subsection if needed]

[Break down complex instructions into digestible pieces.]

## Output Format

[What the skill produces. Include a template if the output is structured.]

```markdown
## [Output Header]

[Template structure]

Integration

• With [other-skill]: [how they combine]
• Called by: [which agents or workflows invoke this]

Anti-Patterns

• [Common mistake to avoid]
• [Another pitfall]

Checklist

Before completing skill execution:

• [Verification step 1]
• [Verification step 2]

---

## Naming Conventions

| Category | Pattern | Examples |
|----------|---------|----------|
| Core skills | `{name}.md` | `thinking.md`, `memory.md` |
| Product flow | `{stage}.md` | `vision.md`, `prd.md` |
| Engineering | `{name}.md` | `code-review.md` |
| Utility | `utility-{name}.md` | `utility-git-commit.md` |
| Domain-specific | `{domain}-{action}.md` | `rails-migrate.md` |

---

## Advanced: Skill Directory Structure

For complex skills that need supporting files:

skills/ my-skill/ SKILL.md # Main skill file (required) scripts/ # Helper scripts (optional) validate.sh references/ # Reference documents (optional) examples.md assets/ # Images, diagrams (optional) workflow.png

The `SKILL.md` file follows the same format as a standalone `.md` skill file.

---

## Integration with Agent System

### How Skills Are Invoked

1. **Direct invocation**: User or agent explicitly calls the skill
2. **Trigger matching**: Description field matches user intent
3. **Agent reference**: Listed in an agent's `## Skills` section

### Skill Dependencies

Declare dependencies that the orchestrator can verify:

```markdown
## Dependencies

### Required
- **vision.md** - Cannot create PRD without vision
  - Check: `projects/{project}/docs/vision.md` exists

### Optional
- **research.md** - For market research if needed

Cross-Skill Workflow

Document how skills chain together:

## Integration

Typical workflow with this skill:
1. thinking.md -> decompose the problem
2. [this-skill].md -> execute the core task
3. decision-making.md -> evaluate results

Checklist: Before Creating a Skill

Content Validation

• One-liner clearly states purpose
• When to Use has 3-5 specific triggers
• Dependencies declared (or explicitly "none")
• Main content is actionable, not just descriptive
• Output format is specified
• Examples included where helpful

YAML Front Matter

• name is concise and descriptive
• description includes action words AND trigger conditions
• description is under 20 words

Quality Checks

• Follows progressive disclosure (most important info first)
• No redundant explanations of common knowledge
• Constraint level matches task fragility
• Anti-patterns section prevents common mistakes
• Integration points documented

Naming and Location

• Filename follows naming conventions
• Placed in correct directory (skills/)
• If complex, uses directory structure with SKILL.md

Output Format

When this skill completes, produce:

1. The skill file at the specified path
2. Summary of what the skill does and its trigger conditions
3. Integration notes on how it connects to existing skills/agents

Anti-Patterns

• Kitchen sink skills: Trying to do too much in one skill
• Vague descriptions: Description field that won't trigger correctly
• Missing output format: Skill without clear deliverable
• Undeclared dependencies: Skills that assume other skills without stating it
• Over-explanation: Including context Claude already has
• No trigger conditions: "When to Use" that's too generic to be actionable