Short answer: a Claude Code skill is a folder with a SKILL.md file in it. The file has a short YAML header (mainly a description that tells Claude when to use it) and a Markdown body with instructions. You can run it yourself with /skill-name, or Claude loads it on its own when your request matches the description. Use skills for procedures you keep re-typing (release notes, launch posts, support replies), keep CLAUDE.md for facts, and use a hook when a rule must run every single time.
Last updated: October 16, 2026. Grounded in the official Claude Code skills docs, hooks guide and subagents docs.
Most skills tutorials are written for teams: code review conventions, API style guides, monorepo deploys. Fine, but if you are building a product alone, the stuff you repeat every week is different. You write release notes. You rewrite the landing page. You draft a Reddit launch post and then delete the hype. You answer the same support email for the fifth time.
That is exactly what skills are good at. This guide covers the mental model in one table, a first skill you can build in five minutes, and eight SKILL.md files I would give any solo founder on day one.
Skills vs subagents vs hooks vs CLAUDE.md vs MCP
Claude Code has five ways to “teach” it something, and people mix them up constantly. Here is the version I keep in my head:
| Tool | What it is | When it loads | Use it for |
|---|---|---|---|
| CLAUDE.md | Always-on project notes | Every session, in full | Facts: stack, commands, “never do X” rules |
| Skill | A SKILL.md playbook | Description always listed, body only when used | Repeatable procedures and long reference material |
| Subagent | A separate agent with its own context | When Claude delegates to it | Noisy work you want out of your main context (research, big searches) |
| Hook | A script Claude Code runs on an event | Every time the event fires | Rules that must hold 100% of the time (format, block .env edits) |
| MCP server | A connection to an outside system | Tool names load when connected | Live data: GitHub, Supabase, Sentry, Stripe |
The key line from the official docs: unlike CLAUDE.md content, a skill’s body loads only when it is used, so long reference material costs almost nothing until you need it. That is why “move procedures out of CLAUDE.md into skills” is one of the easiest wins in reducing Claude Code token usage.
One more thing that confuses people: custom commands were merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files still work, but new work should be skills, because skills can hold supporting files and control who triggers them.
Build your first skill in 5 minutes
Let’s build a skill that summarizes your uncommitted changes. It is small, safe, and useful every day.
1. Create the folder. Personal skills live in your home directory and work in every project on your machine:
mkdir -p ~/.claude/skills/what-changed**2. Write SKILL.md.** Save this as ~/.claude/skills/what-changed/SKILL.md:
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in 2-3 bullets, then list risks: missing error handling, hardcoded values, secrets, tests that need updating. Then propose a one-line commit message. If the diff is empty, say so.The line that starts with ! and a command in backticks is dynamic context injection: Claude Code runs git diff HEAD first and pastes the output into the prompt, so Claude works from your real diff instead of guessing.
3. Test it two ways. Start claude in any git repo with a small edit, then either type /what-changed or just ask “what did I change?” If the description is good, Claude picks the skill on its own.
That’s it. The folder name became the command. No restart dance, no config file.
Where to save skills
| Location | Path | Who gets it |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | You, in every project on this machine |
| Project | .claude/skills/<name>/SKILL.md | Anyone who clones the repo (commit it) |
| Plugin | <plugin>/skills/<name>/SKILL.md | Anyone who installs the plugin, as /plugin-name:skill-name |
If the same name exists in both places, the personal one wins over the project one.
The five frontmatter fields worth knowing
All fields are optional, but these are the ones I actually use:
description: the trigger. Put the main use case first. Combined withwhen_to_use, it gets cut at 1,536 characters in the listing.disable-model-invocation: true: only you can run it. Use this for anything with side effects (deploy, publish, send).allowed-tools: tools Claude can use without asking, only during the turn that invokes the skill.context: fork(plusagent): run the skill in a separate subagent so its noise stays out of your main chat.argument-hint: shows what to type after the command, like[version].
You pass arguments with $ARGUMENTS (everything after the command) or $0, $1 for positions. /release-notes v1.4.0 makes $ARGUMENTS equal v1.4.0.
8 skills for solo founders (copy-paste SKILL.md files)
Put these in ~/.claude/skills/ if you want them everywhere, or in a repo’s .claude/skills/ if they depend on that product’s files. Each one is short on purpose: once a skill loads, its body stays in context for the rest of the session, so every line is a recurring cost.
1. Release notes from git history
~/.claude/skills/release-notes/SKILL.md
---
description: Write user-facing release notes from recent git commits. Use when preparing a release, version bump, or "what shipped" post.
argument-hint: [since-tag]
disable-model-invocation: true
---
## Commits
!`git log --oneline --no-merges $ARGUMENTS..HEAD`
## Instructions
Write release notes for customers, not developers:
- Group into New, Improved, Fixed. Skip internal refactors, deps and CI.
- One line per item, in plain words, starting with the benefit.
- No commit hashes, no ticket numbers.
- End with one sentence on what to try first.
If a commit message is unclear, list it under "Needs a human" instead of guessing.Run it as /release-notes v1.3.0. I make this one manual-only because I don’t want Claude deciding it’s release day.
2. Changelog entry
.claude/skills/changelog/SKILL.md
---
description: Add an entry to CHANGELOG.md in Keep a Changelog format. Use after finishing a feature or fix, or when asked to update the changelog.
---
## Staged and unstaged changes
!`git diff HEAD --stat`
## Instructions
1. Read CHANGELOG.md. If it doesn't exist, create it with an "Unreleased" section.
2. Add bullets under Unreleased using Added / Changed / Fixed / Removed.
3. Match the tone of existing entries. One line each.
4. Don't touch released sections.3. Landing page copy
.claude/skills/landing-copy/SKILL.md
---
description: Draft or rewrite landing page copy (hero, subhead, features, FAQ) for this product. Use when the user asks for homepage, landing page, or marketing copy.
---
Read README.md and docs/positioning.md (if it exists) first.
Rules:
- Hero: under 10 words, says what it does for whom. No "revolutionize", "seamless", "unlock", "supercharge".
- Subhead: one sentence with the concrete outcome.
- 3 features max, each as "benefit, then how".
- FAQ: answer the 4 objections a skeptical buyer would have (price, data, setup time, lock-in).
- Give 2 alternative hero lines, then stop.The real trick here is docs/positioning.md: a half-page file with who the product is for, the main pain, and the one thing you do better. Write it once and every copy task gets better.
4. SEO article outline
~/.claude/skills/seo-outline/SKILL.md
---
description: Turn a target keyword into a blog post outline with search intent, H2s and FAQs. Use when planning an article or when the user gives a keyword.
argument-hint: [keyword]
---
Keyword: $ARGUMENTS
Produce:
1. Search intent in one line (informational, comparison, tutorial, buying).
2. A title under 60 characters that contains the keyword naturally.
3. A 3-sentence direct answer for the top of the post.
4. 5-7 H2s in the order a reader needs them.
5. 4 FAQ questions people actually ask.
6. What I must add from my own experience (screenshots, numbers, a mistake I made). Mark these as TODO, never invent them.Point 6 matters. The fastest way to make AI-assisted content worthless is letting it invent “my results.” This skill forces the gaps to show up as TODOs.
5. Launch posts that don’t sound like ads
~/.claude/skills/launch-posts/SKILL.md
---
description: Draft launch posts for Show HN, Reddit and X from the product README. Use when the user is launching, announcing, or sharing the product.
disable-model-invocation: true
---
Read README.md. Then draft:
- Show HN: title "Show HN: <name> - <what it does>", plus a short first comment: why I built it, what's rough, what feedback I want.
- Reddit: a post that is useful even if nobody clicks the link (the problem, how I solved it, one lesson). Link at the end, once.
- X: 3 posts, each standalone, no hashtags, no emoji walls.
Banned: "game-changer", "excited to announce", fake urgency, invented user counts.
Show all drafts, don't post anything.6. Support reply from your docs
.claude/skills/support-reply/SKILL.md
---
description: Draft a reply to a customer support email using the product docs. Use when the user pastes a customer message or asks how to answer a user.
argument-hint: [paste the customer message]
---
Customer message:
$ARGUMENTS
1. Search docs/ and README.md for the answer. Quote the relevant file path.
2. Draft a reply: thank them in one line, answer in plain steps, offer one next step.
3. If the docs don't answer it, say "Not in docs" and suggest what doc page to add.
4. If it's a bug, add a short internal note with repro steps for the issue tracker.
Never promise refunds, dates or features.The “suggest what doc page to add” line is the quiet win: after a month you have a list of missing docs written by your actual customers.
7. Security pass before launch (runs in a subagent)
.claude/skills/security-pass/SKILL.md
---
description: Read-only security review of the app before launch: secrets, auth checks, Supabase RLS, Stripe webhooks. Use before shipping or when asked to audit security.
context: fork
agent: Explore
disable-model-invocation: true
---
Audit this repository, read-only. Check:
1. Secrets in code or committed .env files.
2. Server routes that trust a user id from the client.
3. Supabase tables without RLS, or policies using "true".
4. Stripe webhook handlers that don't verify the signature.
5. Admin or debug routes reachable in production.
For each finding: file path, line, why it matters, a one-line fix. Rank by risk. If nothing found for a check, say "checked, clean".context: fork with agent: Explore runs this in a separate read-only agent, so a long audit doesn’t flood your main conversation. One catch from the docs: the Explore agent starts without your CLAUDE.md, so everything it needs has to be in the skill itself. The full list behind these checks is in the vibe-coded app security checklist.
8. A verify skill that runs before every commit
.claude/skills/verify/SKILL.md
---
description: Verify the app still works before a commit: typecheck, tests, build. Use before committing code changes.
---
Run, in order, and stop at the first failure:
1. npm run typecheck
2. npm test -- --run
3. npm run build
If something fails, show the error and fix it before committing. Don't skip a step because the change "looks small".This one has a special behavior: according to the docs, when a project skill named verify (or simplify) is present at session start, Claude Code’s commit instructions tell Claude to run it right before each commit, except for docs-only or test-only changes. That needs Claude Code v2.1.286 or later, and it doesn’t work if you set disable-model-invocation: true on it. Swap the commands for your stack.
Pitfalls I’d avoid
Vague descriptions. The description is the trigger. “Helps with marketing” will either never fire or fire on everything. Write it like “Draft launch posts for Show HN, Reddit and X. Use when the user is launching…” and include the words you’d naturally type.
Too many skills. Every skill’s name and description sits in context on every turn, whether you use it or not. If the list gets too big, Claude Code starts dropping descriptions of the skills you use least. Run /skill-doctor to see what each skill costs and how often it fires, and turn off the dead ones.
Failing injected commands. If a command inside the skill exits non-zero, the whole skill invocation aborts and Claude never sees the instructions. git log on a repo with no tags is a classic. Append || true to commands that might legitimately fail.
**Trusting other people’s allowed-tools.** A project skill can pre-approve tools for itself, and workspace trust doesn’t gate that field. Before running Claude Code in a repo you just cloned, read its .claude/skills/ folder.
Long sessions. After auto-compaction, Claude Code keeps only the first 5,000 tokens of each invoked skill (25,000 total across skills). Put the most important rules at the top of SKILL.md, and re-run the skill if Claude starts drifting.
When to use a hook instead
A skill is guidance. Claude follows it with judgment, which means it can skip a step. The official troubleshooting advice is direct: if Claude skipped a rule that must hold every time, move the rule into a hook.
Two hooks every solo project should have, in .claude/settings.json. Auto-format after every edit:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
]
}
]
}
}And block edits to files Claude should never touch. Save this as .claude/hooks/protect-files.sh and chmod +x it:
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
for pattern in ".env" "package-lock.json" ".git/"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0Then register it as a PreToolUse hook with the same Edit|Write matcher and the command "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh. Exit code 2 blocks the edit and tells Claude why. Both examples need jq installed.
My rule of thumb: if breaking the rule once would cost you real money or data, it’s a hook. If it’s about quality or style, it’s a skill.
Sharing skills across projects (and other tools)
- Personal folder:
~/.claude/skills/is the simplest way to reuse skills in every project. Skill folders there can be symlinks, so you can keep the real files in one git repo and link them in. - Commit to the repo: project skills in
.claude/skills/travel with the code. Do this for anything that reads product-specific files (landing copy, support replies, verify). - Cloud sessions and routines: these don’t read
~/.claude/skills/on your laptop. If a scheduled run says a skill wasn’t found, commit it to the repo or enable it on your claude.ai account. - Other tools: Claude Code skills follow the open Agent Skills standard. If you plan to upload a skill to claude.ai or use it elsewhere, stick to the six portable frontmatter fields (
name,description,license,compatibility,metadata,allowed-tools). Extra fields likeargument-hintcause a hard error on upload.
If your repo already has an AGENTS.md for Codex or Cursor, keep facts there and procedures in skills. The CLAUDE.md vs AGENTS.md guide covers how to share one set of instructions across tools.
FAQ
What’s the difference between a Claude Code skill and a slash command?
They’ve been merged. A .claude/commands/name.md file and a .claude/skills/name/SKILL.md skill both create /name. Skills add a folder for supporting files, auto-triggering from the description, and controls like disable-model-invocation.
Why isn’t my skill triggering?
Check that the description contains words you actually say, ask Claude “What skills are available?” to confirm it loaded, and try /skill-name directly. If the YAML header is broken, the skill still loads but without a description, so Claude can’t match it. claude plugin validate ~/.claude/skills finds files with bad frontmatter.
Do skills cost tokens when I’m not using them?
A little. Names and descriptions are always listed so Claude knows what exists. The full body loads only when the skill runs. Skills you mark disable-model-invocation: true don’t put their description in context at all.
Should I use a skill or an MCP server?
Use a skill for a procedure Claude can do with the tools it already has (read files, run git, edit code). Use MCP when Claude needs a live outside system like your database or error tracker. The best MCP servers for Claude Code post covers the short list worth connecting.
Can a subagent use my skills?
Yes. A custom subagent in .claude/agents/ can list skills in a skills: field, and their full content is injected when it starts. You can’t preload skills that set disable-model-invocation: true.
Start with one skill this week, the one for the task you’ve typed out most often. If it saves you ten minutes twice, write the second one.