What are Claude Code Skills?

Claude Code Skills are reusable Markdown-based workflows you invoke with a slash command (e.g. /commit, /ship, /qa). Each skill is a single file with frontmatter and instructions. When you type the slash command, Claude reads the file and follows the instructions for that specific task — turning a repeat workflow into one command.

Where are Claude Code Skills stored?

Skills live in two locations: project-level at .claude/skills/ inside your repo, and user-level at ~/.claude/skills/ for skills you want across all projects. Each skill is a single .md file. Claude auto-discovers them — no registration step. Project skills override user skills with the same name.

How do I create a Claude Code Skill?

Create a new .md file under .claude/skills/ (or ~/.claude/skills/ for global). Add frontmatter with at least 'description'. Write the workflow instructions in Markdown — Claude reads them and follows them like any prompt. Save the file, and type /your-skill-name in any Claude Code session to invoke it.

What's the frontmatter format for a Claude Code Skill?

Minimum: description field with a short trigger sentence ('Use this skill when…'). Common optional fields: name (auto-derived from filename if omitted), allowed-tools (whitelist for tool restrictions). The body of the file is the instructions Claude follows when the skill is invoked.

What's the difference between a Skill and a Subagent in Claude Code?

Skill = a workflow Claude runs in the same context (sees and edits your files directly). Subagent = a separate, isolated context spawned via the Agent tool, runs independently, returns a single result. Use a Skill for routine workflows; use a Subagent for parallelizable research or work you want isolated from the main context.

Can a Claude Code Skill trigger automatically?

Not on its own — skills are user-triggered via slash commands. For automatic behavior, use hooks (configured in .claude/settings.json) that fire on events like SessionStart, UserPromptSubmit, or PostToolUse. A common pattern: a hook detects a trigger, then suggests the user run a relevant skill.

Do Claude Code Skills work across projects?

Yes — skills stored in ~/.claude/skills/ are available in every project. Project-level skills (in repo/.claude/skills/) are scoped to that project and override user skills with the same name. This lets you keep generic skills (commit, debug) global and project-specific ones (deploy-prod, run-migrations) local.

Claude Code Skills — What They Are and How to Build Your Own

If you're using Claude Code on the same kinds of tasks every week — committing, shipping, debugging, QA-testing — you're rewriting the same prompts every time. Skills fix that.

A Skill is a Markdown file. You write the workflow once, save it under .claude/skills/, and from then on a single slash command runs it. /commit writes the commit. /ship opens the PR. /qa runs the test sweep. The workflow is captured, versioned, and reusable.

What a Claude Code Skill actually is

A skill is one file. Frontmatter on top, instructions in the body.

---
description: Quick commit with a clean message — never bypass hooks, never use git add -A
---
 
When the user runs /commit:
1. Run git status to see changes
2. Group related changes; suggest splitting if 2+ unrelated topics
3. Draft a conventional-commit message (feat/fix/chore/...)
4. Stage by name (no -A, no .), commit, push
5. Report the resulting commit URL

That's it. Save as .claude/skills/commit.md and /commit works from your next session.

Where Skills live

Two locations, both auto-discovered:

Project skills: .claude/skills/ inside your repo. Scoped to the project, version-controlled with the code.
User skills: ~/.claude/skills/ in your home directory. Available across every project.

Project skills override user skills with the same name. So you can have a global /ship for most projects and a custom one for a project that ships differently.

Frontmatter fields that matter

Field	Purpose
`description`	The trigger sentence Claude reads to decide when this skill applies. Keep it specific.
`name`	Optional. Auto-derived from filename if omitted.
`allowed-tools`	Optional. Restricts which tools the skill can use (e.g. `Read, Bash, Edit`).

The description is the part Claude actually reads to route requests. Write it as a trigger: "Use this skill when the user wants to deploy production." Not "This skill deploys production." The first one routes; the second one explains.

The patterns that ship

After building dozens of skills, the ones that consistently get used share three traits.

1. Single clear trigger. /commit is obviously for committing. /ship is obviously for shipping. Avoid /utilities-misc — no one remembers when to invoke it.

2. Idempotent first step. The skill starts by checking state (git status, npm test, current branch). If state is already clean, the skill exits without doing harm. You want to be able to run the skill twice and not break anything.

3. Reports back. The last step is always a summary: what was done, the URL/path of the artifact, what's pending. Without this, you don't know if the skill succeeded silently or stopped halfway.

Skills vs Subagents — when each wins

People confuse the two because both extend Claude Code. They're different tools.

A Skill runs in your main context. It sees your files, edits them, follows your conversation. Best for routine workflows where the result needs to land in your working tree.

A Subagent runs in a fresh, isolated context via the Agent tool. It can't see your conversation. It returns a single result back to the main session. Best for parallelizable research, second-opinion reviews, or anything you want walled off from main context.

If you're doing /commit, that's a Skill. If you're spawning three parallel research agents to investigate a bug from different angles, that's Subagents.

Skills + Hooks — automatic suggestion

Skills are user-triggered. For automatic behavior, pair them with hooks. A hook detects an event (PR opened, test failed, session started) and prints a suggestion: "Run /qa to test this branch." The user still triggers the skill — but the suggestion is automatic.

This combo keeps the workflow explicit (you approve every action) while removing the "what should I run now?" overhead.

Anti-patterns to skip

Don't write a skill for a one-off task. If you'll only run it once, just type the prompt. Skills are for repetition.

Don't write skills that depend on undocumented state. "Run /deploy and it'll work if you set MY_VAR" is fragile. Either check the env in the skill or document the requirement in the description.

Don't write skills longer than 100 lines. If your skill needs more than a page of instructions, it's probably 2 or 3 skills concatenated. Split them.

A first skill to try

If you're starting from zero, build /commit first. Everyone commits. The workflow is universal. Once /commit is in your hands you'll understand the rest of the surface in 10 minutes.

---
description: Quick commit and push. Drafts a clean conventional-commit message from the staged + unstaged diff. Never uses git add -A or --no-verify.
---
 
When invoked:
1. git status (no -uall flag — large repos crash)
2. git diff for both staged and unstaged
3. Group by topic. If 2+ unrelated topics, ask which to commit first
4. Draft message: type(scope): summary — focus on why, not what
5. Stage explicitly by name. Never git add -A or git add .
6. Commit. Never --no-verify
7. Push to current branch's remote
8. Print the commit SHA and short stat

Save that, run /commit, and you'll have committed your last 15 minutes of work with a clean message in 10 seconds.

That's the entire point of Skills: do it once, reuse forever.