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("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

.claude/agents/

.claude/skills/{name}/

/output-style

.claude/output-styles/

Agent Development

Reference:

references/agent-development.md

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

name

code-reviewer

description

\n

tools

model

haiku

sonnet

opus

inherit

permissionMode

default

acceptEdits

bypassPermissions

plan

ignore

skills

Model Selection

haiku

sonnet

opus

inherit

Built-in Subagents

general-purpose

plan

Explore

Agent Locations

.claude/agents/

~/.claude/agents/

agents/

--agents

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

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

name

description

allowed-tools

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

.claude/skills/{name}/SKILL.md

~/.claude/skills/{name}/SKILL.md

skills/

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

name

description

keep-coding-instructions

false

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: ✅