claude-extensibility

name

claude-extensibility

description

Claude Code extensibility: agents, skills, output styles. Capabilities: create/update/delete agents and skills, YAML frontmatter, system prompts, tool/model selection, resumable agents, CLI-defined agents. Actions: create, edit, delete, optimize, test extensions. Keywords: agent, skill, output-style, SKILL.md, subagent, Task tool, progressive disclosure. Use when: creating agents/skills, editing extensions, configuring tool access, choosing models, testing activation.

Claude Code Extensibility

CRUD operations for agents, skills, and output styles. This skill transfers expertise in building extensions that actually activate and deliver value.

Related Skills

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

Skill("prompt-architect")  → Create/enhance skill/agent prompt content

Core Principles

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

Core Truths

Every extension must embody these principles:

Truth	Meaning	Test
Expertise Transfer	Make Claude think like expert, not follow steps	Does it transfer patterns or just procedures?
Flow, Not Friction	Produce output, not intermediate work	Does it help produce results or create busywork?
Voice Matches Domain	Sound like practitioner, not documentation	Would an expert recognize this as their thinking?
Focused Beats Comprehensive	Constrain ruthlessly	Does every section earn its place?

Decision Heuristics

Rule	Guidance
3-File Rule	Task touches 3+ files → agent (needs autonomy). Enhances how YOU work → skill.
Delegation Test	"Does this run independently while I do other work?" Yes → agent. No → skill.
Expert Test	"Would an expert do this differently than beginner?" Big difference → skill.
Activation Breadth	Trigger on 80% of relevant requests, not 100%. Over-broad = noise.
Composition Preference	When in doubt, 2 small focused extensions > 1 large monolith.
Tool Constraint	Start with 2-3 essential tools. Adding is easy; removing breaks things.

Expert Patterns

The "Everything Tool" Request

When you see: User wants one agent/skill to handle auth, database, API, and testing This indicates: Scope creep that will create bloated, unfocused extension Therefore: Split into focused single-responsibility extensions; suggest composition Watch out: User may resist - explain that 3 focused skills outperform 1 swiss-army-knife

The Wrapper Trap

When you see: Skill that just wraps a CLI tool with no added expertise This indicates: Missing the expertise transfer opportunity Therefore: Ask "what would an expert know that the tool doesn't tell you?" Watch out: The skill becomes redundant with just reading --help

Activation Keyword Starvation

When you see: Frontmatter description uses only formal/technical terms This indicates: Skill won't activate when users use casual language Therefore: Add synonyms, verbs, casual phrasings to description Watch out: Over-broad keywords cause false activations

The Procedure Manual

When you see: Step 1, Step 2, Step 3... (long numbered instructions) This indicates: Procedures don't transfer judgment - expert skips steps, adapts order Therefore: Teach patterns and heuristics. Let reader apply judgment. Watch out: Some workflows genuinely need sequence - use sparingly

Extension Types

Type	Invocation	Purpose	Location
Agents	Task tool	Specialized sub-processes	.claude/agents/
Skills	Model-invoked (autonomous)	Domain knowledge	.claude/skills/{name}/
Output Styles	/output-style command	Modify main agent behavior	.claude/output-styles/

Activation Keyword Engineering

The description field is your activation gate. System reads ONLY frontmatter to decide loading. Brilliant skill + poor keywords = dead skill.

Keyword Categories to Include

1. Task Verbs: create, build, debug, fix, deploy, optimize, refactor
2. Problem Descriptions: slow, broken, failing, error, conflict
3. Artifact Types: component, API, database, test, config
4. Tool/Framework Names: React, PostgreSQL, Docker (exact + misspellings)
5. Casual Synonyms: "make it faster" → optimize, performance

Description Format (WHAT + WHEN)

# Bad - too vague, won't trigger
description: Helps with documents

# Bad - missing WHEN triggers
description: PDF skill

# Good - multiple trigger points
description: "Extract text and tables from PDF files, fill forms, merge documents.
  Formats: .pdf. Tools: pypdf, pdfplumber. Actions: extract, fill, merge PDFs.
  Keywords: PDF, form, document. Use when: working with PDF files, extracting data."

