Claude Extensibility

Claude Code Extensibility

CRUD operations for agents, skills, and output styles following Anthropic best practices.

Related Skills

IMPORTANT: When creating or editing prompts, use prompt-enhancer skill to improve quality.

Skill("prompt-enhancer")  → Enhance skill/agent prompt content

Core Principles

• Simplicity: Direct tool calls, avoid complex abstractions
• Focus: Single, clear responsibility per extension
• Conciseness: Target <500 lines, use progressive disclosure
• Efficiency: Optimize for token usage and response time

Extension Types

Agent Development

Reference: references/agent-development.md - Full YAML structure, model/tool selection, system prompt patterns, optimization techniques.

Quick Start: Agent

---
name: agent-name
description: Use this agent when [use case]. Use PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n<commentary>[reasoning]</commentary>\n</example>
tools: Grep, Glob, Read, Bash
model: haiku
permissionMode: default
skills: skill-name
---

# Agent Name

Brief mission statement.

## Core Strategy

### 1. Phase Name
Approach and techniques

<format>
Expected output structure
</format>

YAML Fields

Model Selection

Built-in Subagents

Agent Locations

CLI-Defined Agents

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Resumable Agents

Continue previous conversations:

• Each execution gets unique agentId
• Transcript stored in agent-{agentId}.jsonl
• Resume with previous agentId to continue with full context

Skill Development

Reference: references/skill-development.md - Full structure, trigger patterns, hook system.

Quick Start: Skill

---
name: skill-name
description: "[What it does]. [Technologies]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."
allowed-tools: Read, Grep, Glob
---

# Skill Name

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
Guidance, patterns, examples

YAML Fields

Description Format (WHAT + WHEN)

Structure:

"[Core purpose]. [Technologies/Stack]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."

Good example:

description: "Extract text and tables from PDF files, fill forms, merge documents. Formats: .pdf. Tools: pypdf, pdfplumber. Capabilities: text extraction, form filling, document merging. Actions: extract, fill, merge PDFs. Keywords: PDF, form, document, pypdf, pdfplumber. Use when: working with PDF files, extracting data from documents, filling PDF forms."

Bad examples:

description: Helps with documents  # Too vague
description: PDF skill  # Missing WHEN triggers

Tool Access Control

Restrict Claude's tools with allowed-tools:

---
name: safe-reader
description: "Read-only file access. Use when viewing code without modifications."
allowed-tools: Read, Grep, Glob
---

Skill Locations

Skill Structure

my-skill/
├── SKILL.md (required)
├── references/ (optional - detailed docs)
├── scripts/ (optional - utilities)
└── templates/ (optional - templates)

Output Styles

Modify Claude Code's main agent behavior.

Quick Start: Output Style

---
name: My Custom Style
description: Brief description of behavior
keep-coding-instructions: true
---

# Custom Style Instructions

You are an interactive CLI tool that helps users...

## Specific Behaviors
[Define assistant behavior...]

YAML Fields

Built-in Styles

• Default: Standard software engineering
• Explanatory: Educational insights between tasks
• Learning: Collaborative with TODO(human) markers

Output Style Locations

• User: ~/.claude/output-styles/
• Project: .claude/output-styles/

Usage

/output-style              # Access menu
/output-style explanatory  # Switch directly

Testing

Key Question: Does it activate when expected?

Agent Testing:

Task(
  subagent_type="agent-name",
  description="Test task",
  prompt="Detailed test prompt"
)

Skill Testing:

• Test prompts that SHOULD trigger
• Test prompts that should NOT trigger
• Debug with: claude --debug

Common Workflows

Create Agent

1. Create .claude/agents/{name}.md 2. Write YAML frontmatter (name, description, tools, model) 3. Write system prompt (<500 lines) 4. Test with Task tool 5. Optimize based on performance

Create Skill

1. Create .claude/skills/{name}/SKILL.md 2. Write YAML frontmatter with WHAT + WHEN description 3. Write content (<500 lines) 4. Use `Skill("prompt-enhancer")` to improve prompt 5. Add reference files for detailed content 6. Test: Does it activate when expected?

Optimize Extension

1. Measure baseline (lines, token usage, response time) 2. Move details to reference files 3. Use `Skill("prompt-enhancer")` to improve prompts 4. Remove second-person voice 5. Use code blocks over prose 6. Add XML structure 7. Test and verify improvements

Best Practices

Anthropic Guidelines

✅ 500-line rule: Keep SKILL.md and agent prompts under 500 lines ✅ Progressive disclosure: Use reference files for detailed content ✅ Proactive language: Include "use PROACTIVELY" in descriptions ✅ WHAT + WHEN descriptions: Both capability and triggers ✅ Test first: Build 3+ evaluations before extensive documentation ✅ Least privilege: Limit tools to necessary set

