Claude Code Skills: Reusable Prompts That Extend Your AI

Skills are the single most important feature of Claude Code that most people never use. They are the difference between treating Claude as a chatbot you talk to and treating it as a development system you operate. Without skills, every session starts from scratch. You re-explain your workflow, your conventions, your file structure. With skills, you type /plan and Claude already knows what to read, what to produce, and how to verify it.

I have over 60 skills in my setup. They handle everything from session boot to article publishing to architecture reviews. Most of them took 15 minutes to write. They save me hours every week.

What skills are

A skill is a reusable prompt template stored as a markdown file. The file lives at ~/.claude/skills/{name}/SKILL.md, and you invoke it by typing /{name} in Claude Code. That’s it. No plugin system, no API, no compilation step. Just a markdown file with instructions that Claude loads and executes when you call it.

When I type /plan, Claude finds ~/.claude/skills/plan/SKILL.md, reads it, and follows the instructions inside. The SKILL.md file tells Claude what role to assume, what files to read, what steps to follow, and what output to produce. It turns a vague request into a structured, repeatable workflow.

Skills are global by default — they live in ~/.claude/skills/ and work across all your projects. But you can also define project-specific skills by referencing them in your project’s CLAUDE.md file.

Directory structure

Here’s what my skills directory actually looks like (trimmed to the essentials):

~/.claude/skills/
├── plan/
│   └── SKILL.md
├── execute/
│   └── SKILL.md
├── verify/
│   └── SKILL.md
├── start-coding/
│   └── SKILL.md
├── publish-article/
│   └── SKILL.md
├── audit-seo/
│   └── SKILL.md
├── research/
│   └── SKILL.md
├── create-page/
│   └── SKILL.md
├── progress/
│   └── SKILL.md
└── ... (60+ total)

Each skill gets its own folder with a single SKILL.md file. The folder name becomes the command name. /start-coding maps to skills/start-coding/SKILL.md. Simple and predictable.

Anatomy of a SKILL.md

Every SKILL.md follows a consistent structure. Here’s a simplified version based on my /start-coding skill:

---
name: start-coding
description: "Lightweight session boot for coding days."
---

# /start-coding — Lightweight Coding Boot

## Phase 1: Git Sync

Run: `git pull`

## Phase 2: Determine Project Name

Infer the project name from:
1. `project/SPEC.md` — look for the project title
2. Git remote name
3. Current directory name

## Phase 3: Daily Session Log

Run boot script to create or reuse today's session:

```bash
python3 ~/.claude/scripts/boot.py 
  --chat-id "$CLAUDE_SESSION_ID" 
  --project "[project-name]"

Phase 4: Project State

If project/ exists:

Read project/STATE.md (current position)
Read project/ROADMAP.md (what’s next)

Phase 5: Confirm Ready

Output:

Ready. (Session [ID])
Project: [name]
Next: [current phase/task from ROADMAP]


The key parts that make a skill work:

**Frontmatter** — The `name` and `description` fields tell Claude what this skill is for. The description also appears when you list available skills.

**Role definition** — Who Claude becomes when executing this skill. My `/plan` skill opens with: "You are an SDD planner orchestrator. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification."

**Process steps** — The numbered phases that Claude follows in order. Each step is specific: read this file, run this command, produce this output. Vague instructions produce vague results.

**Context references** — Which files Claude should read before acting. My `/plan` skill explicitly loads `project/SPEC.md`, `project/ROADMAP.md`, and `project/STATE.md` before it creates anything. This is how you give Claude the context it needs without re-explaining your project every time.

**Output format** — What the final output should look like. My `/start-coding` skill ends with a specific template: project name, session ID, next task. No ambiguity about what "done" looks like.

## Real examples

These are the skills I use most and what they actually do.

**`/plan`** reads the project spec, roadmap, and current state, then decomposes a phase into executable plans. Each plan gets 2-3 atomic tasks with specific file paths, implementation instructions, and verification commands. It spawns architecture and database review agents when needed. The output is a set of PLAN.md files that `/execute` can run directly.

**`/execute`** takes those PLAN.md files and runs them wave by wave. It reads each task, executes the implementation, runs the verification command, and moves to the next task. It spawns specialized agents — TDD guide, code reviewer, security reviewer — at specific points. When a task fails verification, it fixes the issue before moving on.

**`/verify`** validates completed work against the original spec. It runs the test suite, checks that deliverables exist, and compares output against acceptance criteria. It produces a VERIFICATION.md with pass/fail status for each criterion.

**`/start-coding`** is my lightweight session boot. It pulls the latest code, creates a session log, reads the project state, and tells me what's next. The whole thing takes about 10 seconds. Without it, I'd spend the first five minutes of every session figuring out where I left off.

**`/publish-article`** validates blog post frontmatter (title length, description length, required fields), checks body structure, generates FAQ schema data, and ensures structured data is correct. It catches the SEO mistakes I'd otherwise find after deploying.

## How to create your own skills

Creating a skill is straightforward. Here's my process.

**Step 1: Identify a repeated workflow.** If you've explained the same thing to Claude more than twice, it should be a skill. Common candidates: project setup, deployment, code review, content publishing, database migrations.

**Step 2: Write the SKILL.md.** Start with the frontmatter, then write out the steps you'd normally explain to Claude. Be specific — include file paths, command examples, and output formats. Here's a minimal template:

```markdown
---
name: my-skill
description: "What this skill does in one sentence."
---

