Claude Code Skills: Complete Developer Guide - Build Modular AI Capabilities for Your Workflow

TL;DR: Claude Code Skills are reusable, modular SKILL.md files that let developers package instructions, templates, and automation for Claude Code. Skills are automatically invoked based on task context -- no manual prompting required. They support personal, project-scoped, and plugin distribution models with built-in security via allowed-tools restrictions. This guide covers the full specification, four ready-to-use skill examples, and best practices for teams adopting Claude Code in 2026.

Key Takeaways

• Claude Code Skills let you package reusable instructions, templates, and automation into modular SKILL.md files that Claude invokes automatically based on context.
• Skills can be personal (`~/.claude/skills/`), project-scoped (`.claude/skills/`), or distributed as plugins -- each serving different sharing and collaboration needs.
• Every Skill requires a `SKILL.md` file with YAML frontmatter (name, description) and Markdown instructions. Optional folders for templates, scripts, and data extend functionality.
• Security is built in through `allowed-tools` restrictions that limit which tools a Skill can access (e.g., read-only, specific file types, or certain bash commands).
• This guide includes ready-to-use examples: commit message helper, test generator, documentation generator, and code reviewer Skills.

Want to make Claude Code work smarter for your specific codebase and team? Claude Code Skills are the answer. Instead of repeating the same instructions or relying on ad-hoc prompts, Skills let you create structured, reusable AI capabilities that Claude automatically selects based on what you are working on -- whether that is generating conventional commits, writing unit tests, or enforcing your team's coding standards.

This guide walks you through everything from creating your first SKILL.md file to building advanced Skills for test generation, documentation, code review, and CI/CD automation. Whether you are a solo developer looking to speed up your workflow or a team lead wanting to standardize practices across your organization, you will find practical examples and best practices you can start using today.

Understanding Claude Code Skills

Claude Code Skills represent a paradigm shift in how developers interact with AI assistants, moving from ad-hoc instructions to structured, reusable capabilities. Skills enable developers to encapsulate complex workflows, coding conventions, and domain expertise into discoverable modules that Claude automatically invokes based on context.

Key Characteristics

• Model-Invoked Architecture: Claude analyzes task context and automatically selects appropriate Skills without explicit user commands
• Modular Design: Each Skill focuses on a specific capability, promoting maintainability and reusability
• Hierarchical Organization: Skills can be personal, project-scoped, or plugin-bundled for different sharing models
• Discovery Mechanism: Claude automatically loads Skills from configured directories and plugin packages
• Security Controls: Tool restrictions and access policies ensure Skills operate within defined boundaries

These characteristics make Skills ideal for automating repetitive tasks, enforcing coding standards, integrating with external tools, and capturing team knowledge in executable form.

Skill Architecture and Components

Foundational Structure

Every Skill consists of a directory containing a required SKILL.md file with YAML frontmatter and optional supporting resources:

SKILL.md Frontmatter Specification

The YAML frontmatter defines Skill metadata and behavior:

Required Fields:

• name: Lowercase with hyphens, maximum 64 characters, must be unique
• description: Maximum 1024 characters, should clearly explain what the Skill does, when Claude should use it, and what triggers invocation

Optional Fields:

• allowed-tools: Glob patterns restricting which tools the Skill can access, enhancing security and scope control

Content Guidelines

After the frontmatter, provide clear instructions in Markdown format:

Skill Types and Deployment Models

1. Personal Skills

Location: ~/.claude/skills/

Personal Skills cater to individual developer workflows and productivity patterns.

Use Cases:

• Personal coding style preferences and conventions
• Individual workflow automation and shortcuts
• Learning experiments and prototype capabilities
• Custom tool integrations for personal use

Example Directory Structure:

2. Project Skills

Location: .claude/skills/

Project Skills are version-controlled capabilities shared across development teams.

Use Cases:

• Team-wide coding conventions and standards
• Project-specific workflow automation
• Shared templates and architectural patterns
• CI/CD integration and deployment workflows
• Code review checklists and quality gates

Example Directory Structure:

3. Plugin Skills

Location: Bundled with Claude Code plugins

Plugin Skills provide advanced capabilities from the marketplace and community.

Use Cases:

• Specialized frameworks and library integrations
• Industry-specific workflow patterns
• Advanced security and compliance tools
• Domain-specific code generation

Creating Your First Skill: Commit Message Helper

