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

Skills are where the hype most frequently exceeds what's actually shipping. A recurring observation across r/ClaudeAI threads: users spend a weekend writing five custom skills, then watch three of them never get invoked because the descriptions don't match how they actually phrase tasks. The mechanism is documented in Anthropic's skills announcement — Claude reads the description field and decides whether the skill is relevant — but the implication is under-appreciated: a skill that nobody can summon is just a folder of dead prose.

What practitioners actually do: treat SKILL.md like a CLI man page, not like a wiki article. The best skills in the wild (see community collections on github.com and in the MCP servers registry) have descriptions written in the exact phrasing a user would type, plus a tight list of preconditions. Everything else — context, examples, rationale — lives inside, and is only read when the skill is actually triggered.

Where the community correctly pushes back: skills are not a substitute for deterministic scripts. If your "skill" is really a 15-step bash pipeline, write the bash pipeline and let the skill call it. The strength of skills is discretionary invocation under ambiguity; the strength of scripts is repeatability under certainty. Mixing those roles is how teams end up with agents that feel magical on day one and broken by week two.

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

Pro Tips

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

Continue Learning

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