A Skill Is Better Than a Prompt When the Work RepeatsA Skill Is Better Than a Prompt When the Work Repeats

A Claude Code skill is a Markdown file in .claude/skills/ that gives the agent a consistent procedure, a memory of past decisions, and a reusable set of steps for recurring work. A prompt is something you type once and refine on the fly. The question of which to use comes down to one thing: does this work repeat? If you're doing it more than twice, the cost of writing a good skill pays off faster than you expect.

---

What Skills Enable That Prompts Don't

When you write a prompt, you're reconstructing context every time. You explain the project structure, remind the agent of constraints, re-specify the output format. Some of that is unavoidable — task details change — but the procedure shouldn't change. The skill carries the procedure so the prompt only carries the task.

Skills also accumulate decisions. The first time you build a component with the agent, you decide that this project uses clsx for class names, not template literals. You decide that all new components need a barrel export. You decide that TypeScript props go above the component, not below. Encoding these decisions in a skill means you don't re-litigate them every session — the agent already knows.

Finally, skills are shareable. A skill that captures how your team handles database migrations, or how you write API route handlers, or how you structure design tokens — that skill can live in the repo and every team member gets the same agent behavior.

When a Prompt Is Enough

Not everything needs a skill. A prompt is the right tool when:

• The task is one-off and context-specific
• The procedure is simple enough to state inline
• You're exploring and don't know the right procedure yet

Don't premature-optimize into a skill. Write the task as a prompt a couple of times, notice what you keep repeating, and extract that into a skill. The repeating parts are the skill; the variable parts stay in the prompt.

What to Include in a Skill That Actually Works

The failure mode of a bad skill is over-specification that makes it brittle, or under-specification that makes it vague. A good skill has exactly these parts:

Context — what this skill is for, what kind of project it applies to, any assumptions it makes about the environment.

Procedure — numbered steps. Not bullet points that can be done in any order. Numbered steps that reflect sequence and dependencies.

Outputs — what files get created or modified, what the final state should look like.

Constraints — what NOT to do. This is the part most skills skip, and it's where agents diverge most.

Here's a concrete example — a skill for adding a new API route in a Next.js App Router project:

# add-api-route

Add a new API route to this Next.js App Router project.

## Context
- Routes live in `src/app/api/`
- All routes use the Route Handler pattern (not Pages Router API routes)
- Auth is handled by the `withAuth` wrapper in `src/lib/auth`
- Response helpers are in `src/lib/response` — use `ok()`, `err()`, `notFound()`

## Steps
1. Create `src/app/api/[resource]/route.ts`
2. Import `withAuth` and wrap all handlers that require authentication
3. Import response helpers — never return `NextResponse.json()` directly
4. Add Zod validation for request body on POST/PUT/PATCH routes
5. Export named functions: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` as needed
6. Add the route to `src/app/api/README.md`

## Constraints
- Do not create a separate types file — inline the types in the route file
- Do not use `any` types
- Do not add middleware — use the `withAuth` wrapper pattern

That skill encodes decisions the team already made. The agent doesn't need to infer them from the codebase — they're explicit.

The ai-reference.md Pattern

A related pattern that isn't technically a skill but serves the same function: an ai-reference.md file in the project root (or .claude/) that documents project-specific conventions. This is the first file the agent reads when starting a session. It answers the questions the agent would otherwise have to infer or ask:

• What package manager does this project use?
• Where do components live?
• What testing framework?
• What environment variables exist and what do they do?

Skills are procedural (how to do a task). ai-reference.md is declarative (how this project works). Both reduce the cost of each agent session by front-loading context that doesn't change.

The Investment Calculation

Writing a good skill takes 20–30 minutes. If it saves 5 minutes of prompt overhead per session, it pays off after six sessions. For any recurring task in active development — adding routes, creating components, writing tests for a specific pattern — that threshold comes quickly.

The more honest calculation: the value of a skill isn't just time, it's consistency. The agent with a good skill produces output that looks like your codebase because you told it what your codebase looks like. That consistency compounds in ways that are hard to put a number on.