Skills — Auto-Invoked Capabilities
What Are Skills
Skills are markdown instruction files that Claude Code loads and follows automatically when they are relevant to your current task. Unlike slash commands where you explicitly type a command to trigger behavior, skills are auto-invoked. Claude reads their descriptions, matches them against what you are asking it to do, and activates the appropriate skill without you needing to do anything.
Think of skills as specialized experts that Claude consults depending on the situation. If you have a code-review skill and you ask Claude to review a pull request, it automatically picks up the skill's instructions -- including your custom checklist, quality standards, and output format -- without you ever typing a command.
Skills live in the .claude/skills/ directory of your project and follow a simple structure: YAML frontmatter at the top for metadata, and a markdown body with the actual instructions.
Anatomy of a Skill
Every skill file has two parts: frontmatter that tells Claude when to use the skill, and a body that tells Claude how to use it.
<!-- File: .claude/skills/code-review.md -->
---
name: Code Review
description: Performs thorough code reviews checking for bugs, security issues, performance problems, and style violations. Use this when reviewing pull requests, diffs, or specific files for quality.
---
## Code Review Process
When reviewing code, follow these steps:
### 1. Correctness Check
- Verify logic handles all edge cases
- Check for off-by-one errors, null references, and type mismatches
- Ensure error handling covers failure modes
- Validate that async operations handle rejections
### 2. Security Scan
- Look for SQL injection, XSS, and CSRF vulnerabilities
- Check that user input is validated and sanitized
- Verify authentication and authorization checks are present
- Ensure secrets are not hardcoded
### 3. Performance Review
- Identify N+1 queries and unnecessary database calls
- Check for memory leaks in event listeners and subscriptions
- Look for blocking operations in async code paths
- Verify pagination is used for large data sets
### 4. Output Format
Provide findings in this format:
- **Critical**: Issues that must be fixed before merge
- **Warning**: Issues that should be addressed but are not blocking
- **Suggestion**: Improvements that would be nice to have
End with a summary verdict: APPROVE, REQUEST CHANGES, or NEEDS DISCUSSION.
The description field is the most important piece of the frontmatter. Claude uses it to decide whether to activate the skill. Write descriptions that clearly state what the skill does and when it should be used. Vague descriptions lead to the skill being either triggered too often or never triggered at all.
How Auto-Invocation Works
When you send a prompt to Claude Code, it evaluates your request against the descriptions of all available skills. If your request matches a skill's description closely enough, Claude loads that skill's instructions and incorporates them into its response.
For example, if you have the code-review skill above and you type:
claude
> Review the changes in the last commit for any issues
Claude recognizes this as a code review task, loads the skill, and follows the structured checklist and output format you defined. You did not type /code-review or reference the skill in any way -- it just happened.
This matching is semantic, not keyword-based. Claude understands intent, so "check this PR for bugs" and "audit the latest changes" both trigger the same code-review skill.
Creating Your First Skill
Start with a skill you would use frequently. A documentation generator is a good choice:
<!-- File: .claude/skills/generate-docs.md -->
---
name: Documentation Generator
description: Generates documentation for code including JSDoc comments, README sections, API references, and usage examples. Activate when asked to document functions, modules, or APIs.
---
## Documentation Standards
When generating documentation:
### For Functions and Methods
- Add JSDoc/docstring with description, parameters, return type, and example
- Include edge cases and thrown exceptions in the documentation
- Add @since tag with current date
### For Modules
- Start with a one-paragraph summary of the module's purpose
- List all exports with one-line descriptions
- Include a usage example showing the most common import pattern
### For API Endpoints
- Document HTTP method, path, query parameters, request body, and response
- Include curl example for each endpoint
- Document error responses with status codes and messages
- Add authentication requirements
### Style Rules
- Use present tense ("Returns the user" not "Will return the user")
- Keep descriptions under 2 sentences when possible
- Code examples must be runnable without modification
Frontmatter Fields
Skills support several frontmatter fields that control their behavior:
---
name: My Skill Name # Display name
description: What this skill does and when to use it # Critical for auto-invocation
effort: medium # low, medium, or high — indicates computational cost
shell: bash # Default shell for script execution (bash or python)
---
The effort field helps Claude decide how to allocate resources. A low effort skill is expected to produce quick results, while a high effort skill signals that Claude should take its time and be thorough.
Using Scripts in Skills
Skills can reference external scripts for tasks that go beyond what markdown instructions can express. Place scripts in a .claude/skills/scripts/ directory and reference them from your skill:
<!-- File: .claude/skills/analyze-bundle.md -->
---
name: Bundle Analyzer
description: Analyzes JavaScript bundle size, identifies large dependencies, and suggests optimizations. Use when asked about bundle size, performance optimization, or dependency analysis.
---
## Analysis Process
1. Run the bundle analysis script:
node .claude/skills/scripts/analyze-bundle.js
2. Parse the output and identify:
- Total bundle size and per-chunk breakdown
- Dependencies over 100KB
- Duplicate packages included in multiple chunks
- Tree-shaking opportunities
3. Provide actionable recommendations sorted by impact.
The corresponding script can use Node.js built-in modules to run your build process, read the resulting stats file, parse asset information, and output a sorted analysis. The key point is that markdown instructions define the reasoning framework while scripts handle data collection and computation.
This combination makes skills extremely powerful. You get the flexibility of natural language instructions for high-level reasoning plus the precision of executable code for data processing.
Using Templates in Skills
Skills can include output templates that Claude fills in. This ensures consistent formatting across invocations:
<!-- File: .claude/skills/security-audit.md -->
---
name: Security Audit
description: Performs a security audit of the project, checking dependencies, configurations, and code patterns for vulnerabilities.
---
## Audit Procedure
Run the following checks and fill in the template below.
### Checks
1. Run `npm audit` and capture the output
2. Scan for hardcoded secrets using pattern matching
3. Review authentication and authorization middleware
4. Check CORS and CSP headers configuration
5. Verify environment variable handling
### Report Template
# Security Audit Report — [Date]
## Summary
- **Risk Level**: [Critical / High / Medium / Low]
- **Issues Found**: [count]
- **Dependencies Scanned**: [count]
## Dependency Vulnerabilities
[List from npm audit with severity and remediation]
## Code Findings
[List of issues found in source code]
## Configuration Issues
[List of misconfigurations]
## Recommendations
[Prioritized list of actions to take]
Skills vs Slash Commands
Understanding when to use each:
Slash commands are manually triggered. You type /command-name and the instructions execute. They are best for explicit, on-demand workflows like deploying, generating release notes, or running a specific sequence of steps.
Skills are automatically triggered when Claude detects relevance. They are best for ongoing behavioral rules like how to review code, how to write documentation, how to structure tests, or how to handle specific types of tasks.
If you find yourself typing the same slash command at the start of every session, it should probably be a skill instead. If you only need a workflow occasionally and want explicit control over when it runs, keep it as a slash command.
Best Practices
Write descriptions as if you are training a new team member to recognize when this skill applies. Be specific about the trigger conditions. Instead of "helps with testing," write "generates unit tests with full coverage for TypeScript functions, including edge cases, error paths, and mock setup. Activate when asked to write tests, add test coverage, or create test files."
Keep each skill focused on one capability. A skill that tries to handle code review, documentation, testing, and deployment will match too broadly and produce inconsistent results. Create separate skills for each concern.
Test your skills by starting a fresh session and giving Claude a task that should trigger the skill. Verify that the output follows your defined format and checklist. If the skill is not triggering, rewrite the description to better match the kinds of prompts you use.
Try this exercise: create three skills for your project -- one for code review, one for documentation, and one for test generation. Write clear descriptions for each. Then start a fresh Claude Code session and, without mentioning any skill by name, ask Claude to review a file, document a module, and write tests for a function. Check whether the right skill activated each time and refine the descriptions until triggering is reliable.
Version control your skills alongside your code. When the whole team shares the same .claude/skills/ directory, everyone gets consistent AI behavior regardless of who is working on the codebase. This is one of the most effective ways to encode team standards into your AI-assisted development workflow.