Claude Skills

I have a deploy process for one of our client projects. Seven steps. Check staging. Run tests. Create a release tag. Build the Docker image. Push to the registry. Update the config. Verify the health check.

I used to paste these steps into Claude Code at the start of every deploy session. Every time. Then I wrote them into CLAUDE.md. But CLAUDE.md loads on every conversation, even when I’m fixing a typo in a README. Those deploy instructions burned tokens on tasks that had nothing to do with deployment.

Then I moved them into a Skill. Now Claude only loads the instructions when I say “deploy” or when it recognizes I’m working on something deployment-related. The rest of the time, they cost about 100 tokens of metadata.

I now have 14 Skills across our projects. Deploy to staging. Deploy to production. Review for security. Generate a client report. Set up a new developer’s environment. Write a migration. Each started as something I kept repeating. Each is now something I never think about. It’s like writing an SOP that your best employee memorizes instantly and follows perfectly every time.

What a Skill is

A Skill is a folder with a SKILL.md file in it. The file starts with a small YAML header (name and description), followed by Markdown instructions telling Claude how to do something. No SDK. No API. No compilation. Just a Markdown file in a folder.

Claude reads every installed Skill’s name and description at startup — about 100 tokens per Skill. When it decides a Skill is relevant, it loads the full instructions. Supporting files in the Skill folder (reference docs, example outputs, scripts) only load when the task specifically needs them.

This three-level loading is the critical difference from CLAUDE.md, where everything loads on every conversation. With Skills, deploy instructions only load when you’re deploying. The migration playbook only loads when you’re migrating. I tested this empirically. Our main project’s CLAUDE.md dropped from 800 tokens to 350 after I extracted five procedures into Skills, saving roughly 7,000 tokens per busy day across 15-20 sessions.

Skills vs everything else

Claude Code now has many extension points. The mental model:

CLAUDE.md is for facts that are always true. “We use TypeScript. Our API is at /api/v1/. Never use var.” Loads every conversation.

Skills are for procedures that apply sometimes. “Here’s how to deploy.” “Here’s how to write a migration.” Load only when relevant.

Hooks are for rules that must always be enforced, no exceptions. “Run prettier after every file edit.” Deterministic — fire every time.

MCP servers are for connecting to external services that require authentication. Supabase, GitHub, Vercel.

The simplest rule: CLAUDE.md for what’s always true. Skills for how to do things. Hooks for what must always happen. MCP for authenticated external services.

Skills vs MCP — the real debate

This is the most interesting question in AI tooling right now. MCP gives Claude the ability to interact with services. Skills give Claude knowledge about how to accomplish workflows.

For tools that already have a CLI, the benchmarks are clear. Scalekit ran 75 identical tasks through bare CLI, CLI plus a Skill file, and an MCP server. The MCP server used 7× to 32× more tokens. Reliability was 100% for CLI approaches versus 72% for MCP. At 10,000 operations per month, the cost difference was $3.20 versus $55.20.

The pattern: if the tool has a good CLI, write a Skill that teaches Claude how to use it. Reserve MCP for services that require OAuth or don’t have a CLI.

This matched my experience exactly. I ran both the GitHub MCP server and a GitHub CLI Skill for two weeks. The MCP server worked, but every operation took longer and Claude’s responses on non-GitHub tasks got worse (context bloat). I removed the MCP server, kept the Skill, and the difference was immediate. A 40-line Skill does the same job for a fraction of the token cost.

Writing Skills that work

Write the description carefully — it’s how Claude decides whether to load your Skill. Be specific about when it applies. “Deploys the current branch to the staging environment. Use when the user says ‘deploy to staging’ or ‘ship to staging’” beats “Helps with deployment stuff.”

Don’t over-explain. Claude already knows how to code. Only teach what it doesn’t know — your team’s conventions, your project’s quirks, your pipeline’s requirements. “Use the format feature/TICKET-123-short-description. Always include the ticket number from Linear” is useful. “Run git checkout -b to create a new branch” is wasted tokens.

Match precision to importance. Prose when multiple approaches are fine. Pseudocode when you have a preferred pattern. Executable scripts when consistency is critical. Keep SKILL.md under 500 lines and move detailed references to separate files in the Skill folder.

Skills also support advanced features: typed arguments for parameterized workflows, tool restrictions (a review Skill that can only read, not write), forked context for running in a separate subagent, and shell expansion that injects live data (current PR diff, git status) before Claude sees the prompt.

The ecosystem

Anthropic publishes official Skills for document creation (docx, pdf, pptx, xlsx) and reference implementations. Vendor Skills from Vercel, Cloudflare, Stripe, Supabase, and even OpenAI cover deployment, best practices, and framework conventions. Vercel ships a cross-agent CLI at skills.sh that installs Skills for seventeen different tools. Community directories catalog thousands of Skills.

Security note: Skills can execute arbitrary code through shell expansion and bundled scripts. Only install from sources you trust.

When to create a Skill

The second time you paste the same instructions into Claude Code, stop. Spend five minutes writing a Skill. You’ll never paste them again.

Your deploy process, code review checklist, migration steps, testing conventions — each becomes a Skill committed to git in .claude/skills/. Everyone on the team follows the same playbook. The “Never deploy during a client demo” line in our deploy Skill is there because we deployed during a client demo. The staging environment shared a database pool with production. The deploy recycled the pool. The client’s demo froze for twelve seconds. We added the calendar check that afternoon. Some lines in a Skill are instructions. Others are scar tissue.

The bottom line

Skills are the most important extension mechanism in AI tooling because they match how AI actually works. An LLM reads text and follows instructions. A Skill is text with instructions. No impedance mismatch. No protocol translation. Just prose the model reads and applies. When the model gets smarter, every Skill gets smarter with it.

Start with one Skill for whatever you paste into Claude most often. You’ll be surprised how much better it works when the instructions are structured, always available, and never forgotten.

This is the free web edition of Chapter 13. The full text — with complete Skill templates, advanced frontmatter examples, CI/CD integration patterns, and the full Skills vs MCP benchmark analysis — is available in 42: The AI Builder’s Stack, coming Q3 2026 on Amazon in hardcover, paperback, and digital.