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