Claude Code Skills: What They Are and How Teams Use Them
A new engineer joins the project, opens Claude Code, and asks it to run a database migration. Claude does it the wrong way, because the right way lives in a Notion page nobody linked. So someone pastes the same six paragraphs of "here is how we run migrations" into the session by hand, again, the way they did for the last three hires. A Claude Code skill is the fix for exactly that: the procedure, written down once, in the repo, that Claude reaches for on its own.
A Claude Code skill is a folder holding a SKILL.md file: some YAML metadata plus Markdown instructions Claude loads when a task matches, per the Claude Code skills reference. It is the same Agent Skills format Anthropic ships across its products, but stored in your codebase so the whole team's Claude Code follows the same playbook.
If you want the general concept, including how skills differ from MCP and a CLAUDE.md file, we covered that in what Claude Skills are. This post is narrower: skills as they work inside Claude Code, the coding agent, where they get committed to a repo and shared through git. For the ops angle on which skills are worth writing at all, see the best Claude skills for a lean ops team.
What a Claude Code skill actually is
At the center of every skill is one required file, SKILL.md. It has two parts. First, YAML frontmatter between --- markers, holding at minimum a name and a description. Then the Markdown body, which is the actual instructions Claude follows once the skill is in play. That is the whole minimum. A skill can be one file.
The description field is the load-bearing part. Claude reads it to decide whether the skill is relevant to what you just asked, so a vague description means the skill never fires when you need it, per the Claude Code skills docs. "Run our database migrations" is worse than "Run Postgres migrations for this repo using the Prisma workflow, including the staging dry-run and the rollback check."
Around that file, a skill can bundle whatever the job needs:
- Scripts Claude runs when deterministic code beats free-form generation, like a shell script that lints and formats before a commit.
- Reference files Claude opens only when a specific detail is required, so the main instructions stay short.
- Templates or config the task reuses, like a PR description skeleton or a test scaffold.
The mental model for a technical operator: a skill is a runbook Claude can execute, not just read. The step-by-step you would otherwise re-explain every session becomes a file the agent picks up on its own.
Where Claude Code skills live: personal, project, and plugin
This is where Claude Code skills earn their keep over a chat trick. They live on the filesystem, in one of three places, and the location decides who gets them.
| Type | Location | Who it reaches |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | Just you, across every project on your machine |
| Project | .claude/skills/<name>/SKILL.md in the repo | Anyone who clones the repo, committed and versioned in git |
| Plugin | Bundled inside an installed Claude Code plugin | Whoever installs that plugin |
Those paths come straight from the Claude Code settings docs. The distinction that matters most for a team is the middle row. A project skill sits in .claude/skills/ at the repo root, gets committed like any other file, and travels with the code. When a teammate pulls the branch, their Claude Code has the same skill yours does. The migration runbook, the deploy checklist, the "how we write tests here" convention, all become versioned team knowledge instead of tribal memory in one person's head.
Personal skills are private to your environment and follow you between projects. Plugin skills come packaged with an installed plugin and are managed with it, which is how you distribute a skill across many repos at once without copy-pasting folders.
How Claude Code decides to use a skill
There are two ways a skill fires, and knowing both saves confusion.
The first is automatic. Claude scans the name and description of the available skills, and when your request matches one, it loads that skill's instructions on its own. You never mention the skill. You ask for the task, and the right runbook shows up.
The second is manual. You type /skill-name in Claude Code to invoke a skill directly, the same way a slash command works, documented in the skills reference. Useful when you know exactly which procedure you want and do not want to leave it to the description matching.
Underneath both sits a loading model Anthropic calls progressive disclosure, described in its Agent Skills overview. Claude reads only the lightweight metadata first to judge relevance, loads the full instructions only if the skill is selected, and opens bundled files or runs scripts only when the task reaches them. So a skill can carry a lot of reference material without taxing the context window until a detail is actually needed. That is why a skill scoped to one job, with a sharp description, behaves better than a sprawling one that triggers at the wrong times.
Claude Code skills vs slash commands, subagents, and CLAUDE.md
All four feel like "ways to customize Claude Code," which is why they get muddled. They do different jobs.
| Feature | What it is | How it loads |
|---|---|---|
| CLAUDE.md | Standing project instructions | Always in context, every session |
| Skill (SKILL.md) | A reusable procedure or runbook | Loaded when relevant, or invoked with /name |
| Slash command | An explicit action you type | Only when you type /name |
| Subagent | A separate agent worker for a subtask | Spawned to run in its own context |
The clean way to hold it: your CLAUDE.md is the always-on rules for the repo, the stack, the conventions. A skill is a specific job Claude should know how to do when it comes up. A subagent delegates a chunk of work so it does not clog the main conversation's context. These are not competitors. A real setup uses CLAUDE.md for the guardrails and a handful of project skills for the repeatable procedures, per Anthropic's skills documentation.
Do you need to build your own?
For a technical team that already lives in Claude Code, yes, and the payoff is concrete. Write project skills for the three or four procedures you re-explain most, commit them, and every session across the team starts from the same playbook. Start with the runbook that hurts when a new person gets it wrong: the deploy, the migration, the release checklist. The mechanics of writing one from scratch are in how to build a custom Claude skill.
But there is a line a skill does not cross, and it is the line most operators actually care about. A skill runs inside an interactive Claude Code session, when a person is at the keyboard driving it. It does not fire when a lead lands in your form, when a PDF hits an inbox, or on a schedule at 6am. The moment you want the work to happen unattended, on a trigger, writing back into your CRM or your database with error handling and monitoring, you are no longer talking about a skill. You are talking about a workflow.
That gap is where working with bottta is the honest recommendation. We design and build the automation on two fronts. We author the project skills committed to your repo, with sharp descriptions and the scripts they need, so your team's Claude Code follows one playbook instead of everyone's private version. And we build the part a skill cannot reach: the triggered workflow that runs without a person in the loop, the integrations that connect the tools, the LLM extraction and routing where judgment is needed, and the monitoring that pages someone when a run fails. That is Workflow Design, Integrations, AI Automation, and Custom Builds, on a $3K/month retainer (up to 3 active workflows, ongoing monitoring and fixes) or a fixed-scope $4K project (integrations included, 30-day post-launch support).
You can also stitch triggers together yourself with Zapier, Make, or n8n, and for a simple two-step handoff that is a reasonable first move. See when to automate a task and when not to for where DIY glue pays off. The build is worth handing off once the workflow spans several systems, needs to be reliable, and nobody on the team owns keeping it alive.
If a Claude Code skill is the runbook and the workflow is the machine that runs it while you sleep, start a project with bottta and we will build both.
Frequently asked questions
Are Claude Code skills the same as Claude Skills?
Same format, different surface. Both are folders with a SKILL.md file, the Agent Skills standard Anthropic introduced in October 2025. "Claude Code skills" specifically means skills used inside the coding agent, stored in .claude/skills/, where they can be committed to a repo and shared with a team.
Where do I put a skill so my whole team gets it?
In .claude/skills/<name>/SKILL.md at the repo root, then commit it. Anyone who clones the repo gets the skill, since it is versioned in git like any other file, per the settings docs. Personal skills go in ~/.claude/skills/ and stay on your machine.
Do I have to invoke a skill manually?
No. Claude auto-selects a skill when your request matches its description, which is why a specific, well-written description matters. You can also force it by typing /skill-name when you want a particular procedure.
Can a Claude Code skill run on a schedule or a webhook by itself?
No. A skill runs during an interactive session with a person driving it. To run work on a trigger, unattended, you wire the procedure into a workflow with a scheduler or webhook, connected systems, and monitoring. That is a build, not a skill, and it is the part bottta puts together for lean teams.
Do skills work outside Claude Code?
The SKILL.md format also runs in the Claude apps and through the API, but skills do not sync across those surfaces automatically. You deploy the same file to each place you want it, per the Agent Skills overview. For more on running Claude across a small business, see Claude for small business.