Frontmatter Checklist

• Name is clear and descriptive (not abbreviation)
• Description includes file types if applicable (.docx, .pdf)
• Description includes task verbs (creating, editing, analyzing)
• Description includes synonyms users might say
• Description includes contexts (reports, professional documents)

Keyword Density Test

Read description aloud. For every 10 words, at least 3 should be potential triggers.

---

Agent Development

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

Quick Start: Agent

---
name: agent-name
# CRITICAL: Description is the ONLY thing system reads to decide activation
# Include: task verbs, problem descriptions, synonyms users actually say
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>
# CONSTRAIN RUTHLESSLY: 3-5 tools = focused. 10+ tools = confused.
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

## What This Agent Does NOT Do
- Does not [boundary 1] (use X agent)
- Does not [boundary 2] (escalate to user)

<format>
Expected output structure
</format>

YAML Fields

Field	Required	Description
name	Yes	Lowercase, hyphens (e.g., code-reviewer)
description	Yes	Single line with \n for newlines, include examples
tools	No	Comma-separated; inherits all if omitted
model	No	haiku, sonnet, opus, inherit (default: sonnet)
permissionMode	No	default, acceptEdits, bypassPermissions, plan, ignore
skills	No	Comma-separated skill names to auto-load

Model Selection

Model	Use When	Target Time
haiku	Fast tasks, exploration, search	< 3s
sonnet	Balanced, most use cases	< 10s
opus	Complex reasoning, architecture	< 30s
inherit	Match main conversation model	varies

Built-in Subagents

Agent	Model	Tools	Purpose
general-purpose	Sonnet	All	Complex research, multi-step operations
plan	Sonnet	Read, Glob, Grep, Bash	Research in plan mode
Explore	Haiku	Read-only	Fast codebase search (quick/medium/very thorough)

Agent Locations

Location	Scope	Priority
.claude/agents/	Project	Highest
~/.claude/agents/	User (all projects)	Lower
Plugin agents/	Plugin-specific	Varies
--agents CLI flag	Session only	Medium

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
# WHAT it does + WHEN to use it (both required!)
description: "[Core purpose]. [Technologies]. Capabilities: [list].
  Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."
allowed-tools: Read, Grep, Glob
---

# Skill Name

## Purpose
What this skill helps with - in practitioner voice.

## Patterns

### [Pattern Name]
**When you see:** [Observable trigger]
**This indicates:** [Expert insight]
**Therefore:** [Action to take]
**Watch out for:** [Common pitfall]

## Heuristics
- **[Rule of thumb]**: [When/why it applies]

## When to Use Something Else
- For X → use `other-skill`
- For Y → escalate to user

YAML Fields

Field	Required	Description
name	Yes	Lowercase, hyphens, max 64 chars
description	Yes	WHAT + WHEN format, max 1024 chars, quoted
allowed-tools	No	Restrict tool access (security)

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

Location	Scope
.claude/skills/{name}/SKILL.md	Project (shared via git)
~/.claude/skills/{name}/SKILL.md	User (all projects)
Plugin skills/	Plugin-bundled

Skill Structure

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