Let's build a comprehensive Skill that generates conventional commit messages following team standards.

Step 1: Choose Deployment Location

For team-wide usage:

For personal usage:

Step 2: Implement the Skill Definition

The Commit Helper Skill consists of a YAML frontmatter section followed by detailed instructions. Here's how to structure it:

YAML Frontmatter:

Skill Instructions:

The Skill begins with a clear purpose statement, followed by a structured workflow that Claude follows when generating commit messages.

Core Workflow:

1. Analyze Changes - The Skill instructs Claude to examine staged modifications using git diff and status commands to identify affected components and modules.
2. Determine Commit Type - Claude categorizes the commit based on conventional commit standards:
   • feat: New features or capabilities
   • fix: Bug fixes or error corrections
   • docs: Documentation-only changes
   • style: Code formatting and whitespace changes
   • refactor: Code restructuring without behavior changes
   • test: Test additions or modifications
   • chore: Build process, dependency updates, and tooling changes
3. Identify Scope - The Skill guides Claude to identify the affected component, module, or feature area (e.g., auth, api, ui, database).
4. Analyze Breaking Changes - Claude checks for API signature modifications, configuration changes, database schema migrations, or dependency incompatibilities.
5. Generate Commit Message - The Skill provides a template structure with three parts:
   • Subject line (max 50 characters) using imperative mood
   • Body (wrapped at 72 characters) explaining motivation and context
   • Footer with breaking change notes and issue references

Example Commit Messages:

The Skill includes several concrete examples to guide Claude's output:

Feature Addition Example:

Bug Fix Example:

Breaking Change Example:

Edge Cases Handled:

• No Staged Changes: The Skill instructs Claude to inform the user when no changes are staged
• Large Changesets: For extensive modifications, Claude provides summary sections
• Multiple Concerns: The Skill suggests splitting unrelated changes into separate commits
• Merge Commits: Standard merge commit format is used

Quality Checks:

Before finalizing, Claude verifies:

• Subject line length (max 50 characters)
• Body line wrapping (max 72 characters)
• Imperative mood in subject line
• Clear documentation of breaking changes
• Correct issue reference format

Step 3: Test the Skill

Start Claude Code and trigger the Skill:

Then interact naturally:

Claude will automatically invoke the commit-helper Skill, analyze the changes, and generate an appropriate commit message.

Advanced Skill Implementations

Test Generator Skill

A sophisticated Skill that generates comprehensive unit tests for code functions.

YAML Frontmatter:

Skill Purpose:

The Test Generator automatically creates comprehensive unit tests using Jest framework with coverage for happy paths, edge cases, and error conditions.

Core Workflow:

1. Analyze Target Function - Claude reads the source file, extracts the function signature (name, parameters, return type), understands the implementation logic, identifies dependencies, and documents expected behavior.
2. Identify Test Scenarios:
   • Happy Path Tests: Valid input variations, typical use cases, expected return values
   • Edge Case Tests: Empty inputs (null, undefined, empty strings/arrays), boundary values (zero, negative numbers, maximum values), type edge cases
   • Error Handling Tests: Invalid inputs, exception scenarios, error message validation
   • Integration Tests: Database interactions, API calls, external service dependencies (if applicable)
3. Generate Test File - Claude creates a test file following the naming convention `.test.{js|ts}` with structured test suites.

Test Structure Pattern:

The Skill instructs Claude to organize tests into nested describe blocks:

• Main describe block for the function name
• Nested describe blocks for test categories (Happy Path, Edge Cases, Error Handling)
• Individual it blocks for specific test cases with descriptive names
• Proper expect assertions for each test case

Example Test Scenario:

For a calculateDiscount function, the Skill would guide Claude to generate tests covering:

• Standard percentage calculations (10%, 50%)
• Zero discount handling
• Decimal price handling
• 100% discount edge case
• Very small amount handling
• Negative price error case
• Invalid discount percentage error cases
• Non-numeric input error cases
• Type coercion scenarios
• Execute Tests - The Skill instructs Claude to run the test suite using npm test and report results with coverage metrics.

Quality Standards:

The Skill enforces these testing standards:

• Minimum 80% code coverage target
• All public API functions must have tests
• Critical business logic requires comprehensive test suites
• Descriptive test names explaining expected behavior
• Setup/teardown for shared test fixtures
• Proper mocking of external dependencies

