Engineer Your Claude Skills, Don't Just Prompt Them

The Problem With Prompt Engineering

I spent my first month with Claude Code typing the same instructions into every new chat. "Use TypeScript." "Follow my existing patterns." "Don't add comments." "Keep responses minimal."

Every. Single. Session.

Then I'd get inconsistent results. Claude would add verbose explanations I didn't ask for. It would suggest patterns that didn't match my stack. I was treating AI like a search engine when I should have been treating it like a compiler.

Prompt engineering optimizes individual requests. Skill engineering creates systems.

What Is a Behavioral Skill File?

A skill file is a markdown document that lives in your .claude/ directory. It defines how Claude should behave for specific types of work — not just what to do, but how to think about problems in your codebase.

Here's my refactor.md skill file:

# Refactoring Protocol

When refactoring code:

1. Show minimal diffs — only changed lines
2. Preserve existing patterns (check nearby files first)
3. No explanatory comments in code
4. Provide a single-line summary after changes
5. If touching types, verify all callsites

Prefer composition over abstraction.
Prefer explicit over clever.

That's it. Five rules and two principles. But those rules compound across dozens of refactoring sessions. Claude doesn't need to guess my preferences. It doesn't waste tokens explaining obvious changes. It checks patterns automatically.

The Difference Between Skills and Prompts

A prompt is transactional:

"Refactor this function to use async/await but keep the error handling the same"

A skill is behavioral:

When refactoring, minimize diffs and preserve existing error patterns

The prompt handles one task. The skill handles an entire category of work.

I have skill files for:

• debug.md — how to investigate production issues
• database.md — Supabase patterns, migration rules
• api.md — REST conventions, error responses
• test.md — what to test, what to skip

Each file is under 50 lines. Together they eliminate maybe 80% of the repetitive instructions I used to type.

How Skills Create Compounding Leverage

They Transfer Across Projects

My api.md skill works identically across all four SaaS products. I wrote it once. It applies everywhere. When I open a new Claude session in any repo, the behavior is consistent.

They Encode Decisions

I don't have to remember why we return 204 on successful deletes instead of 200. It's in api.md. Claude knows. New Claude sessions know. My future self doesn't have to re-explain the decision.

They Reduce Context Switching

Without skills, I'd start a session thinking "okay, what are my preferences again?" With skills, I just say "refactor this component" and Claude already knows my stance on comments, abstractions, and diff size.

They Improve Over Time

When I notice Claude doing something I don't want, I add a line to the relevant skill file. That fix propagates to every future session. The system gets better without me thinking about it.

How to Start Building Skills

1. Track Your Repeated Instructions

For the next week, note every time you give Claude the same type of instruction twice. "Use kebab-case for file names." "Don't add tests for utility functions." "Check Supabase docs before suggesting new queries."

Those are skill candidates.

2. Start With One Category

Pick the work you do most often. For me, it was refactoring. Create a single markdown file with 3-5 rules. Keep it minimal. You can always add more.

3. Test and Refine

Use the skill file for a few sessions. Notice where Claude still guesses wrong. Add clarifying rules. Remove rules that don't actually change behavior.

4. Resist Over-Engineering

Don't try to document everything. Don't write essays. Skills work because they're concise. If a skill file hits 100 lines, split it.

What Skills Aren't

Skills aren't:

• Code templates (that's what snippets are for)
• Project documentation (that's your README)
• Exhaustive style guides (Claude won't read 50 pages)

They're behavioral defaults — the assumptions you want Claude to make when context is limited.

The Real Leverage

Most developers improve their Claude prompts linearly. Better prompt → better response. Then they start over next session.

Skills compound. Every refinement improves every future session. Every new project inherits the accumulated intelligence.

I've been running BuildNotBurn for six months with the same core skill files. They've been edited maybe a dozen times total. But they've influenced hundreds of Claude sessions across four products.

That's the difference between prompting and engineering.

You wouldn't rebuild your build system every time you compiled. Don't rebuild your AI context every time you open a chat.