Core Sections (Include What's Needed)

Section	Purpose	Include When
Frontmatter	Activation trigger	Always - required
Context	Domain framing	When domain context helps
Patterns	Expert recognition	Core - almost always
Heuristics	Decision guidance	When judgment needed
Anti-Patterns	What to avoid	When mistakes are common/costly
Workflow	Process guidance	When sequence matters
Quality Signals	How to verify good work	When quality is hard to assess
Tools/Commands	Technical specifics	When implementation details matter
Output Spec	Expected format	When format is specific

---

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

Field	Purpose	Default
name	Display name	Filename
description	UI description	None
keep-coding-instructions	Retain 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

---

Writing Principles

Voice

• Sound like a practitioner, not documentation
• Direct and confident, not hedging
• Specific and concrete, not abstract

Before (documentation voice):

It is recommended that users consider implementing appropriate error handling mechanisms.

After (practitioner voice):

Always handle errors explicitly. Silent failures are debugging nightmares.

Density

• Every sentence should transfer knowledge
• No filler, no redundancy
• If it doesn't change behavior, cut it

Scannability

• Claude reads this during tasks
• Headers help Claude find relevant sections
• Patterns are scannable by name
• Bold key terms

Patterns Over Procedures

Transform procedures to patterns when expertise matters:

Before (procedure):

1. Open the file
2. Check the format
3. Validate the data
4. Process the content

After (pattern):

### Format Recognition
**When you see:** File extension and initial bytes
**This indicates:** Expected structure and parsing approach
**Therefore:** Choose parser before reading content
**Watch out for:** Extension doesn't always match actual format

---

Anti-Patterns

The Kitchen Sink Agent

Looks like: Agent with 10+ tools, handles "everything related to X" Why wrong: Broad agents make poor decisions, consume tokens exploring options Instead: Constrain to 3-5 core tools. Create sibling agents for related domains.

The Echo Skill

Looks like: Skill that restates tool documentation without adding insight Why wrong: No expertise transfer. User could just read the docs. Instead: Add the "expert layer" - pitfalls, non-obvious combos, when NOT to use.

The Invisible Trigger

Looks like: Description uses only official tool/framework name Why wrong: Users say "help me deploy" not "invoke kubernetes-orchestrator" Instead: Include task verbs, user-language synonyms, problem descriptions.

Missing Boundaries

Looks like: No explicit "what this does NOT do" section Why wrong: Scope creep, incorrect expectations, overlapping extensions Instead: Every extension needs 3+ explicit out-of-scope declarations.

Vague Descriptions

Looks like: description: Helps with documents Why wrong: Too vague to trigger on relevant requests Instead: Include file types, task verbs, problem descriptions, synonyms.

---

Quality Signals

Good Signs

• Frontmatter reads like "when to use" guide, not feature list
• First 10 lines provide immediate actionable guidance
• Expert reading it would nod and say "yes, that's how I think"
• Explicit constraints on what it does NOT handle
• Examples show judgment calls, not just syntax
• Has named patterns with insights, not just steps

Warning Signs

• More than 50% content is reference tables or field definitions
• No mention of tradeoffs or "when NOT to use"
• Generic language that could apply to any domain
• Activation keywords are all nouns, no verbs or problem descriptions
• Body exceeds 600 lines (probably doing too much)
• Second-person voice ("you should...")

---

Validation Checklist

Before outputting, verify against Core Truths:

Frontmatter (Most Critical)

• Has YAML frontmatter with name and description?
• Name is clear and searchable (not abbreviation)?
• Description includes trigger keywords?
• Description includes file types if applicable?
• Description includes task verbs (creating, editing, etc.)?
• Description includes synonyms users might use?

Expertise Transfer

• Has named patterns with insights, not just steps?
• Transfers HOW to think, not just WHAT to do?
• Would an expert recognize their thinking here?

Flow

• Helps produce output, not create busywork?
• No unnecessary intermediate steps?
• Actionable immediately?

Focus

• Every section earns its place?
• No bloat?
• Ruthlessly constrained to what matters?

---

Common Workflows

Create Agent

1. Create .claude/agents/{name}.md
2. Write YAML frontmatter (name, description, tools, model)
3. Write system prompt (<800 lines)
4. Use Skill("prompt-architect") to improve prompt
5. Test with Task tool
6. Optimize based on performance

Create Skill

1. Create .claude/skills/{name}/SKILL.md
2. Write YAML frontmatter with WHAT + WHEN description
3. Write content with patterns, not procedures
4. Use Skill("prompt-architect") 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-architect") to improve prompts
4. Remove second-person voice
5. Use code blocks over prose
6. Add XML structure
7. Test and verify improvements

---

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

---

Best Practices

Anthropic Guidelines

✅ 800-line rule: Keep SKILL.md and agent prompts under 800 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-Pattern Summary

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

---

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: ~500 | Progressive Disclosure: ✅