Claude Code Skills: Extending Capabilities
Claude Code becomes exponentially more powerful when you teach it new skills. Think of skills as specialized workflows packaged into reusable commands. Instead of explaining the same complex task repeatedly, you can invoke it with a single command like /deploy-backend or /optimize-images.
What are skills? They're markdown files containing instructions, context, and examples that guide Claude through specific tasks. They live in your project, your home directory, or in plugin packages—giving you flexibility in how you organize and share them.
Types of Skills
Claude Code supports three types of skills, each with different use cases and scopes. Understanding these distinctions helps you organize your workflow efficiently.
Plugin Skills
Plugin skills are distributed as npm packages and can be installed globally. They're perfect for sharing common workflows across teams or the community.
# Install a plugin skill globally
npm install -g @claude-code/skill-docker
# The skill is now available in all projects
claude /docker-compose-setup
Location: ~/.claude/plugins/node_modules/@scope/package/skills/
Managed Skills
Managed skills are user-level skills stored in your home directory. They're available across all projects but are personal to you. Perfect for workflows you use frequently but don't want to package as a plugin.
# Create a managed skill
mkdir -p ~/.claude/skills
touch ~/.claude/skills/optimize-assets.md
# Now available in any project
claude /optimize-assets
Location: ~/.claude/skills/
Project Skills
Project skills live inside your codebase and are specific to that project. They're version-controlled alongside your code and shared with the team. Ideal for project-specific workflows like deployment or testing procedures.
# Create a project skill
mkdir -p .claude/skills
touch .claude/skills/deploy-staging.md
# Only available in this project
claude /deploy-staging
Location: .claude/skills/ (project root)
Creating Custom Skills
Skill Structure
A skill is a markdown file with a specific structure. The filename (without .md) becomes the command name. Here's the anatomy of a well-crafted skill:
# Skill Name
Brief description of what this skill does.
## Context
Provide background information Claude needs to understand:
- What problem this solves
- When to use this skill
- Relevant project conventions or constraints
## Instructions
Step-by-step instructions:
1. First, do this specific thing
2. Then, validate by checking X
3. Finally, update documentation
## Examples
### Example 1: Basic Usage
```
Input: User request pattern
Expected Output: What Claude should produce
```
### Example 2: Edge Case
```
Input: Complex scenario
Expected Output: How to handle it
```
## Success Criteria
How to verify the task completed successfully:
- [ ] All tests pass
- [ ] Documentation updated
- [ ] No linting errorsBest Practices
Creating effective skills is an art. Here are principles learned from building dozens of custom skills:
1. Be Specific and Actionable: Vague instructions lead to inconsistent results. Instead of "improve the code," say "refactor using the Repository pattern, following the example in src/repositories/UserRepository.ts."
2. Include Context: Tell Claude about your project's conventions, architectural decisions, and constraints. This prevents it from making assumptions that conflict with your setup.
## Context
This project uses:
- TypeScript strict mode
- ESLint with Airbnb config
- Jest for testing
- Functional components (no classes)
- CSS Modules (not styled-components)
All components must have corresponding test files.3. Provide Examples: Show Claude what success looks like. Examples are more powerful than descriptions.
4. Define Success Criteria: Give Claude a checklist to verify completion. This ensures nothing is forgotten and provides clear done conditions.
5. Keep Skills Focused: One skill, one job. Don't create a mega-skill that does everything. Instead, create modular skills that can be combined.
Using Skills
Once you've created a skill, using it is straightforward. Claude Code automatically discovers skills in the configured directories and makes them available as commands.
# List all available skills
claude /skills
# Invoke a skill
claude /skill-name
# Pass additional context to a skill
claude /optimize-images --format=webp --quality=85
# Combine with natural language
claude /deploy-staging "Use the feature/user-auth branch"Practical Examples
Let's explore real-world skills that solve common development challenges. These examples demonstrate different complexity levels and use cases.
Document Manipulation Skill
A skill for converting documentation between formats while maintaining structure and metadata.
# convert-docs
Convert documentation files between formats (Markdown, HTML, PDF) while preserving structure, links, and metadata.
## Context
This project maintains documentation in multiple formats:
- Source: Markdown in `/docs`
- Output: HTML for website, PDF for downloads
- Preserve: Internal links, code blocks, images
- Style: Use project CSS from `/assets/docs.css`
## Instructions
1. Identify input file(s) and desired output format
2. Parse source maintaining:
- Heading hierarchy
- Code block syntax highlighting
- Internal link references
- Image paths (update if needed)
3. Convert to target format
4. For HTML: Apply project CSS
5. For PDF: Use headless browser for rendering
6. Validate output:
- All links work
- Code blocks formatted correctly
- Images display properly
7. Save to appropriate output directory
## Examples
### Example: Markdown to HTML
```
Input: docs/api/authentication.md
Output: public/docs/api/authentication.html
- Convert markdown syntax
- Apply docs.css stylesheet
- Update internal links to .html
- Copy referenced images to public/docs/api/images/
```
## Success Criteria
- [ ] Output file created in correct directory
- [ ] All internal links functional
- [ ] Code blocks have syntax highlighting
- [ ] Images display correctly
- [ ] No conversion warnings or errorsTesting Workflow Skill
A comprehensive skill that ensures proper test coverage and quality for new features.
# comprehensive-test
Create comprehensive test suite for new features including unit, integration, and E2E tests.
## Context
Testing standards:
- Framework: Jest + React Testing Library
- Coverage threshold: 80% minimum
- Integration tests: API contracts validated
- E2E tests: Critical user flows only
- Mock external dependencies
- Follow AAA pattern (Arrange, Act, Assert)
## Instructions
1. Analyze the feature code to identify:
- Public API surface
- Edge cases and error conditions
- Integration points
- User-facing workflows
2. Create unit tests:
- Test each public method/function
- Cover edge cases
- Test error handling
- Mock dependencies
3. Create integration tests:
- Test component interactions
- Validate API contracts
- Test data flow
- Use actual API calls (not mocked)
4. Create E2E tests (if user-facing):
- Test critical user journey
- Use Playwright
- Include both happy path and error scenarios
5. Run full test suite and verify coverage
## Examples
### Example: API Endpoint Feature
```
Feature: User registration endpoint
Unit Tests:
- Input validation (valid/invalid email, password strength)
- Hash password correctly
- Handle duplicate email
- Return correct status codes
Integration Tests:
- POST /api/register with valid data
- Verify user created in database
- Verify email sent
- Test rate limiting
E2E Test:
- Navigate to /register
- Fill form with valid data
- Submit and verify redirect
- Check confirmation email received
```
## Success Criteria
- [ ] Coverage ≥ 80%
- [ ] All tests pass
- [ ] Integration tests validate API contracts
- [ ] E2E tests cover critical user flows
- [ ] No console errors during test runs
- [ ] Tests run in under 30 secondsDeployment Automation Skill
A skill that handles the complete deployment workflow with safety checks and rollback procedures.
# deploy-production
Execute production deployment with safety checks, health monitoring, and rollback capability.
## Context
Infrastructure:
- Platform: AWS ECS + Fargate
- Docker registry: ECR
- Secrets: AWS Secrets Manager
- Monitoring: CloudWatch + Datadog
- Load balancer: ALB with health checks
Deployment strategy: Blue-green deployment
## Instructions
1. Pre-deployment checks:
- [ ] All CI/CD tests passed
- [ ] Staging deployed and verified
- [ ] No incidents in last 24h
- [ ] Database migrations ready (if any)
2. Build and push:
```bash
docker build -t app:$VERSION .
docker tag app:$VERSION $ECR_REPO:$VERSION
docker push $ECR_REPO:$VERSION
```
3. Run database migrations:
- Execute in transaction
- Test rollback before committing
4. Deploy to production:
- Update ECS task definition with new image
- Deploy to "green" environment
- Wait for health checks to pass (5 consecutive successes)
5. Traffic switch:
- Update ALB to route traffic to green
- Monitor error rates for 5 minutes
- If error rate > 1%, trigger rollback
6. Post-deployment:
- Verify critical endpoints
- Check CloudWatch metrics
- Update deployment log
- Send Slack notification
## Rollback Procedure
If deployment fails:
1. Update ALB to route back to blue
2. Revert ECS task definition
3. Roll back database migrations (if any)
4. Alert team via Slack
5. Create incident report
## Success Criteria
- [ ] New version deployed
- [ ] Health checks passing
- [ ] Error rate < 1%
- [ ] Response time within SLA
- [ ] All critical endpoints responding
- [ ] Datadog dashboards green
- [ ] Team notified of successful deploymentThese three skills demonstrate the range of what's possible: from simple utilities to complex workflows with safety checks and monitoring. The key is specificity—the more detailed your instructions, the more reliable the results.
Conclusion
Skills transform Claude Code from a helpful assistant into a specialized expert tailored to your workflow. By investing time in creating well-crafted skills, you:
- Reduce repetition: Complex workflows become single commands
- Ensure consistency: Everyone follows the same procedures
- Capture knowledge: Domain expertise is documented and reusable
- Accelerate onboarding: New team members get instant workflow guidance
Start small—create a skill for your most frequent task. As you get comfortable with the structure, expand to more complex workflows. Before you know it, you'll have a library of specialized skills that make your entire team more productive.