Documentation Generator Skill

A Skill that creates comprehensive JSDoc/TSDoc documentation for code elements.

YAML Frontmatter:

Skill Purpose:

Generate detailed, standards-compliant documentation for code elements following JSDoc/TSDoc conventions.

Core Workflow:

1. Analyze Code Element - Claude identifies the element type (function, class, method, interface, type alias), extracts parameters with types, determines return value and type, identifies thrown exceptions, and understands purpose from implementation.
2. Generate Documentation - The Skill provides templates for different code element types:

Function Documentation Pattern:

• Brief description of what the function does
• More detailed description if needed explaining purpose, behavior, and implementation details
• @param tags for each parameter with descriptions
• @returns tag describing the return value
• @throws tags for error conditions
• @example block with code demonstrating usage

Class Documentation Pattern:

• Brief description of the class
• Detailed description of the class purpose, behavior, and usage patterns
• @example block showing instantiation and method usage

Method Documentation Pattern:

• Brief description of the method
• @param tags for parameters
• @returns tag for return value
• @throws tags for error conditions
• @example block demonstrating method usage
• Apply Documentation - The Skill instructs Claude to insert the documentation comment above the code element with proper indentation, verify markdown formatting in examples, and validate parameter names match actual parameters.

Example Transformation:

Before Documentation:

After Documentation:

Documentation Standards:

The Skill enforces these documentation standards:

• Use active voice in descriptions
• Be concise but comprehensive
• Include examples for complex functions
• Document all parameters and return values
• Specify error conditions and thrown exceptions
• Use proper JSDoc/TSDoc tags
• Keep line length under 80 characters

Code Review Skill

A comprehensive Skill for conducting thorough code reviews with detailed feedback categorization.

YAML Frontmatter:

Skill Purpose:

Conduct thorough code reviews focusing on correctness, security, performance, and maintainability.

Review Checklist:

The Skill guides Claude through a systematic evaluation across five dimensions:

1. Correctness
   • Logic errors or bugs
   • Off-by-one errors
   • Null/undefined/nil handling
   • Edge cases handled properly
   • Error handling completeness
   • Type safety (in typed languages)
2. Security
   • Input validation and sanitization
   • SQL injection risks
   • XSS vulnerabilities
   • Authentication/authorization checks
   • Sensitive data exposure
   • Cryptography best practices
   • Dependency vulnerabilities
3. Performance
   • Algorithm complexity (time and space)
   • Database query efficiency (N+1 queries)
   • Memory leaks
   • Unnecessary computations
   • Caching opportunities
   • Batch operations vs. loops
4. Code Quality
   • Naming conventions
   • Function/method length and complexity
   • Code duplication (DRY principle)
   • Comments and documentation
   • Test coverage adequacy
   • Consistent code style
5. Best Practices
   • Design patterns appropriate usage
   • SOLID principles adherence
   • Framework conventions compliance
   • Idiomatic language usage

Review Process:

The Skill outlines a five-step process:

1. Read the code: Understand changes, context, and purpose
2. Run automated checks: Look for obvious issues and patterns
3. Manual review: Apply checklist systematically to each section
4. Categorize findings:
   • CRITICAL: Must fix (security vulnerabilities, data corruption risks)
   • MAJOR: Should fix (performance issues, maintainability problems)
   • MINOR: Consider fixing (style inconsistencies, small optimizations)
   • SUGGESTION: Nice to have (alternative approaches, future improvements)
5. Provide feedback: For each issue, Claude provides:
   • Clear description of the issue
   • Exact location with file path and line number
   • Severity level
   • Suggested fix with code example
   • Explanation of why it matters

Review Output Format:

The Skill instructs Claude to structure review results in markdown format with sections for each severity level. Each issue includes:

• A clear title describing the problem
• Location information (file path and line number)
• Code snippet showing the problematic code
• Detailed explanation of the issue and its impact
• A code example showing the recommended fix

Example Issues by Severity:

CRITICAL Issues might include:

• SQL injection vulnerabilities with parameterized query fixes
• Unhandled promise rejections with proper error handling
• Security misconfigurations with secure alternatives

MAJOR Issues might include:

• N+1 query problems with eager loading solutions
• Memory leaks with cleanup function implementations
• Performance bottlenecks with optimization strategies

MINOR Issues might include:

• Inconsistent naming conventions
• Magic numbers without named constants
• Missing code comments

