Short answer: a Claude Code skill is a folder with a SKILL.md file: instructions Claude loads when your task matches the skill's description. Keep project skills in .claude/skills/ and commit them. To install one from GitHub, run npx skills add <repo> --skill <name>, pinned to one commit, after reading every file and checking whether it runs code. I made one myself: the free MVP System Design skill.
What a skill is
If you keep pasting the same checklist into the chat, how to release or how to test, make it a skill. Write it once; Claude uses it whenever a task calls for it.
A skill is a folder with a SKILL.md file: a short header between two --- lines, then the instructions. The header's description tells Claude when to use the skill. The folder's name becomes a command: type / and the name to start the skill yourself. A whole skill, saved as .claude/skills/tests/SKILL.md:
--- description: How to write and run tests here. Use when you change code or fix a bug. --- 1. Write a test that fails first, then make it pass. 2. Run all tests with <command>. They must pass before every commit. 3. Coverage under <N>% fails the build. Never lower the bar.
Unlike CLAUDE.md, the rules file Claude reads in full every session, a skill shows Claude only its name and description until it's used, so a long procedure costs next to nothing. A skill can also hold reference files Claude reads when needed, and scripts it runs. Skills follow an open standard, Agent Skills, used across several AI tools.
Where skills live
Where you save a skill decides who gets it.
| Kind | Folder | Who gets it |
|---|---|---|
| Project | .claude/skills/<name>/SKILL.md | everyone in this repository: commit it |
| Personal | ~/.claude/skills/<name>/SKILL.md | only you, in every project on this computer |
| Plugin | the plugin's own skills/ folder | whoever installs and turns it on |
| Company | a folder your IT team manages | every user on the company's computers |
If two skills share a name, a personal one beats a project one, and a company one beats both. Claude Code picks up new and changed personal and project skills in the same session, without a restart; if the skills folder itself is new, run /reload-skills. Type /skills to list what Claude can use.
All of this is from Anthropic's documentation on skills, checked on 7 November 2026.
How to install a skill
Installing just means putting the folder in one of those places. There are three ways.
Copy the folder into .claude/skills/, after reading it.
Use the skills tool. This free, open-source tool from Vercel Labs fetches skills from GitHub into the right folder. It needs Node.js 22.20 or later (ask Claude to help you install it). Run the tool in your project folder, or ask Claude to:
npx skills add <owner/repo> --list npx skills add <owner/repo>@<commit> --skill <name> -a claude-code
The first line lists a repository's skills without installing them. The second installs one, for Claude Code, into this project; -g installs it for all your projects. The @<commit> part, with the full commit id, pins it. A repository is a project's code with its whole history, and a commit is one saved version of it, so a pinned skill is exactly the text you read. Commands from the tool's reference, checked the same day.
Install a plugin. A plugin is a package that can hold several skills plus extras such as hooks, small commands Claude Code runs at set moments. Type /plugin in Claude Code to browse and install them; their skills run as /plugin-name:skill-name. A single skill doesn't need a plugin. More in Claude Code plugins.
How to vet a skill
A skill briefs your AI agent inside your project. Installing one unread is like letting a stranger brief your developer. Check it first:
- Read every file, not only
SKILL.md. Claude may open the others later. - Check whether it runs code. Four signs: a
scriptsfolder or program files, such as.pyor.sh; a line starting with!and a command in backticks, or a block opening with```!, which Claude Code runs before Claude reads the skill;allowed-toolsin the header, which lets Claude use those tools without asking you while the skill runs; andhooksin the header, commands that keep firing for the rest of the session. Code isn't bad in itself (Anthropic's first example skill runsgit diff); just know what runs and why. - Pin the version, as above, so nothing changes until you decide.
- Prefer plain Markdown: plain text with none of the four signs, so nothing to run. Text can still give Claude bad orders, so read it anyway.
- Look for hidden instructions: lines aimed at the AI, not at you, such as an order buried in a long reference file. If one tells Claude to send data somewhere, change settings or skip your checks, don't install.
- Read the skills in any repository you clone. They come with it, and Anthropic warns that their
allowed-toolsapply even in a folder you never marked as trusted.
For one more lock, ask Claude to add "disableSkillShellExecution": true to ~/.claude/settings.json, your personal settings file: Claude Code then skips the ! commands in skills you add.
A real example: four SEO skills
This site was built with Claude Code. In November 2026 I added four SEO skills to its repository. Here is how:
- Every file was read before anything was installed.
- They were installed pinned to one commit, recorded in a
skills-lock.jsonfile in the repository. - They live in the repository, in
.claude/skills/, so every session gets the same version. - Before the first use, the files were checked for hidden instructions.
They are plain Markdown, so nothing in them runs. And an update arrives as an ordinary pull request, a request to merge a change after review, where the new text can be read before any session uses it.
Which skills matter for a production app
Skip the top-10 lists. Once real customers use your app, the skills that matter cover four jobs: tests, code review, security and releases. Claude Code ships help for three:
| Job | Built into Claude Code | What your own skill adds |
|---|---|---|
| Tests | /verify runs your app to check that a change works | your test command and coverage bar |
| Code review | /code-review finds bugs in your changes; --fix fixes them | your review priorities |
| Security | /security-review checks your changes for risks like broken sign-in or exposed data | your rules for secrets and personal data |
| Releases | nothing | the steps, started only by you |
Give your release skill disable-model-invocation: true in its header, and only you can start it: Claude can't run it on its own, however ready the code looks.
MVP System Design, my skill plus rules for the agent, shows how much one skill can cover. Its 16 chapters: system design, stack, folders, logs, dev, stage, prod (your computer, a rehearsal copy, the live app), release, cloud, alerts, tasks, tests, code quality, UI, security and rate limits (caps on repeated actions). It enforces 99% test coverage: tests must run 99% of the code. It's plain instructions for the AI, with no code to run, and free under the MIT license. Short version: the production-ready checklist.
Install only what you'll use. Each skill Claude may use adds its description to every session; with many installed, Claude Code drops some descriptions to fit, and Claude can miss the one you need. /skill-doctor shows what each costs and how often it runs.
Skill, CLAUDE.md, hook or plugin?
- CLAUDE.md: facts and rules for every task, loaded every session.
- A skill: a procedure you need some of the time. Anthropic's rule of thumb: when part of your CLAUDE.md grows into a procedure, make it a skill.
- A hook: a rule that must never break. Claude can skip an instruction; Claude Code runs a hook every time. See Claude Code hooks.
- A plugin: a whole setup, several skills and hooks, shared across projects or a team.
Next: what to put in CLAUDE.md. Building with Codex? Read Codex skills. The whole workflow: Claude Code best practices. All guides: articles.