Skills Guide

How to use and create Claude Code Skills

Skills Guide

Skills are knowledge-layer components in Claude Code that provide domain-specific expertise and guidance to Claude. Unlike commands that require manual invocation, Skills are automatically activated based on task context.

What are Skills?

Skills are professional knowledge modules stored in SKILL.md files:

  • Auto-activation: Claude automatically uses relevant Skills based on task context
  • Domain knowledge: Provides best practices and guidance for specific domains
  • Extensible: Create custom Skills to meet specific needs
  • Context-aware: Only invoked in relevant scenarios

Skills vs Commands vs Agents

Component Trigger Purpose
Commands User manually invokes (/command) Execute specific tasks
Skills Auto-activated Provide domain knowledge
Agents Delegated calls Handle complex workflows

Using Built-in Skills

Claude Code plugins typically include multiple built-in Skills. When your task matches a Skill's description, Claude automatically uses it.

Example: Code Review

When you say "help me review this code for security issues", if a plugin with a security review Skill is installed, Claude will automatically apply that Skill's knowledge for the review.

Viewing Available Skills

Skills are typically installed with plugins:

# Install plugin (plugins may contain multiple Skills)
/plugin install plugin-name@marketplace

Creating Custom Skills

Basic Structure

The simplest Skill only needs a SKILL.md file:

my-skill/
└── SKILL.md

SKILL.md Format

---
name: Code Style Guide
description: Use this skill when the user asks about "code style", "naming conventions", "code formatting", or discusses coding standards
version: 1.0.0
---

# Code Style Guide

## Naming Conventions

- Variables use camelCase
- Constants use UPPER_SNAKE_CASE
- Classes use PascalCase
- Private members use underscore prefix

## Formatting Rules

- Use 2 spaces for indentation
- Line width should not exceed 80 characters
- Use trailing commas

## Best Practices

- Functions should have single responsibility
- Avoid deep nesting
- Use meaningful variable names

Frontmatter Fields

Field Required Description
name Yes Skill name
description Yes Trigger condition description (critical!)
version No Version number

Writing Effective Descriptions

The description field determines when a Skill is activated and should include specific trigger phrases:

Good example:

description: Use this skill when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events

Bad example:

description: Guide about hooks  # Too vague

Complete Skill Structure

For complex Skills, you can include more resources:

my-skill/
├── SKILL.md           # Main knowledge document
├── references/        # Detailed references
│   ├── patterns.md    # Design patterns
│   └── advanced.md    # Advanced techniques
├── examples/          # Example code
│   ├── basic.ts       # Basic example
│   └── advanced.ts    # Advanced example
└── scripts/           # Helper scripts
    └── validate.sh    # Validation script

Referencing Resources

Reference other resources in SKILL.md:

---
name: API Development Guide
description: Use when the user asks about "API design", "REST interfaces", "API best practices"
version: 1.0.0
---

# API Development Guide

See @references/patterns.md for detailed API design patterns

## Quick Example

See @examples/basic.ts for basic usage

Using Skills in Plugins

Directory Structure

Skills go in the plugin's skills/ directory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # Command layer
├── agents/            # Agent layer
└── skills/            # Knowledge layer
    ├── code-style/
    │   └── SKILL.md
    └── api-docs/
        ├── SKILL.md
        └── references/

Referencing Skills in Commands

Commands can explicitly reference Skill knowledge:

---
description: Generate standards-compliant API documentation
argument-hint: [api-file]
---

Generate API documentation for @$1.

Use the api-docs skill to ensure documentation includes:
- Complete endpoint descriptions
- Parameter specifications
- Response formats
- Error codes
- Usage examples

Practical Examples

Example 1: Project Standards Skill

---
name: Project Standards
description: Use when the user asks about "project structure", "file organization", "directory conventions"
version: 1.0.0
---

# Project Standards

## Directory Structure

\`\`\`
src/
├── components/    # React components
├── hooks/         # Custom Hooks
├── services/      # API services
├── utils/         # Utility functions
└── types/         # TypeScript types
\`\`\`

## File Naming

- Components: PascalCase (e.g., `UserProfile.tsx`)
- Utilities: camelCase (e.g., `formatDate.ts`)
- Constants: UPPER_SNAKE_CASE (e.g., `API_ENDPOINTS.ts`)

## Import Order

1. React related
2. Third-party libraries
3. Internal modules
4. Type definitions
5. Style files

Example 2: Git Workflow Skill

---
name: Git Workflow
description: Use when the user asks about "branch strategy", "commit conventions", "Git process"
version: 1.0.0
---

# Git Workflow Standards

## Branch Naming

- Features: `feature/description`
- Fixes: `fix/description`
- Hotfixes: `hotfix/description`

## Commit Message Format

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

### Type Values

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code formatting
- `refactor`: Refactoring
- `test`: Testing
- `chore`: Build/tooling

Example 3: Security Review Skill

---
name: Security Review
description: Use when the user asks about "security check", "vulnerability scan", "security best practices", or reviewing code security
version: 1.0.0
---

# Security Review Guide

## Common Vulnerability Checks

### SQL Injection
- Check for parameterized queries
- Avoid string concatenation in SQL

### XSS Attacks
- Check if user input is escaped
- Use CSP headers

### Sensitive Data
- Ensure passwords are not stored in plaintext
- Don't hardcode API keys
- Check logs for sensitive data leaks

## Review Checklist

- [ ] Input validation
- [ ] Output encoding
- [ ] Authentication mechanism
- [ ] Authorization checks
- [ ] Encryption usage
- [ ] Error handling

Best Practices

1. Clear Trigger Descriptions

Use specific trigger phrases, not vague descriptions:

# Good
description: Use when the user asks about "create component", "React component template", "component best practices"

# Bad
description: React component related

2. Structured Knowledge

Organize knowledge into clear hierarchies:

  • Use heading levels
  • Provide code examples
  • Include checklists

3. Keep Updated

  • Regularly update Skill content
  • Version numbers reflect changes
  • Document important updates

4. Modular Design

  • Each Skill focuses on one domain
  • Use references directory for detailed materials
  • Provide practical examples

Debugging Skills

If a Skill isn't activating as expected:

  1. Check description: Ensure trigger phrases match user input
  2. Verify format: Ensure YAML frontmatter is correctly formatted
  3. Test triggers: Try using exact phrases from the description

Next Steps

On this page