Skills: Reusable Prompt Templates

Skills (also called Slash Commands) are a reusable prompt template system in Claude Code. They are essentially Markdown files stored in specific directories. When invoked via /skill-name syntax, their content is loaded into Claude’s context, guiding Claude to execute tasks according to predefined workflows.

If CLAUDE.md is “always-loaded background knowledge,” then Skills are “on-demand specialized capabilities.” You don’t need to repeat complex workflow descriptions every time — define once, invoke anytime.

Invocation

In Claude Code, simply type a slash command to invoke a Skill:

> /commit
> /review-pr 123
> /deploy staging

Claude Code finds the corresponding Skill file, loads its content into context, and executes according to the instructions defined in the Skill.

Skill File Structure

Skill files are Markdown files with a specific structure, stored in the .claude/skills/ directory:

A typical Skill file looks like this:

# Commit Skill

Review all staged changes using git diff --cached.

Write a concise commit message following conventional commits format:
- type(scope): description
- Types: feat, fix, docs, style, refactor, test, chore

Rules:
- Keep the subject line under 72 characters
- Use imperative mood ("add" not "added")
- Include a body if the change is complex
- Reference related issues if applicable

After writing the message, create the commit.

User-Level vs Project-Level Skills

Skills exist at two levels:

• User-level (~/.claude/skills/): Your personal Skills, available across all projects. Ideal for personal workflow preferences.
• Project-level (.claude/skills/): Committed to the project repository, shared with the team. Ideal for project-specific workflows.

Project-level Skills can be version-controlled — team members can use the same Skills after pulling the code.

Skills vs CLAUDE.md

Understanding the difference is crucial:

CLAUDE.md is suited for project conventions, tech stack descriptions, and coding standards — information always needed. Skills are suited for specific task processes — deployment procedures, code review checklists, release workflows, and so on.

Passing Arguments to Skills

Skills can accept arguments. When you type /review-pr 123, 123 is passed as an argument to the Skill. The Skill file can reference these arguments:

# Review PR Skill

Fetch and review the pull request specified by the user.

Steps:
1. Use gh pr view with the provided PR number to get details
2. Use gh pr diff to review the changes
3. Check for:
 - Code quality issues
 - Missing tests
 - Security concerns
 - Documentation gaps
4. Provide a structured review summary

Example: Deploy Skill

A complete deployment Skill example:

# Deploy Skill

Execute a full deployment pipeline for the specified environment.

## Pre-deploy Checks
1. Run the full test suite: npm test
2. Run linting: npm run lint
3. Ensure no uncommitted changes exist
4. Verify the current branch is up to date with remote

## Build
1. Run the production build: npm run build
2. Verify build output exists and is valid

## Deploy
1. Deploy to the specified environment using the deploy script
2. Run: ./scripts/deploy.sh <environment>
3. Wait for deployment to complete

## Post-deploy Verification
1. Run smoke tests against the deployed environment
2. Check health endpoints
3. Report deployment status

If any step fails, stop immediately and report the error.
Do NOT proceed with deployment if tests or build fail.

How Skills Are Loaded

ToolSearch & Deferred Loading

Skills are not all preloaded into context. When Claude Code starts, it only loads each skill’s name and description (from the YAML frontmatter), while the full content is deferred. The complete skill definition is only fetched via the ToolSearch tool when the user types /skill-name or when the AI determines a skill is needed.

When the user types /commit, Claude Code does not read the file itself — instead, the internal Skill Tool is invoked, which handles the lookup, loading, and injection. This process is transparent to the user.

Automatic Recall Mechanism

Beyond manual /name invocation, the AI can also match skills automatically. The system compares the current task description against all skills’ descriptions using semantic matching. If the match score is high enough, the skill is loaded automatically. This is why the description field is so important — it determines whether the AI can “recall” the right skill at the right moment.

Skill Frontmatter

The YAML frontmatter in each skill file is the key to recall:

---
name: deploy
description: Execute deployment pipeline with pre-checks, build, and verification
---

name is used for exact matching (/deploy), while description is used for semantic matching (AI’s autonomous judgment). A good description should accurately convey the skill’s purpose and applicable scenarios, so the AI can automatically think to invoke it when the user describes a related task.

Loading vs Execution

Loading a skill merely injects its markdown content into the context. The AI still needs to understand and execute the instructions within. This means the quality of the skill directly impacts execution accuracy — the clearer and more specific the instructions, the more precisely the AI performs.

This also means Skills are fundamentally a context injection mechanism — they don’t change Claude’s capabilities, but guide Claude’s behavior through carefully crafted prompts.

Tips for Writing Effective Skills

• Be explicit about steps: Break tasks into clear steps, each with a specific action.
• Handle failure cases: Tell Claude what to do when something fails.
• Specify tool usage: If a Skill requires specific tools (gh, npm, etc.), state them explicitly.
• Stay focused: One Skill solves one problem — don’t mix unrelated tasks.
• Leverage project context: Skills can reference project files and configs to make instructions more specific.