# /my-skill — Short Description

## Step 1: Load Context

Read these files:
- path/to/relevant/file
- path/to/another/file

## Step 2: Do the Work

[Specific instructions for what to do]

## Step 3: Verify

Run: `[verification command]`

## Step 4: Output

Format the result as:

[expected output template]

Step 3: Test and iterate. Run the skill, see where Claude goes off track, and tighten the instructions. The most common issue is vague steps — “implement the feature” tells Claude nothing. “Create src/lib/components/Header.svelte using the design tokens from src/tokens.css” tells it exactly what to do.

Step 4: Reference it from CLAUDE.md. Add a note in your project’s CLAUDE.md so future sessions know the skill exists. This is especially important for project-specific skills that only make sense in certain codebases.

Skills vs hooks vs scripts vs agents

Skills are one of four extension mechanisms in Claude Code. Here’s how they compare:

Component	Trigger	Purpose	Example
Skill	User invokes `/command`	Reusable workflow	`/plan`, `/execute`, `/verify`
Hook	Tool event (pre/post)	Automated check	Auto-format after file edit
Script	Shell command	Utility	Upload video, compress image
Agent	Spawned by skill or code	Specialized worker	code-reviewer, tdd-guide

Skills are user-initiated workflows. You decide when to run them.

Hooks fire automatically before or after Claude uses a tool. A PostToolUse hook might auto-format code every time Claude edits a file. You don’t invoke hooks — they run on their own.

Scripts are plain shell scripts that Claude can call. They handle things that don’t need AI — file uploads, image compression, deployment commands. My upload-video.js script compresses video with ffmpeg and uploads to Cloudflare R2. No AI needed.

Agents are specialized sub-processes that skills spawn for focused tasks. My /execute skill spawns a code-reviewer agent after implementation and a tdd-guide agent before writing code. Agents run with their own context window, so they don’t pollute the main conversation.

The mental model: skills orchestrate, hooks automate, scripts utility, agents specialize. A well-built skill often calls scripts and spawns agents as part of its workflow.

What makes skills powerful

The real value of skills isn’t saving keystrokes. It’s encoding decisions.

Every time I run /plan, it automatically checks whether the spec is finalized before planning. It reads existing architecture before proposing new work. It limits plans to 2-3 tasks because I’ve learned that bigger plans degrade in quality. These aren’t things I want to remember and re-explain — they’re decisions I’ve already made, baked into the prompt.

Skills compound over time. Each time a skill fails or produces subpar output, I tighten the instructions. My /plan skill has been through dozens of iterations. It handles edge cases I’ve forgotten about. It catches mistakes I’d make if I were explaining the workflow from scratch.

That’s the shift from chatbot to system. A chatbot forgets everything between sessions. A system with skills remembers your workflows, your conventions, and your hard-won lessons — permanently.

For how skills fit into the larger development workflow, see the workflow guide.