Anti-Patterns

❌ Vague descriptions without triggers ❌ Over 500 lines without references ❌ Second-person voice ("you should...") ❌ All tools when subset suffices ❌ No examples in agent descriptions

Quick Reference

Agent Model Selection:

• Haiku: Fast, simple tasks (< 3s)
• Sonnet: Balanced, most use cases (< 10s)
• Opus: Complex reasoning (< 30s)
• Inherit: Match main conversation

File Locations:

• Agents: .claude/agents/*.md
• Skills: .claude/skills/{name}/SKILL.md
• Output Styles: .claude/output-styles/*.md

Management Commands:

• /agents - Interactive agent management
• /output-style - Switch output styles

---

Status: Production Ready | Lines: ~200 | Progressive Disclosure: ✅

Agent Development Guide

Table of Contents

1. YAML Frontmatter Structure 2. Configuration Fields 3. Model Selection Guide 4. Tool Selection Strategy 5. System Prompt Design 6. Built-in Subagents 7. Advanced Features 8. Agent Patterns 9. Optimization Checklist

YAML Frontmatter Structure

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked. Use PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n<commentary>[reasoning]</commentary>\n</example>
tools: tool1, tool2, tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach.

Configuration Fields

name

• Lowercase with hyphens only
• Descriptive and unique
• Examples: codebase-explorer, code-reviewer, debugger

description

• MUST be a single line - use \n for newlines (no quotes needed in YAML)
• Start with "Use this agent when..." followed by use cases
• Include "Use PROACTIVELY" for automatic delegation
• Include 2-3 inline <example> blocks
• Format: <example>\nContext: ...\nuser: ...\nassistant: ...\n<commentary>...</commentary>\n</example>
• Max ~300 words (examples add value)
• Do NOT use YAML multiline syntax (>-, |, >)

tools

• Comma-separated list of allowed tools
• Omit to inherit all tools from main agent
• Common: Grep, Glob, Read, Bash, Write, Edit
• Principle of least privilege: Only grant necessary tools

model

• haiku: Fast, cost-efficient (exploration, search)
• sonnet: Balanced (most use cases, default)
• opus: Complex reasoning (architecture, analysis)
• inherit: Match main conversation model

permissionMode

skills

• Comma-separated skill names to auto-load
• Skills activated when agent starts
• Example: skills: pdf-processing, data-analysis

Model Selection Guide

Choose Haiku when:

• Fast response required (< 3 seconds target)
• Simple, well-defined tasks
• Search and discovery operations
• Cost sensitivity critical

Choose Sonnet when:

• Balanced performance needed
• Moderate complexity
• Most general-purpose tasks
• Default choice

Choose Opus when:

• Complex reasoning required
• Architectural decisions
• Multi-step analysis
• Security audits

Choose Inherit when:

• Agent should match main conversation capabilities
• Consistency with user's model choice

Tool Selection Strategy

Read-only Exploration

Grep, Glob, Read, Bash

Use for: Codebase analysis, file discovery, pattern matching

Analysis without Search

Read, Bash

Use for: Code review, metrics collection, static analysis

Code Modifications

Write, Edit, Bash

Use for: Feature implementation, refactoring, file creation

Comprehensive

(omit tools field to inherit all)

Use for: Complex workflows, multi-phase operations

Principle: Start minimal, expand if needed.

System Prompt Design

Voice Guidelines

✅ Use: Imperative, infinitive, active voice ✅ Examples: "Find files...", "Analyze code...", "Execute searches..."

❌ Avoid: Second person, passive voice, filler words ❌ Examples: "You should find...", "Files can be found...", "Simply search..."

XML Tag Usage

Use XML tags for:

• <principles> - Core design philosophy
• <exploration_patterns> - Grouped techniques
• <format> - Output structure
• <error_handling> - Recovery strategies
• <constraints> - Limitations and targets

Keep in natural language:

• Main mission statement
• High-level strategy
• Phase/step descriptions

Prompt Optimization

Progressive Disclosure:

• Main agent file (<500 lines): Core strategy and common patterns
• Reference files: Comprehensive examples, language-specific patterns

Compression Strategies:

• Use code blocks instead of prose
• Consolidate repetitive examples
• Abbreviate patterns

Built-in Subagents

General-Purpose Subagent

• Model: Sonnet
• Tools: All tools
• Purpose: Complex research tasks, multi-step operations, code modifications
• Use when: Task requires both exploration and modification

Plan Subagent

• Model: Sonnet
• Tools: Read, Glob, Grep, Bash
• Purpose: Research and gather information in plan mode
• Automatic use: When in plan mode and codebase research needed

Explore Subagent

• Model: Haiku (fast, low-latency)
• Mode: Strictly read-only
• Tools: Glob, Grep, Read, Bash (read-only commands only)
• Thoroughness levels: quick, medium, very thorough
• Use when: Need to search/understand codebase without changes

Advanced Features

Resumable Subagents

Continue previous agent conversations with stored context:

• Each execution gets unique agentId
• Transcript stored in agent-{agentId}.jsonl
• Resume with previous agentId to continue with full context

Task(
  subagent_type="code-reviewer",
  description="Continue review",
  prompt="Continue from previous context...",
  resume="agent-abc123"  # Previous agentId
)

CLI-Defined Agents

Define agents at runtime via command line:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Chaining Subagents

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

Dynamic Selection

Claude intelligently selects agents based on:

• Task description matching
• Description field specificity
• Context relevance

Agent Patterns

File Discovery Agent

---
name: file-finder
description: Locate files across codebase using name patterns, code structures, or feature relationships. Use PROACTIVELY when searching for files.
tools: Grep, Glob, Read, Bash
model: haiku
---

Code Review Agent

---
name: code-reviewer
description: Expert code review for quality, security, and maintainability. Use PROACTIVELY after writing or modifying code.\n\nExamples:\n<example>\nContext: User finished implementing auth endpoint\nuser: "I've implemented the auth endpoint"\nassistant: "I'll review the implementation for security and quality"\n<commentary>Proactive review after code changes</commentary>\n</example>
tools: Read, Grep, Glob, Bash
model: sonnet
---

Architecture Analyst

---
name: architecture-analyst
description: Analyze system architecture, evaluate design patterns, and understand complex codebases. Use for architectural decisions.
tools: Grep, Glob, Read, Bash
model: opus
---

Debugger Agent

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

Agent Locations

Invocation Methods

Automatic Delegation

User: "Find all authentication files"
→ Claude invokes file-finder automatically based on description match

Explicit Invocation

User: "Use the code-reviewer agent to check my changes"
→ Claude invokes code-reviewer explicitly

Programmatic

Task(
  subagent_type="codebase-explorer",
  description="Find payment processing files",
  prompt="Search for payment, transaction, checkout patterns",
  model="haiku"
)

Optimization Checklist

• [ ] Reduce to <500 lines (move details to references)
• [ ] Remove second-person voice
• [ ] Add XML tags for structure
• [ ] Consolidate repetitive examples
• [ ] Use code blocks over prose
• [ ] Include "PROACTIVELY" in description
• [ ] Provide executable examples
• [ ] Add clear response format
• [ ] Include error recovery
• [ ] Specify performance targets
• [ ] Test with real scenarios
• [ ] Limit tools to necessary set

Success Criteria

Well-designed agent has: 1. Clear, focused mission (single responsibility) 2. Appropriate model selection (cost/performance balance) 3. Minimal tool set (least privilege) 4. Concise prompt (<500 lines or references) 5. Executable examples (tested and working) 6. Clear response format 7. Error recovery strategies 8. Performance targets specified 9. "PROACTIVELY" trigger in description

Performance Targets

Skill Development Guide

Table of Contents

1. Skill Structure 2. YAML Frontmatter 3. Description Best Practices 4. Tool Access Control 5. Progressive Disclosure 6. Skill Types 7. Testing and Debugging 8. Common Patterns

Skill Structure

Skills are directories containing a required SKILL.md file plus optional supporting files:

my-skill/
├── SKILL.md (required)
├── references/ (optional - detailed documentation)
│   ├── api-reference.md
│   └── examples.md
├── scripts/ (optional - utility scripts)
│   └── helper.py
└── templates/ (optional - templates)
    └── template.txt

Storage Locations

YAML Frontmatter

Required YAML frontmatter with Markdown content:

---
name: your-skill-name
description: "Brief description of what this Skill does and when to use it"
allowed-tools: Read, Grep, Glob
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

Field Requirements

Description Best Practices

Critical for discovery - Skills are model-invoked (Claude autonomously decides when to use them). Description must include BOTH capability AND triggers.

WHAT + WHEN Format

Structure:

"[Core purpose]. [Technologies/Stack]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."

Section Breakdown

Good Examples

# PDF Processing
description: "Extract text and tables from PDF files, fill forms, merge documents. Formats: .pdf. Tools: pypdf, pdfplumber. Capabilities: text extraction, form filling, document merging. Actions: extract, fill, merge PDFs. Keywords: PDF, form, document, pypdf, pdfplumber. Use when: working with PDF files, extracting data from documents, filling PDF forms."

# Excel Processing
description: "Excel spreadsheet processing and analysis. Formats: .xlsx, .xlsm, .csv, .tsv. Capabilities: create spreadsheets, formulas (error-free), formatting, data analysis, charts, pivot tables. Actions: create, edit, analyze, visualize spreadsheets. Keywords: Excel, spreadsheet, xlsx, csv, formula, VLOOKUP, SUMIF, pivot table. Use when: creating spreadsheets, editing Excel files, analyzing tabular data."

# Git Commit Messages
description: "Generate clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes."

Bad Examples

description: Helps with documents  # Too vague - no keywords, no triggers
description: PDF skill  # Missing capabilities, actions, keywords
description: Excel skill for spreadsheets  # Missing WHEN triggers

Clear Distinction Between Similar Skills

# Sales Analysis Skill
description: "Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking."

# System Monitoring Skill
description: "Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics."

Tool Access Control

Restrict Claude's tool usage with allowed-tools for security and focus:

---
name: safe-file-reader
description: "Read files without making changes. Use when you need read-only file access."
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern

Use Cases for Tool Restriction

Progressive Disclosure

Claude reads supporting files only when needed. Reference them from SKILL.md:

# PDF Processing

## Quick Start

Extract text:

import pdfplumber with pdfplumber.open("doc.pdf") as pdf: text = pdf.pages[0].extract_text()

For form filling, see [references/forms.md](references/forms.md).
For detailed API reference, see [references/api.md](references/api.md).

## Requirements

pip install pypdf pdfplumber

Guidelines

• Main SKILL.md: <500 lines, core guidance
• Reference files: Detailed documentation, examples, edge cases
• Table of contents: Add to reference files > 100 lines
• One level deep: Don't nest references deeply

Skill Types

Domain Skills

Purpose: Provide comprehensive guidance for specific technical areas

Characteristics:

• Advisory, not mandatory
• Topic or domain-specific
• Best practices documentation

Examples:

• backend-dev-guidelines - Node.js/Express patterns
• frontend-dev-guidelines - React/TypeScript practices
• database-operations - SQL/NoSQL patterns

Guardrail Skills

Purpose: Enforce critical best practices that prevent errors

Characteristics:

• Enforcement via hooks
• Block operations until verified
• Session-aware

Examples:

• database-verification - Verify table/column names before queries
• security-review - Check for vulnerabilities before deployment

Tool-Restricted Skills

Purpose: Provide capabilities with limited tool access

Characteristics:

• allowed-tools field set
• Read-only or limited scope
• Security-sensitive workflows

Testing and Debugging

Key Question: Does it activate when expected?

Manual Testing

# Check if skill triggers on expected prompt
# In Claude Code, type prompts that should trigger the skill:
> "Help me extract text from a PDF"
> "Create an Excel formula for..."
> "Generate a commit message"

Debug Mode

claude --debug

Shows skill loading and activation decisions.

Common Issues

Debugging Checklist

• [ ] SKILL.md exists in correct location
• [ ] YAML frontmatter valid (check --- delimiters)
• [ ] Name is lowercase with hyphens only
• [ ] Description is quoted and < 1024 chars
• [ ] Description includes WHAT + WHEN
• [ ] Content is < 500 lines
• [ ] No tab characters (use spaces)

Common Patterns

Simple Skill (Single File)

---
name: generating-commit-messages
description: "Generate clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes."
---

# Generating Commit Messages

## Instructions
1. Run `git diff --staged` to see changes
2. Suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best Practices
- Use present tense
- Explain what and why, not how

Skill with Tool Permissions

---
name: code-reviewer
description: "Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality."
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review Checklist
1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage

Multi-File Skill with References

---
name: pdf-processing
description: "Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages."
---

# PDF Processing

## Quick Start

Extract text:

import pdfplumber with pdfplumber.open("doc.pdf") as pdf: text = pdf.pages[0].extract_text()

For form filling, see [references/forms.md](references/forms.md).
For detailed API reference, see [references/api.md](references/api.md).

## Requirements

pip install pypdf pdfplumber

Best Practices Summary

Do

✅ Include WHAT + WHEN in description ✅ Keep SKILL.md under 500 lines ✅ Use reference files for detailed content ✅ Include specific keywords for discovery ✅ Test with real prompts before finalizing ✅ Use allowed-tools for security-sensitive skills ✅ Document dependencies and requirements

Don't

❌ Write vague descriptions ❌ Exceed 500 lines without references ❌ Use generic terms that overlap with other skills ❌ Skip testing activation triggers ❌ Forget "Use when" scenarios ❌ Use tabs (use spaces instead)

Lifecycle

Create: Place SKILL.md in correct location Update: Edit SKILL.md directly; changes apply on next Claude Code start Remove: Delete the skill directory and commit changes Share: Commit .claude/skills/ to git for team access