Imported from majiayu000/claude-skill-registry (skills/data/claude-extensibility/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry --skill claude-extensibility. Copyright stays with the author.

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:

Decision Heuristics

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

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

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
# 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

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, <800 lines)
├── references/ (optional - detailed docs)
├── scripts/ (optional - utilities)
└── templates/ (optional - templates)

Core Sections (Include What's Needed)

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

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