Claude Code Skills: How SKILL.md Works and Where

Claude Code skills are folders with a SKILL.md file that teach Claude Code one repeatable job: how to write a kickoff doc from a proposal, or how to review a lead list. Claude loads the skill when a request matches its description, or you run it yourself with a slash command. We use them for most of the recurring work in our builds, and this post covers how they are laid out, how we write them, and where we have been burned.

What a Claude Code skill is

A skill is a directory. The only required piece is SKILL.md: YAML frontmatter between two --- lines (it has to be the first line of the file), then plain Markdown instructions. Next to it you can put reference files and scripts. A typical layout looks like this:

my-skill/
  SKILL.md        # overview and steps
  reference.md    # loaded only when needed
  examples.md
  scripts/
    helper.py     # executed, not read into context

The part that matters for cost is when things load. Claude sees each skill's name and description up front, and the body only comes in when the skill is used. A CLAUDE.md file is different: it is always in context. If a section of your CLAUDE.md has turned into a procedure ("when releasing, do these nine steps"), it belongs in a skill.

Where Claude Code skills live

A personal skill goes in ~/.claude/skills/<skill-name>/SKILL.md and follows you across projects. A project skill goes in .claude/skills/<skill-name>/SKILL.md inside the repo, so everyone who clones it gets the same behavior. Plugins can ship skills too, invoked as /plugin-name:skill-name, and managed settings can supply enterprise skills.

We put anything tied to a client build in the project folder and commit it. If the skill encodes how we work in general (our code review checklist, our handoff format) it lives in the personal folder. When two skills share a name, enterprise beats personal and personal beats project, so avoid reusing a name across levels unless you mean to override.

The frontmatter that does the work

Every field is optional, but description is the one to get right, because Claude uses it to decide whether to load the skill. These are the fields we touch most often:

A minimal working skill, adapted from the pattern in Anthropic's docs:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed.
allowed-tools: Bash(git diff *)
---

## Current changes
!`git diff HEAD`

Summarize the changes above in two or three bullets, then list any risks.

The ! followed by a backticked command runs the command and injects its output before Claude reads the skill. That is how a skill gets live data without Claude spending a turn fetching it.

Skills vs slash commands vs CLAUDE.md

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. So the question is less "skill or command" and more "does this job need supporting files or extra frontmatter". If yes, use a skill directory.

Skills we run in real builds

The clearest examples are on our verified lead list automation page. A Claude Code skill makes the fit calls on each row of a lead list, and Python scripts do everything that needs to be exact: dedupe, email lookups, verification. The split matters. The model is good at judgment (is this person a buyer?) and bad at arithmetic and API bookkeeping, so we give each job to the right tool.

The same pattern shows up in our Stripe deposit to kickoff run, where a skill writes the kickoff document from the accepted proposal after the webhook and CRM steps have already happened. If you want to see the pattern across more builds, the automations hub lists them all.

Mistakes we would avoid

Vague descriptions. "Helps with emails" matches everything and nothing. A description that names the trigger ("Use when the user asks for a reply summary") gets loaded when it should and left alone when it should not. The description plus when_to_use is truncated at 1,536 characters in the listing, so put the trigger first.

Letting a skill with side effects run automatically. Anything that sends a message, moves a deal or spends credits gets disable-model-invocation: true. We would rather type a slash command than find out Claude decided the skill matched.

One giant SKILL.md. The docs recommend staying under 500 lines. Past that, split reference material into its own files and point to them from the main file. Also keep in mind that a loaded skill stays in context for the rest of the session, so long skills have a real cost in a long session.

Skipping the scripts. If a step is deterministic, such as hashing a value, formatting a date or merging two files, write it as a script in the skill folder instead of describing it in prose. Scripts are executed, not read into context, and they do not drift between runs.

Volatile facts, as of November 5, 2026

Skills are one of the faster-moving parts of Claude Code. Per Anthropic's skills docs today: after auto-compaction, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each within a combined 25,000-token budget. Nested skill prefixes in monorepos need v2.1.309 or later. The /skill-doctor command needs v2.1.252 or later. Edits under the skills folders apply without a restart, but a new top-level skills directory needs /reload-skills. Re-check the Claude Code skills documentation before you depend on any of these numbers.

What we would do

Start with one skill for the one task you repeat weekly, not a library. Write the description around the trigger, set disable-model-invocation if the task has any side effect, and move the exact steps into a script. Run it a few times, watch where Claude improvises, and tighten those lines. Add a second skill only after the first one runs without you correcting it.

If the skill is part of a larger workflow that touches your CRM, email tool or payment processor, that is where our Claude Code work usually starts: the skill handles judgment, scripts and workflow tools handle the rest, and a human approves the steps that cost money or reach a customer.