What are Claude Code Skills?

Skills are reusable, shareable prompt templates that codify best practices and workflows for Claude Code. They allow you to package common tasks into a single command that can be invoked consistently across your team. Think of skills as custom slash commands tailored to your project's needs.

Creating Your First Skill

Step 1: Create the Skills Directory

Skills are stored in your project's .claude/skills/ directory:

mkdir -p .claude/skills

Step 2: Write the Skill File

Create a markdown file with your skill definition. The filename becomes the skill command name:

<!-- .claude/skills/code-review.md -->
Code Review Skill
Perform a thorough code review of the current changes.
Instructions
Run git diff to see the current changes
Analyze each changed file for:
   - Bug risks and logic errors
   - Security vulnerabilities (OWASP top 10)
   - Performance issues
   - Code style and best practice violations
   - Missing error handling
Rate the overall code quality (1-10)
Provide specific, actionable feedback for each issue
Suggest concrete fixes with code examples

Output Format
Summary of changes
Issues found (categorized by severity: Critical/Warning/Info)
Specific line-by-line feedback
Overall quality score and recommendations

Step 3: Use the Skill

In your Claude Code session, invoke the skill:

/code-review

Claude will follow the instructions in your skill file to perform the code review.

Skill File Structure

A skill file is a markdown document with these sections:

Title and Description

The first heading becomes the skill name, and the first paragraph is the description shown in the skill list.

Instructions

The body of the markdown file contains the instructions Claude will follow. You can include:

• Step-by-step procedures
• Checklists and requirements
• Output format specifications
• Constraints and preferences
• Example code and templates

Variables

Skills can reference files and context using special patterns:

• $ARGUMENTS — Any arguments passed after the skill name
• The skill automatically has access to the current project context

Advanced Skill Patterns

Multi-Step Workflow

<!-- .claude/skills/deploy.md -->
Deploy to Production
Deploy the current branch to production with safety checks.
Steps
Run the full test suite: npm test
If tests pass, build the project: npm run build
Check for console.log statements: grep -r "console.log" src/
Verify environment variables are set
Create a git tag for the release
Deploy using the deployment script
Verify the deployment is healthy
Send deployment notification

Safety Rules
Never deploy if tests are failing
Always create a backup tag before deploying
Require manual confirmation before the actual deploy

Documentation Generator

<!-- .claude/skills/document.md -->
Generate Documentation
Generate comprehensive documentation for the specified module.
Instructions
For the file or module specified in $ARGUMENTS:
Read the source code
Identify all exported functions, classes, and types
For each export:
   - Write a clear description
   - Document all parameters with types
   - Document return values
   - Provide usage examples
   - Note any side effects or edge cases
Generate a README-style module overview
Include a quick start example

Style Guide
Use JSDoc-compatible format
Include practical examples for every function
Explain "why" not just "what"
Link to related modules where relevant

Database Migration Helper

<!-- .claude/skills/migrate.md -->
Create Database Migration
Generate a safe, reversible database migration.
Instructions
Understand the schema change requested in $ARGUMENTS
Create a migration file in migrations/ with:
   - Up migration (apply the change)
   - Down migration (revert the change)
   - Data migration if schema changes affect existing data
Follow these safety rules:
   - Always include a down migration
   - Never drop columns without a deprecation period
   - Use transactions where possible
   - Add appropriate indexes
Generate a test migration that verifies both directions

Team Sharing

Sharing Skills Within a Team

Skills stored in .claude/skills/ can be committed to version control:

git add .claude/skills/
git commit -m "Add team Claude Code skills"

This ensures every team member has access to the same standardized workflows.

Skill Organization

For larger projects, organize skills into categories:

.claude/skills/
  review/
    code-review.md
    security-review.md
    pr-review.md
  deploy/
    deploy-staging.md
    deploy-production.md
  docs/
    generate-docs.md
    update-readme.md

Project vs. Global Skills

• Project skills (.claude/skills/): Specific to the current project, committed to git
• Global skills (~/.claude/skills/): Personal skills available across all projects

Best Practices

• Start specific — Write skills for your most repetitive tasks first
• Be explicit — The more detailed your instructions, the more consistent the output
• Include examples — Show Claude exactly what good output looks like
• Version control skills — Treat skills like code and review changes
• Iterate — Refine skills based on Claude's actual performance
• Use constraints — Tell Claude what NOT to do as well as what to do
• Test skills — Try skills on different scenarios to ensure they generalize well
• Document prerequisites — Note any setup requirements in the skill file

Example Skills Library

Here are popular skill patterns teams have found useful:

• PR Review — Automated pull request review with checklist
• Security Audit — OWASP-focused security review of code changes
• Performance Profiling — Identify and suggest fixes for performance issues
• Test Generator — Generate comprehensive test suites for new code
• Documentation Writer — Auto-generate API docs and README sections
• Refactor Assistant — Safe, incremental refactoring with test verification
• Release Notes — Generate changelog entries from git history