Ship Claude Code skills inside your client's repo

A Claude Code skill is a folder with a single SKILL.md file inside it. That file holds instructions Claude adds to its toolkit — a checklist, a playbook, a multi-step procedure you'd otherwise paste in by hand every time. The trick that makes it powerful for client work is where the folder lives. Put it in the repo, and the skill is part of the codebase. It clones when the repo clones. So the engineer who joins on Tuesday opens Claude in that project and it already knows the client's deploy steps, their naming rules, the one migration that always breaks prod — before anyone types a word of context.

There are two places Claude Code looks, and the difference is exactly who gets the skill:

Every skill is one directory whose entrypoint is SKILL.md. That file has two parts: YAML frontmatter between --- markers, then the markdown body. The frontmatter is metadata; the body is the playbook Claude follows when the skill runs.

• name — optional. If you leave it out, it defaults to the directory name. (For project and personal skills the command you type is taken from the folder name regardless, so name is really just the display label.)
• description — the field that matters. Claude reads this to decide when the skill applies. This single line is the biggest determinant of whether your skill ever fires. The docs recommend it for exactly that reason; without it, Claude falls back to the first paragraph of the body, which is rarely as sharp.
• The body — everything after the closing ---. The actual instructions: steps, rules, guardrails. Keep it tight; once a skill loads it stays in context for the session, so every line is a recurring cost.

Here's a complete, copy-paste skill for the exact job from the video — deploying a client's app. Drop it at .claude/skills/deploy-client/SKILL.md:

---
name: deploy-client
description: Deploy this client's app to production. Use when the user
  asks to deploy, ship, release, or push live — runs the client's exact
  build, migration, and smoke-test steps in order.
disable-model-invocation: true   # you decide when to deploy, not Claude
---

# Deploy <client> to production

Follow these steps in order. Stop and report if any step fails.

1. Confirm the branch is `main` and the tree is clean (`git status`).
2. Run the test suite: `npm test`. Do not continue on a failure.
3. Build: `npm run build`.
4. Apply DB migrations against production: `npm run db:migrate:prod`.
   NOTE: the 2023-loyalty migration must run BEFORE the billing one —
   reversing them has taken prod down here before.
5. Deploy: `npm run deploy:production`.
6. Smoke-test the live URL and report the HTTP status of `/health`.

Here's the part the short couldn't fit. Claude doesn't run every skill on every turn. In a normal session it loads each skill's description into context — just the description, not the whole body — and when your request matches one, it loads that skill's full instructions and uses it. That's "model-invoked routing": Claude reads the description and decides. You don't wire up triggers; the description is the trigger.

Be clear-eyed about it though: auto-activation is not guaranteed every time. Anthropic's own troubleshooting covers both failure modes — a skill that never fires, and one that fires too often. So treat auto-routing as a convenience, not a contract. For anything high-stakes (a deploy, a destructive migration) invoke it explicitly by typing /skill-name. That always works, regardless of how the description is written.

Which means the description carries the whole load. Write it as a crisp "use when…" intent sentence, packed with the words a teammate would actually type. Compare:

A skill isn't limited to SKILL.md. The folder can hold supporting files alongside it — templates Claude fills in, reference docs it loads only when needed, and scripts it actually executes. SKILL.md stays the short overview; the heavy material sits beside it and loads on demand, so it costs almost nothing until it's used. Reference each file from SKILL.md so Claude knows what it is and when to reach for it.

One detail that saves you a debugging session: when a skill runs a bundled script, reference it through the ${CLAUDE_SKILL_DIR} variable, not a relative path. That variable resolves to the skill's own directory no matter where it's installed (project, personal, or plugin) and no matter the current working directory — so the same skill works for every client without edits.

.claude/skills/deploy-client/
+-- SKILL.md            # the playbook (required)
+-- checklist.md         # pre-deploy gate Claude reads when needed
+-- env.example          # the env vars this client's deploy expects
+-- scripts/
    +-- smoke.sh         # run via ${CLAUDE_SKILL_DIR}/scripts/smoke.sh

When you're shipping skills into several client repos, a little structure keeps them consistent. Each skill is its own folder under .claude/skills/; group them by job, give each a sharp description, and keep one house style across clients so an engineer who moves between accounts isn't relearning conventions. A sensible layout for a client repo:

.claude/
+-- skills/
    +-- deploy-client/
    |   +-- SKILL.md
    |   +-- scripts/smoke.sh
    +-- db-migrate/
    |   +-- SKILL.md
    +-- pr-review/
    |   +-- SKILL.md
    +-- onboarding/
        +-- SKILL.md          # "how this client's stack fits together"

Two patterns worth standardising across every client:

• House skills vs client skills. Keep a master set of your agency's standard skills (deploy, migrate, review) in a template repo, then drop them into each new client's .claude/skills/ at kickoff. Tune only the client-specific bits (their deploy command, their gotchas) in the body.
• An onboarding skill per repo. A short, advisory skill (no disable-model-invocation) that explains how that client's stack fits together. Claude loads it when a new engineer asks "how does X work here", and they're productive without pinging you.

This is the move that makes skills worth the setup. Project skills are just files in the repo, so they go through git like everything else.

# in the client repo, after writing your skills
git add .claude/skills
git commit -m "Add deploy + migrate + review skills"
git push

From that moment, anyone who clones or pulls the repo gets the identical skills — the same deploy steps, the same guardrails, the same "use when" routing — with zero extra setup. No Slack message, no wiki page, no "here's how we deploy" call. The standards live where the work happens, in the editor, and they update the same way the code does: someone improves the deploy skill, opens a PR, and the whole team's Claude gets smarter on the next pull.

Both of these fail silently — no error, the skill just doesn't run — which is exactly why they eat an afternoon. Know them and you'll never lose that afternoon.

1. A vague or generic description — so Claude never routes to it. This is the number-one cause. Routing is the description; if it reads "deployment helper" instead of "use when the user asks to deploy / ship / release", nothing a person types matches it, and the skill sits there unused while you assume it's "not working". Fix: rewrite the description as a sharp "use when…" sentence with the literal words your team says (see section 03). And remember you can always force it with /skill-name to confirm the skill itself is fine and it's purely a routing miss.
2. Creating the .claude/skills/ directory mid-session. Claude Code watches its skill directories and picks up edits to existing ones live — but per the docs, a brand-new top-level skills directory that didn't exist when the session started needs a Claude Code restart before it's watched. So if you make .claude/skills/ for the first time while Claude is already running, your shiny new skill is invisible until you restart. Fix: create the directory, then restart Claude Code (after that, adding more skills inside it is picked up live).

Start to shared in five steps. This is the whole loop — from nothing to a skill every teammate inherits.

1. Make the folder. In the client repo: mkdir -p .claude/skills/deploy-client. If .claude/skills/ didn't already exist, restart Claude Code now (gotcha 2).
2. Write SKILL.md. Paste the starter from section 02. Frontmatter (description first, written as "use when…") + the body steps.
3. Sharpen the description. Make sure it names the real words your team types — deploy, ship, release. This is what decides if it ever fires.
4. Test both ways. Invoke it explicitly with /deploy-client to confirm the body works, then phrase a natural request ("ship this to prod") to confirm routing picks it up.
5. Commit and push. git add .claude/skills && git commit && git push. Now every clone of this repo has it — the whole team, same standards, no copy-paste.