You are in a terminal, the commit is staged, and the wording you need sits in one of 40 Markdown files somewhere in another window.
You alt-tab, search for the commit prompt, paste it, then realize it needs the staged diff too. So you run another command, copy that output, and start again. The work is small. The ritual is the problem.
Claude Code skills replace that folder with SKILL.md files that load when your request matches their description. A skill is a prompt that knows when to fire.
That shift removes prompt hunting from ordinary developer work. Your commit helper can read the staged diff. Your review helper can inspect a change. Your migration helper can apply the same safety checks every time, without asking you to remember the exact prompt first.
Skills keep prompt instructions close to the work that needs them.
This is why a skill folder stays smaller than a prompt library over time. Each skill owns one repeatable job, its trigger description, and any helper files that job needs.
This walkthrough shows the file structure and helper-script pattern behind a skill.
A request such as “write a commit message for my staged changes” carries enough intent for a skill description to match it.
A static file like prompts/commit.md waits for you to find it, open it, paste it, and add the relevant diff. A skill lives at .claude/skills/smart-commit/SKILL.md, where Claude Code can inspect its YAML frontmatter before deciding whether the request fits.
The description field is the routing layer. Write it in plain language about the job, the context it needs, and the outcome it should produce. Claude Code uses that description for semantic matching, then reads the full instructions only after activation. Claude Academy’s explanation of skills and other Claude Code features is useful background for this split.
CLAUDE.md has a different job. Put persistent repository rules there, such as project conventions that should shape every interaction. Put a focused procedure in a skill when it should run for a particular request.
For example, a team can keep formatting rules in CLAUDE.md and let smart-commit read staged changes only when someone asks for a commit message. That keeps everyday context cleaner.
If you are setting up repository instructions alongside skills, our guide to Claude Code configuration best practices can help you separate durable rules from task-specific instructions.
Two fields start the file. Claude Code’s skills documentation defines a skill as a directory built around SKILL.md.
The YAML frontmatter needs a name and a description:
The name gives you an explicit slash command. The description gives Claude Code enough context to match a natural-language request.
---name: summarize-changesdescription: Summarize working tree changes and identify likely risks when a developer asks what changed or whether a diff is safe.---
Skills use progressive disclosure in three layers:
Use the ! prefix with a backticked shell command inside the skill body to run a command before Claude answers. The output of git diff HEAD, for example, gives the skill the current working-tree diff without a manual paste.
That makes a meaningful difference for Git work. The prompt stays stable while the context changes on every run.
smart-commit is for developers who want a commit message based on what is actually staged, rather than a generic request typed from memory. Instead of reusing "Write a conventional commit message for these changes," it injects the current staged diff with git diff --cached. That gives the skill the real modifications to assess at the moment you commit.
A static prompt library leaves several manual steps in the workflow: remember the prompt, switch context, collect or pipe the diff, paste it, and then check whether the result follows the team’s commit convention. smart-commit removes the repeated diff-pasting step by evaluating the staged Git state directly.
The practical workflow is simple: stage only the files that belong in the commit, then run the skill. Because it sees git diff --cached, its suggested type, scope, and imperative summary are grounded in that selected set of changes, not in unstaged experiments or unrelated work still in the working tree.
That boundary is also important. If a necessary file has not been staged, the skill cannot account for it. Review the staged diff before accepting the message, especially when a change spans more than one area. The skill helps enforce a concise Conventional Commit summary, but it is not a replacement for checking that the commit itself is complete, safe, and logically focused.
review-pr suits developers who want a repeatable audit before asking teammates to review a change. Its instructions turn a broad review request into a consistent report.
Choose it when security and quality checks need the same structure on each review. Anthropic’s skills architecture overview describes the instruction-and-asset approach that makes focused procedures like this possible.
draft-pr fits a branch that is ready for a reviewer but still needs a clear explanation of what changed. It can use Git history and GitHub CLI context rather than relying on a hand-built summary.
Choose it when the branch history should shape the pull request description. A pasted template cannot see the commits or changed files unless you supply them first.
safe-migration is for teams changing a database schema while application code may still be running. It puts database safety rules in one repeatable review procedure.
Choose it for schema changes that need the same review gates each time. The skill keeps concurrent indexes, table rewrites, column drops, and application compatibility in the same procedure.
generate-tests is for a function or feature that needs tests shaped around its contract and its project's test setup. It turns a loose test request into a stable set of checks.
Choose it when mock boundaries and edge cases should be consistent across test requests. A static request such as “write tests with mocks” leaves those details open every time.
summarize-changes is the one to run before a handoff, a commit, or a quick sanity check. It reads the working tree directly, then reports the change and likely risk areas.
Choose it when you need a current repository summary before deciding what to do next. The file below is a complete starting point based on the Claude Code skills documentation.
<!-- .claude/skills/summarize-changes/SKILL.md -->---name: summarize-changesdescription: Summarize current working tree changes and identify likely risks when a developer asks what changed, requests a diff summary, or asks whether anything may be broken.---
Review the current repository changes before answering.
Current diff:!`git diff HEAD`
Write the response in these sections:
## SummaryState the user-visible behavior and the files involved.
## RisksList concrete risks visible in the diff, including missing error handling, incomplete callers, or behavior that needs checking.
## ChecksList focused tests or commands the developer should run next.
If the diff is empty, say that there are no working tree changes relative to HEAD.
Ask “what did I change?” to test autonomous matching. Type /summarize-changes when you want to invoke the same skill directly.
The practical winner is Claude Code skills for recurring repository work, because they can match a request and pull in current Git state.
Aspect Static Prompts Claude Code Skills Start Find and paste a file Match a request or use a slash command Startup context Full pasted prompt Roughly 50–100 token catalog metadata Repository state Manual copy-paste Shell output can load before response Instructions Fixed pasted text SKILL.md loads on activation Commit work Commit prompt smart-commit reads staged diffs Code review Review prompt review-pr ranks Critical, Warning, Suggestion Pull requests PR template prompt draft-pr uses gh and Git history Migrations SQL checklist prompt safe-migration checks non-blocking rules Tests Test-writing prompt generate-tests checks isolation and boundaries Diff summary Repository-summary prompt summarize-changes reads git diff HEAD
A static prompt can still hold a one-off idea. For procedures you repeat, skills hold the trigger, instructions, and live context in the same directory. Anthropic’s overview of skills also describes persistent Claude Projects workspaces with a 200K context window, where keeping unrelated instructions out of the active request matters.
Put personal habits in your home directory and shared rules in the repository.
mkdir -p ~/.claude/skills/smart-commit
Save its instructions as ~/.claude/skills/smart-commit/SKILL.md. This path keeps personal commit conventions available outside a single repository.
mkdir -p .claude/skills/review-pr
Save the file as .claude/skills/review-pr/SKILL.md and commit it with the repository. That makes the review procedure visible alongside the code it governs.
mkdir -p .agents/skills/safe-migration
The Agent Skills specification uses .agents/skills/<skill-name>/SKILL.md as the standard cross-agent discovery path.
Keep global skills for personal preferences and repository skills for team rules. After creating one, run claude and type its slash command to verify explicit invocation, then try a request that matches its description.
For a broader Claude Code project setup, see how to spend your credits where they matter.
CLAUDE.md holds persistent instructions for a repository or workspace: conventions, project rules, and preferences that should apply throughout a session. A skill is a focused procedure in its own directory, with a required SKILL.md file, YAML metadata, instructions, and optionally helper scripts. Rather than placing every workflow in the always-present project guidance, use a skill for work that only matters in a particular situation, such as preparing a staged commit, reviewing a pull request, or handling a migration safely.
This separation keeps routine workspace guidance cleaner. It also replaces the context switching and repeated copy-pasting common with static prompt libraries. Claude Code reads a skill’s short frontmatter description at startup, typically ~50–100 tokens, and loads the fuller instruction body only when a request matches. Keep that body under <5000 tokens so the procedure remains focused. Global preferences can live in ~/.claude/skills/, while shared project workflows belong in .claude/skills/.
Yes. Run claude and type /skill-name to invoke a skill explicitly. This is the quickest way to test a new skill file and is useful when your request is brief or could be interpreted several ways. Test both paths: invoke the slash command, then ask a natural-language question that matches the skill description. If the skill uses dynamic context injection, it can also feed current Git state into Claude without requiring you to copy command output into the chat.
Similar descriptions make routing less clear because Claude Code uses those descriptions to decide which procedure fits a request. Give each skill a distinct job and name the expected situation in its metadata. For example, separate staged commit wording, pull request review, and migration safety instead of describing all three as general Git help. If two skills genuinely overlap, invoke the intended one with /skill-name while you refine their descriptions.
Skills follow the Agent Skills open standard. The standard defines a portable format built around a SKILL.md file, metadata, instructions, and optional supporting files, so the workflow structure can move across agent frameworks that support the standard. Compatibility still depends on the receiving tool's implementation, particularly for helper scripts or tool-specific context commands.
Start with one repeated task, such as commit messages or diff summaries, and put it in ~/.claude/skills/ as a dedicated SKILL.md file.
Test it with both a matching natural-language request and its slash command. Once that works, move the team-owned procedures into .claude/skills/ and commit them with the repository.
The 6 Claude Code Skills That Replaced My Entire Prompt Library was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.