SUGGESTION Level might include:

• Opportunities for code extraction and reusability
• Documentation improvements for developer experience

Edge Cases:

The Skill handles special scenarios:

• No Issues Found: Provide positive feedback and highlight good practices
• Large Changesets: Focus on critical and major issues first
• Legacy Code: Be pragmatic about applying modern standards to old code
• Framework-Specific: Adapt review criteria to framework conventions

Best Practices for Skill Development

1. Write Clear, Contextual Descriptions

Bad Example:

Good Example:

The good description provides:

• What the Skill does (generates conventional commit messages)
• Input context (git diffs)
• Trigger phrases (create a commit, commit message help, stage and commit)

2. Keep Skills Focused and Modular

Each Skill should address a single, well-defined responsibility:

Good Architecture:

• `commit-helper`: Only handles commit message generation
• `test-generator`: Only generates unit tests
• `doc-generator`: Only generates documentation
• `code-reviewer`: Only performs code reviews

Poor Architecture:

• `code-helper`: Tries to handle commits, tests, documentation, and reviews in one Skill

3. Include Concrete Examples

Always provide examples demonstrating expected inputs and outputs. For instance, an API response formatter Skill should show:

Standard Format:

Success Response Example:

Error Response Example:

4. Use Tool Restrictions for Security

Limit tool access to improve security and prevent unintended operations:

This Skill can read and search code but cannot modify files or execute commands.

5. Version Your Skills

Document version history to track changes and improvements:

6. Test Comprehensively

Before deploying Skills, test with diverse scenarios:

1. Happy Path: Normal, expected usage
2. Edge Cases: Empty inputs, boundary conditions, unusual data
3. Error Conditions: Invalid inputs, missing dependencies, network failures
4. Large Scale: How does the Skill handle large files or datasets?
5. Concurrency: Can multiple users invoke the Skill simultaneously?

7. Reference Supporting Files

For complex Skills, organize resources systematically:

API Scaffolder Example:

Testing and Debugging Skills

Testing Methodology

Create Test Scenarios:

In Claude Code:

Verify Skill Invocation:

Claude should mention using the Skill or demonstrate behavior consistent with Skill instructions.

Test Edge Cases:

• No changes staged
• Very large diffs
• Multiple file types
• Special characters in content
• Binary files

Common Issues and Solutions

Problem: Skill Not Being Invoked

Possible Causes:

• Description doesn't match user context
• Name conflicts with other Skills
• YAML frontmatter syntax errors

Solutions:

1. Make description more specific with trigger phrases
2. Ensure unique Skill names
3. Validate YAML syntax:

Problem: Skill Giving Incorrect Results

Debugging Steps:

1. Review instructions for clarity and completeness
2. Add more detailed examples showing expected behavior
3. Make procedural steps more explicit and numbered
4. Include error handling guidance for common failures

Problem: Skill Using Wrong Tools

Solution: Add allowed-tools restrictions:

Sharing and Distributing Skills

Sharing Personal Skills

Personal Skills in ~/.claude/skills/ require manual distribution:

Export the Skill:

Document Requirements in README.md:

Include installation instructions, dependencies, configuration requirements, and usage examples. For instance:

• Installation: Copy the skill directory to ~/.claude/skills/
• Dependencies: List required tools, packages, or environment variables
• Configuration: Document any environment variables or config files needed
• Usage: Provide example prompts that trigger the Skill

Sharing Project Skills

Project Skills are automatically shared via version control:

Create the Skill:

Commit to Repository:

Document in Project README:

Include a section describing available Claude Code Skills with usage instructions and conventions enforced by each Skill.

Creating Skill Packages

For distributing multiple related Skills:

install.sh:

Publishing to GitHub

Example repository structure for community Skills:

Integration with Development Workflows

CI/CD Integration Skill

A Skill for managing continuous integration and deployment workflows:

Skill Purpose:

Generate and manage GitHub Actions workflows, GitLab CI, or Jenkins pipelines following best practices.

Supported Platforms:

• GitHub Actions
• GitLab CI/CD
• Jenkins
• CircleCI
• Travis CI

Core Workflow:

1. Identify Project Type - Determine if the project is Node.js/JavaScript, Python, Go, Java/Maven/Gradle, or Docker-based.
2. Determine Pipeline Stages - Define stages for build, test, lint, security scan, and deployment (staging, production).
3. Generate Pipeline Configuration - Create platform-specific pipeline configuration with proper job definitions, dependency management, and deployment strategies.

