Claude Skills Best Practices

Mental Model#

A skill is a Markdown file that extends Claude’s behavior. Think of it as a persistent instruction set Claude loads on demand — not a script that runs automatically, but a detailed playbook Claude reads and follows when the right task comes up.

How Claude finds and loads skills:

• At session start, Claude scans all registered skill directories and loads only each skill’s name and description (the frontmatter). Full content is not loaded yet.
• When a task matches a skill’s description (or you invoke it explicitly via the Skill tool), Claude loads the full SKILL.md and follows its instructions.
• This progressive disclosure keeps context lean — you can have hundreds of skills registered without bloating every conversation.

Two kinds of skills:

• Rigid — Step-by-step workflows that must be followed exactly (e.g., commit, deploy, TDD). Designed to enforce discipline. Use disable-model-invocation: true so they only fire deliberately.
• Flexible — Reference knowledge, patterns, or conventions Claude adapts to context (e.g., API docs, style guides, domain knowledge). These inform Claude’s approach rather than dictating steps.

How to Create a Skill (Step-by-Step)#

Step 1 — Invoke the new-skill skill#

/new-skill

This guides you through:

• Choosing which plugin bundle to add the skill to
• Running init_skill.py to scaffold the directory and starter SKILL.md
• Setting up proper frontmatter conventions

Step 2 — Define what the skill does (before writing it)#

Answer these questions first:

• What specific situation triggers this skill? (Be precise — vague = never fires)
• What does success look like? What should Claude do or produce?
• Is it rigid (always follow these steps) or flexible (apply these principles)?
• Does it chain into another skill when done?

Step 3 — Write the frontmatter#

Fill in name and description first. Everything else follows from those.

Step 4 — Write the skill body#

Structure depends on skill type:

• Rigid skills → checklist of steps with verification criteria
• Flexible skills → organized reference sections with examples

Use the writing-skills skill for guidance during this phase.

Step 5 — Test it#

Invoke the skill in a real conversation and watch what Claude does. Ask:

• Did it fire when expected?
• Did it not fire when it shouldn’t?
• Did Claude follow the instructions faithfully?
• Were there ambiguities Claude had to guess at?

Fix gaps and re-test. Never ship a skill you haven’t tested in live use.

Step 6 — Publish#

/publish-to-marketplace

This validates all skills in the bundle, runs package_skill.py, ensures plugin.json is current, creates a git tag, and prints installation instructions.

Anatomy of a Skill#

Every skill lives in its own folder. The only required file is SKILL.md.

skills/
└── my-skill-name/
    ├── SKILL.md              ← required entry point
    ├── process-guide.md      ← optional supporting doc
    ├── examples/
    │   └── example-workflow.md
    └── templates/
        └── starter-template.md

SKILL.md contains the frontmatter and the main instruction body. Keep it under ~500 lines. For longer skills, split content into supporting files and reference them from SKILL.md — Claude pulls them in on demand.

Supporting files are loaded when Claude reads them. Reference them explicitly in the skill body: Read the detailed guide at skills/my-skill/process-guide.md.

Writing the Frontmatter#

Minimal required frontmatter:

---
name: my-skill-name
description: Use when doing X in context Y. Triggers on phrases like "do X", "need X", "X for Y".
---

Writing the Description (Your Trigger)#

The description field is the most critical part of any skill. Claude matches user intent against it to decide whether to invoke. A bad description = a skill that never fires or fires at the wrong time.

Patterns that work#

Lead with “Use when…” followed by a concrete situation:

description: Use when implementing any feature or bugfix, before writing implementation code.

Include trigger phrases — the exact words a user might say:

description: Use when the user wants to commit code. Triggers on phrases like "commit these changes", "save my work to git", "/commit".

Name the workflow stage:

description: Use when implementation is complete and you need to decide how to integrate the work.

Patterns that don’t work#

Before/after example#

Before (won’t fire reliably):

description: Skill for researching companies

After (fires reliably):

description: Research one or more companies using Brave Search for competitive intelligence. Triggers on phrases like "research company X", "look up company X", "competitive intel on X".

Structuring the Skill Body#

Rigid vs Flexible — pick one#

Use rigid when:

• The task has a fixed sequence that must not be skipped (e.g., always test before commit)
• Skipping steps causes real problems
• You want to enforce a discipline you’d otherwise forget

Use flexible when:

• The skill is reference knowledge Claude adapts to context
• Different situations call for different approaches
• You’re documenting patterns, not procedures

Rigid skill body structure#

## Overview
One paragraph: what this skill does and why it exists.

## When to Use
- Concrete situation A
- Concrete situation B

## When NOT to Use
- Edge case that looks similar but isn't

## The Process
1. Step one — exactly what to do
   - Verification: how to confirm it worked
2. Step two — exactly what to do
   ...

## Common Mistakes
- Anti-pattern and why it's wrong

## Red Flags
Signs you've gone off track

Flexible skill body structure#

## Overview
What this knowledge covers and when it applies.

## Key Concepts
### Concept A
Explanation with examples.

### Concept B
Explanation with examples.

## Examples
Real, working examples — never pseudocode.

## Quick Reference
Table or checklist for fast lookup.

Checklists#

Use - [ ] syntax for steps Claude should track:

- [ ] Read existing code before proposing changes
- [ ] Run tests before marking complete
- [ ] Ask user to review before proceeding

Each step should be independently executable with no ambiguity. No “TBD”, no “similar to step 3”, no placeholders.

Process flow diagrams#

For complex workflows, use dot notation in a code block — Claude renders this as a directed graph:

```dot
digraph flow {
    "Start" -> "Do thing A";
    "Do thing A" -> "Check result" [label="success"];
    "Check result" -> "Do thing B";
}
```

Skill Chaining#

Skills compose into workflows. The superpowers chain is the canonical example:

brainstorming → writing-plans → executing-plans → finishing-a-development-branch → verification-before-completion

How to chain skills#

At the end of a skill, explicitly name the next step:

## After This Skill
Invoke the `writing-plans` skill to create a detailed implementation plan. Do NOT proceed to implementation directly.

Use the REQUIRED SUB-SKILL: convention when a skill depends on another:

REQUIRED SUB-SKILL: Use superpowers:brainstorming before executing this skill.

Hard gates prevent skipping:

<HARD-GATE>
Do NOT write any code until the design has been presented and approved. This applies regardless of how simple the task seems.
</HARD-GATE>

When to chain vs keep separate#

• Chain when skill B is always the logical next step after skill A
• Keep separate when the next step varies by context
• Never assume the user knows the chain — always state it explicitly in the skill body

Anti-Patterns & Red Flags#

Anti-patterns to avoid#

Red flags during use#

• Claude ignores the skill mid-workflow → your steps are ambiguous or contradictory
• Skill fires when it shouldn’t → description is too broad
• Skill never fires when expected → description too vague, or disable-model-invocation: true is set
• Claude asks clarifying questions the skill should answer → missing context in the skill body

Quick Reference Template#

Copy this as a starting point for any new skill:

---
name: skill-name
description: Use when [specific situation]. Triggers on phrases like "[phrase 1]", "[phrase 2]", "[phrase 3]".
---

# Skill Name

## Overview
One paragraph explaining what this skill does and why it exists.

## When to Use
- Situation A
- Situation B

## When NOT to Use
- Edge case that looks similar

## The Process

- [ ] Step 1 — what to do
- [ ] Step 2 — what to do
- [ ] Step 3 — verify result

## Common Mistakes
- Mistake: why it's wrong, what to do instead

## After This Skill
[Optional] Next skill to invoke: `plugin:next-skill-name`