Custom Skills & Agents: Extend Claude Code's Capabilities

Introduction to Skills

Why Skills Matter

The Skills Hierarchy

.claude/
├── CLAUDE.md            # Project-level context
├── settings.json        # Configuration
└── skills/              # Skills directory
    ├── code-review/
    │   └── SKILL.md
    ├── security-audit/
    │   └── SKILL.md
    └── test-generator/
        └── SKILL.md

Skill Architecture

Every skill is defined by a SKILL.md file with a specific structure:

SKILL.md Anatomy

---
name: security-audit
description: Comprehensive security analysis following OWASP standards
allowed-tools: Read, Grep, Glob, Bash
context: fork
model: sonnet
---

# Security Audit Skill

You are a security expert...

[Detailed instructions]

Frontmatter Fields

Context Modes

Interactive Skill Builder

Use this wizard to create your own custom skill. Choose a type, configure options, and generate a complete SKILL.md file:

Built-in Skills

Claude Code comes with several pre-built skills you can use immediately or customize:

1. Code Review Skill

---
name: code-review
description: Thorough code review with actionable feedback
allowed-tools: Read, Grep, Glob
context: fork
---

# Code Review Skill

You are a senior engineer conducting a thorough code review.

## Review Checklist
- [ ] Logic correctness
- [ ] Error handling
- [ ] Performance implications
- [ ] Security considerations
- [ ] Test coverage
- [ ] Code style/conventions

## Severity Levels
- 🔴 Critical: Must fix before merge
- 🟡 Warning: Should address
- 🟢 Suggestion: Nice to have
- ℹ️ Info: FYI only

## Output Format
For each finding:
1. File and line number
2. Severity level
3. Issue description
4. Suggested fix with code example

2. Test Generator Skill

---
name: test-generator
description: Generate comprehensive test suites with TDD methodology
allowed-tools: Read, Write, Grep, Bash
context: fork
---

# Test Generator Skill

You are a testing expert practicing TDD methodology.

## Test Types to Generate
1. **Unit Tests**: Pure function testing
2. **Integration Tests**: Component interaction
3. **Edge Cases**: Boundary conditions
4. **Error Cases**: Expected failures

## Framework Detection
- React: Jest + React Testing Library
- Node: Vitest or Jest
- Python: pytest
- Go: testing package

## Naming Convention
`test_[function_name]_[scenario]_[expected_result]`

Example:
```python
def test_validate_email_empty_string_returns_false():
    assert validate_email("") == False

Coverage Goals

• →Happy path: 100%
• →Edge cases: 80%
• →Error handling: 90%

### 3. Documentation Skill

```markdown
---
name: documentation
description: Generate comprehensive documentation for any codebase
allowed-tools: Read, Write, Grep, Glob
context: fork
---

# Documentation Skill

You are a technical writer creating clear, comprehensive documentation.

## Documentation Types
1. **README.md**: Project overview, setup, usage
2. **API Docs**: Endpoint reference with examples
3. **Code Docs**: JSDoc/docstrings
4. **Guides**: How-to tutorials

## Quality Checklist
- [ ] Clear purpose statement
- [ ] Prerequisites listed
- [ ] Step-by-step instructions
- [ ] Code examples for key features
- [ ] Troubleshooting section
- [ ] Contribution guidelines

## Style Guide
- Use active voice
- Keep sentences short
- Include code examples
- Add diagrams for complex flows
- Link to related resources

Agent Patterns

Combine skills into powerful agents for complex workflows:

Pattern 1: Sequential Pipeline

# PR Review Agent

## Steps
1. Run `code-review` skill on changed files
2. Run `security-audit` skill on changed files  
3. Run `test-generator` for new code paths
4. Compile results into PR comment format

## Configuration
```json
{
  "name": "pr-review-agent",
  "skills": ["code-review", "security-audit", "test-generator"],
  "mode": "sequential"
}

Pattern 2: Parallel Analysis

# Codebase Health Check Agent

## Parallel Skills
- Performance analyzer
- Security auditor
- Dependency checker
- Code quality scorer

## Aggregation
Combine all results into unified health report with scores.

Pattern 3: Conditional Branching

# Smart Review Agent

## Logic
IF file is `.py`:
  → Run Python-specific review
ELIF file is `.tsx`:
  → Run React + TypeScript review
ELIF file is `.sql`:
  → Run SQL security review
ELSE:
  → Run generic code review

Advanced Techniques

1. Skill Composition

Create meta-skills that combine others:

---
name: full-audit
description: Complete codebase audit combining multiple skills
allowed-tools: Task, Read, Grep
---

# Full Audit Meta-Skill

## Execution Order
1. Spawn `security-audit` task
2. Spawn `performance-review` task  
3. Spawn `accessibility-check` task
4. Await all results
5. Generate unified report

## Usage
Use the `Task` tool to spawn sub-agents:
- Each skill runs in forked context
- Results are collected and synthesized
- Final report highlights critical issues first

2. Dynamic Skill Loading

Load skills based on project type:

---
name: project-analyzer
description: Detect project type and load appropriate skills
allowed-tools: Read, Glob, Task
---

# Project Analyzer

## Detection Logic
1. Check for package.json → Load Node.js skills
2. Check for requirements.txt → Load Python skills
3. Check for go.mod → Load Go skills
4. Check for Cargo.toml → Load Rust skills

## Per-Project Skills
- Node.js: eslint-check, npm-audit, jest-runner
- Python: pylint-check, bandit-audit, pytest-runner
- Go: golint-check, gosec-audit, gotest-runner

3. Skill Chaining with State

Pass state between skills:

---
name: refactor-pipeline
description: Multi-stage refactoring with state preservation
allowed-tools: Read, Write, Edit, Task
---

# Refactor Pipeline

## Stage 1: Analysis
- Identify code smells
- Map dependencies
- Output: analysis.json

## Stage 2: Planning
- Input: analysis.json
- Generate refactor plan
- Output: plan.json

## Stage 3: Execution
- Input: plan.json
- Apply refactoring
- Run tests after each change

## Stage 4: Verification
- Run full test suite
- Compare before/after metrics
- Generate summary report

4. User Interaction Skills

Skills that prompt for user input:

---
name: interactive-setup
description: Guided project setup with user prompts
allowed-tools: Read, Write, Bash
---

# Interactive Setup Skill

## Flow
1. Detect project type
2. Ask: "Which testing framework?"
   - Options: Jest, Vitest, Mocha
3. Ask: "Include TypeScript?"
   - Options: Yes, No
4. Ask: "Add CI/CD?"
   - Options: GitHub Actions, GitLab CI, None

## Based on answers:
- Generate appropriate configuration files
- Install dependencies
- Create starter tests

Best Practices

Do's ✅

1. →Keep skills focused - Single responsibility
2. →Include examples - Show expected input/output
3. →Define clear outputs - Specify format expectations
4. →Version your skills - Track changes in git
5. →Test skills regularly - Validate with real use cases

Don'ts ❌

1. →Don't hardcode paths - Use patterns and relative paths
2. →Don't grant unnecessary tools - Principle of least privilege
3. →Don't make skills too generic - Specific is better
4. →Don't skip the description - Others need to understand
5. →Don't forget edge cases - Define behavior for unusual inputs

Test Your Knowledge

Next Steps

Now that you can create custom skills:

1. →Master Hooks - Trigger skills automatically with event hooks
2. →Explore MCP Servers - Connect skills to external services
3. →Build Workflows - Orchestrate multi-tool pipelines