Example GitHub Actions Workflow:

The Skill guides Claude to create workflows with:

• Appropriate triggers (push, pull_request)
• Branch filtering
• Job dependencies
• Caching strategies for dependencies
• Parallel job execution
• Security scanning integration
• Environment-specific deployments
• Secret management

Best Practices Enforced:

• Cache dependencies for faster builds
• Run jobs in parallel when possible
• Use secrets for sensitive data
• Implement deployment approvals for production
• Include rollback procedures

Conclusion

Claude Code Skills represent a powerful paradigm for extending AI-assisted development with domain-specific knowledge, team conventions, and reusable automation. By packaging instructions, templates, and scripts into modular Skills, development teams can standardize workflows, capture institutional knowledge, and dramatically enhance productivity.

The comprehensive examples and implementation patterns provided in this guide demonstrate how to build sophisticated Skills for diverse use cases—from commit message generation to comprehensive code reviews. As AI-assisted development becomes increasingly central to software engineering workflows, Skills will play a crucial role in customizing these tools to match team practices and domain requirements.

The future of developer productivity lies in the seamless integration of AI capabilities with human expertise and organizational knowledge. Claude Code Skills provide the framework for this integration, enabling developers to focus on creative problem-solving while AI handles routine tasks according to established conventions and standards.

Resources and Further Learning

Official Documentation

• Claude Code Skills Documentation
• Claude Code Official Website
• Claude Code GitHub Repository
• Claude Code Hooks Examples

Sample Skills and Templates

• Awesome Claude Code - Community Resources
• Claude Code Templates Collection
• Claude Code Subagents Collection
• Claude Code Cookbook

Frequently Asked Questions

What are Claude Code Skills?

Claude Code Skills are reusable, modular SKILL.md files that let developers package instructions, templates, and automation for Claude Code. Each Skill consists of a directory containing a required SKILL.md file with YAML frontmatter (defining name, description, and optional tool restrictions) and optional supporting resources like templates, scripts, and reference data. Skills are automatically invoked by Claude based on task context -- no manual prompting required. They enable developers to encapsulate complex workflows, coding conventions, and domain expertise into discoverable modules that Claude selects and applies when relevant to the current task.

How to create custom Claude Code Skills?

To create a custom Claude Code Skill: (1) Choose a deployment location -- use .claude/skills/ for project-scoped team Skills or ~/.claude/skills/ for personal Skills. (2) Create a directory for your Skill (e.g., mkdir -p .claude/skills/my-skill). (3) Create a SKILL.md file with YAML frontmatter containing name (lowercase with hyphens, max 64 characters), description (max 1024 characters explaining what the Skill does and when to use it), and optional allowed-tools (glob patterns restricting tool access). (4) Write clear Markdown instructions below the frontmatter covering purpose, step-by-step instructions, concrete examples, and edge cases. (5) Optionally add supporting directories for templates, scripts, and reference data. (6) Test by launching Claude Code and using natural language that matches the Skill description.

Claude Code Skills vs Cursor Rules: what's the difference?

Claude Code Skills and Cursor Rules both provide custom instructions for AI coding assistants, but they differ in architecture and capability. Claude Code Skills use a modular, model-invoked architecture where Claude automatically selects the appropriate Skill based on task context -- each Skill is a self-contained directory with its own SKILL.md definition, templates, scripts, and data files. Skills support tool restrictions via allowed-tools for security and can be distributed as personal, project-scoped, or plugin packages. Cursor Rules are typically a single .cursorrules file at the project root containing global instructions that apply to all interactions. Skills offer more granular control, modularity (one Skill per capability), and automatic context-based invocation rather than always-on global rules.

Where are Claude Code Skills stored?

Claude Code Skills are stored in three possible locations depending on their scope: (1) Personal Skills are stored in ~/.claude/skills/ and are available only to the individual developer across all projects. (2) Project Skills are stored in .claude/skills/ within the project repository root and are shared with the entire team via version control (git). (3) Plugin Skills are bundled with Claude Code plugins from the marketplace or community packages. Each Skill directory contains a required SKILL.md file and optional subdirectories for templates, scripts, and data. Project Skills are the recommended approach for team-wide standardization since they are automatically version-controlled and shared when team members pull the repository.