How to use Claude Code Skills in a project

Claude Code Skills are easiest to use when you treat them like small pieces of project tooling: keep them close to the code they understand, give them one clear job, and make the result verifiable.

Step 1: choose the scope

Create a project Skill when the workflow depends on local conventions, scripts, or architecture:

.claude/skills/review.md

Create a global Skill when you want the same workflow in every repository:

~/.claude/skills/branch-readiness.md

Do not start global if the instructions mention project-specific paths. Moving a local workflow to the global directory too early is a common source of wrong assumptions.

Step 2: add valid frontmatter

The description should explain the trigger and outcome, not just repeat the filename.

---
description: Review the current diff for correctness, security, regressions, and missing tests.
---

Then write the workflow in normal Markdown. Include what Claude should read, what it may change, what it must never do, and how it should report the result.

Step 3: invoke the Skill

Open Claude Code from the relevant project and type the slash command:

/review

Give the Skill a narrow request when needed, such as /review the current checkout flow. The Skill should preserve its own checklist while using the request to focus the investigation.

For a one-off task, use a normal prompt instead. A Skill is valuable because it preserves the workflow across sessions, not because every request needs a special command.

Step 4: test it read-only first

The first version should inspect state and return a report without editing or pushing. Run it on a small, known change and check whether it:

• finds the right files;
• follows the repository's conventions;
• distinguishes evidence from assumptions;
• identifies missing tests or edge cases;
• avoids secrets and unrelated files.

Once the read-only behavior is reliable, you can add edits to a separate Skill or a clearly approved step. Keep deploy, database, and push actions behind explicit confirmation.

Troubleshooting discovery

If the Skill does not appear, check these in order:

1. You are in the repository that contains .claude/skills/.
2. The file ends in .md and is not accidentally nested one directory deeper.
3. The frontmatter starts and ends with ---.
4. The description is present and describes a real trigger.
5. The filename is a simple command name such as review.md.
6. A fresh session can see the file.

If the command appears but behaves badly, shorten the instructions and add a first inspection step. Most failures come from an ambiguous scope or a Skill that tries to handle several unrelated jobs.

For reusable workflows, compare your file with the Claude Code Skills examples. If you want a ready-made starting point, use the Claude Code Skills Starter Kit.