Claude Code Skills Explained: Build Your Custom Command Library

Why You Need Skills

When developing with Claude Code, you’ll inevitably run into these scenarios:

Every time you do a code review, you type a long prompt telling Claude what to check and how to check it. Every time you write a blog post, you describe the format, style, and directory structure all over again. Every time you write tests, you explain your project’s testing conventions from scratch.

You’ve said the same thing ten times. You’re not tired of it, and neither is Claude — but your time is slipping away.

What’s even worse is team collaboration — you’ve figured out an efficient way to use Claude, but everyone else on the team is doing their own thing. Knowledge doesn’t accumulate, and efficiency can’t be aligned.

That’s when you need Skills.

What Are Skills

Skills are Claude Code’s custom slash command feature. In simple terms, you write your frequently used prompts into a Markdown file, then invoke them with /command-name.

For example, if you create a Skill called review, all you need to type is:

/review

Claude will follow your predefined rules to do a code review — no need to describe everything again, no risk of missing steps.

Skills are essentially: reusable, shareable, version-controlled prompt templates.

A bit of history: Claude Code originally had two separate concepts — commands and skills, stored in different directories. They’ve since been merged under the unified Skills system, though the legacy .claude/commands/ directory is still compatible.

Directory Structure and Scope

Skills have two scopes: project-level and personal-level.

Project-Level Skills

Stored in your project’s .claude/skills/ directory, version-controlled with your codebase, shared across the entire team:

project-root/
  .claude/
    skills/
      review/
        SKILL.md        # Skill definition file
      gen-test/
        SKILL.md
        template.ts     # Supporting file

Each Skill is a folder, and the folder name becomes the command name. The core file is SKILL.md; everything else is optional supporting material.

Personal-Level Skills

Stored in ~/.claude/skills/, accessible only to you, never committed to the repository:

~/.claude/
  skills/
    my-style/
      SKILL.md
    daily-report/
      SKILL.md

Perfect for personal preferences like your coding style or daily report templates.

Priority

When a project-level and personal-level Skill share the same name, project-level takes priority. This makes sense — project standards should override personal preferences.

SKILL.md File Format

Each SKILL.md consists of two parts: YAML frontmatter and Markdown body.

Frontmatter Fields

---
name: review
description: Perform code review following team standards, checking security, performance, and maintainability
allowed-tools:
  - Read
  - Glob
  - Grep
disable-model-invocation: false
---

Here’s what each field means:

Field	Required	Description
`name`	Yes	Command name, triggered by typing `/name`
`description`	Yes	Describes what the Skill does; also used by Claude to decide whether to auto-trigger
`allowed-tools`	No	Tools automatically authorized when the Skill is active, skipping per-use confirmation
`disable-model-invocation`	No	Set to `true` to prevent Claude from auto-triggering; only manual `/name` invocation works

name: Becomes the /slash-command. For example, name: review means you invoke it with /review.

description: This field is crucial. Claude reads all Skill descriptions to determine whether the current task matches a Skill. Write it well, and Claude can automatically invoke the right Skill at the right time.

allowed-tools: Tools that are auto-approved when the Skill runs. For a read-only review Skill, authorizing Read, Glob, and Grep means Claude won’t pop up confirmation dialogs for every action.

disable-model-invocation: Defaults to false, meaning Claude can auto-trigger based on context. Set to true to ensure only manual /command-name input activates it. Recommended for sensitive operations.

Markdown Body

Below the frontmatter are the instructions for Claude, written in Markdown:

## Review Steps

1. Use Grep to find all files involved in the current changes
2. Check each file for:
   - Security vulnerabilities (SQL injection, XSS, etc.)
   - Performance issues (N+1 queries, unnecessary re-renders, etc.)
   - Clear naming and maintainable logic
3. Output a review report with issues sorted by severity

## Output Format

List issues in a table with: filename, line number, severity, description, and fix suggestion

Combine the frontmatter and body, and you have a complete SKILL.md.

Supporting Files

The folder containing SKILL.md can include additional supporting files to enhance the Skill’s capabilities:

File Type	Purpose	Example
Templates	Let Claude fill in content following a template	`template.md`, `component.tsx`
Example output	Show Claude the expected output format	`example-output.md`
Scripts	Let Claude execute specific scripts	`run-check.sh`
Reference docs	Provide domain knowledge or style guidelines	`style-guide.md`

Reference these files from your SKILL.md body:

## Template

Use the `template.tsx` in this directory as the component template.

## Example

See `example-output.md` for the expected output format.

Claude will then read these files and follow the templates and examples when executing the task.

Practical Use Cases

Case 1: Code Review Skill

A unified code review standard for the whole team, everyone uses the same command:

.claude/skills/review/SKILL.md

---
name: review
description: Review code changes following team standards, checking security, performance, and code quality
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Task

Review all changes on the current branch compared to main.

## Checklist

1. **Security**: Injection attacks, sensitive data leaks, permission checks
2. **Performance**: N+1 queries, large data loads, unnecessary re-renders
3. **Code quality**: Naming conventions, function length, duplicate code
4. **Test coverage**: Whether new logic has corresponding tests

## Output

List issues by severity, each including file, line number, and fix suggestion.

Anyone on the team types /review and gets a consistent, standards-based code review.

Case 2: Blog Writing Skill

Codify your blog writing conventions into a Skill:

.claude/skills/blog/SKILL.md

---
name: blog
description: Write a Chinese blog post following project conventions
allowed-tools:
  - Read
  - Glob
  - Write
disable-model-invocation: true
---

## Task

Write a Chinese blog post based on the topic provided by the user.

## Conventions

- File location: src/data/blog/zh/<slug>.md
- Required frontmatter: title, description, date, tags, lang: zh
- Style: Conversational, second person, use bold for key points
- Structure: Why you need it → What it is → How to use it → Real scenarios → Tips → Conclusion

From now on, /blog kicks things off with format and style automatically aligned.

Case 3: Test Generation Skill

Your project has specific testing conventions — codify them in a Skill:

.claude/skills/gen-test/SKILL.md

---
name: gen-test
description: Generate unit tests for a specified file following project testing conventions
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
---

## Task

Generate unit tests for the source file specified by the user.

## Conventions

- Test framework: Jest
- File naming: <original-filename>.test.ts
- At least 3 test cases per exported function: normal input, edge case, error input
- Use nested describe/it structure
- Mock external dependencies, no real network requests

Type /gen-test src/utils/format.ts, and Claude auto-generates tests following your conventions.

Practical Tips

Tip 1: Use allowed-tools to Skip Confirmations

If a Skill only reads and analyzes, add Read, Glob, and Grep to allowed-tools. This way Claude won’t keep popping up confirmation dialogs, making the experience much smoother.

But be careful: be cautious with write tools (Write, Edit), especially for Skills that modify code. Keeping manual confirmation is safer.

Tip 2: Use disable-model-invocation to Prevent Misfires

Some Skills have broadly written description fields, and Claude might auto-trigger them at the wrong time. Set disable-model-invocation to true to ensure only manual /command-name input activates them.

Rule of thumb: Read-only Skills can be auto-triggered by Claude; write or sensitive operation Skills should be manually triggered.

Tip 3: Leverage Anthropic’s Official Skills Repository

Anthropic maintains an official Skills repository on GitHub (anthropics/skills) with ready-to-use Skills, including skill-creator — a Skill specifically designed to help you create new Skills.

Copy them directly into your project, or use them as references for creating your own.

Tip 4: Mind the Context Budget

Claude loads all Skill names and descriptions into its context. If you have too many Skills, descriptions get truncated. The default budget is 1% of the context window, adjustable via environment variable:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000

So keep your description concise and effective — say what the Skill does and when to use it in as few words as possible.

Final Thoughts

Skills solve a simple problem: turning your experience into reusable commands.

When developing with Claude Code, everyone accumulates their own “best practices” — how to review code, how to write tests, how to refactor. But if that experience only lives in your head, communicated through manually typed prompts every time, it doesn’t scale.

Write it as a Skill, share it with the team, version-control it, invoke it with a single /command. Personal experience becomes team capability — codify once, reuse forever.

One folder, one SKILL.md, unlocking your entire team’s AI efficiency.