build-extension-builder

What this skill does

# Extension Builder

Build cognitive extensions that enable effective collaboration, where both human and Claude grow through the partnership.

> **Requires:** `plugin-dev@claude-plugins-official` and `agent-sdk-dev@claude-plugins-official` for authoritative schemas and templates. This skill adds quality methodology on top.

## Why This Matters

Extensions become part of how users think and work. The difference between helpful and harmful comes down to how it's built.

**Good extensions:**
- Show reasoning (user learns WHY, not just WHAT)
- Provide control (user shapes direction)
- Fill gaps (what Claude doesn't already know)
- Compound value (each enhancement makes the next easier)

**Bad extensions:**
- Hide reasoning (black box)
- Replace thinking (user just consumes output)
- Repeat basics (bloat without insight)
- Create dependency (user less capable without it)

---

## Design Principles

Build these into every extension.

### Transparency (β = 0.415 effect)

Make reasoning visible so users can verify and learn.

| Pattern | Implementation |
|---------|----------------|
| **Show the claim** | What you're recommending |
| **Show the why** | Reasoning behind it |
| **Show alternatives** | What you considered and rejected |
| **Show the source** | Where this comes from |
| **Show uncertainty** | Confidence level (1-10) |

**Example in a skill:**
```markdown
### Error Handling

Use `thiserror` for library errors, `anyhow` for applications.

**Why:** thiserror derives std::error::Error with zero runtime cost.
anyhow provides context chaining but hides the error type.

**Source:** Rust API Guidelines, tokio/reqwest usage patterns.
```

### Control (β = 0.507 effect, strongest)

Give users agency over direction.

| Pattern | Implementation |
|---------|----------------|
| **Decision frameworks** | Teach HOW to decide, not WHAT to do |
| **Tradeoff tables** | Options with tradeoffs, user chooses |
| **Approval gates** | Stop before irreversible actions |
| **Checkpoints** | Verifiable steps in complex workflows |

**Example decision framework:**
```markdown
### Which Error Type?

| Context | Use | Why |
|---------|-----|-----|
| Library (public API) | thiserror | Callers need to match on error types |
| Application (internal) | anyhow | Context matters more than type |
| Both (lib + binary) | thiserror + anyhow | Export typed errors, use anyhow internally |
```

### Pit of Success

Make the right thing the only obvious path.

Structure your extension so correct behavior is natural:
- Default to safe options
- Make dangerous operations require extra steps
- Use constraints, not documentation

### Mistake-Proofing (Poka-Yoke)

Catch errors where they originate.

- Validate assumptions early
- Surface uncertainty at decision points
- Include "watch out for" sections

### Non-Conformist by Design

Extensions that offer templates converge. Extensions that teach process diverge.

| Selective (Converges) | Generative (Diverges) |
|-----------------------|-----------------------|
| "Pick style A, B, or C" | "What approach fits your context?" |
| Templates to apply | Framework to discover |
| Menu of options | Dialogue to articulate |
| Everyone gets similar output | Each user develops unique voice |

**The homogenization trap:** When AI tools offer categorical choices, everyone picks from the same menu. Output converges toward sameness.

**The generative alternative:** Help users discover and crystallize their *own* approach. The skill teaches the process, not the product.

| Wrong | Right |
|-------|-------|
| Skill prescribes THE answer | Skill helps user find THEIR answer |
| Template library | Discovery framework |
| "Use this pattern" | "Here's how to find the right pattern" |

**Crystallization pattern:**
```
skill helps user discover → user articulates their approach →
approach becomes local skill → collaboration uses that vocabulary
```

The published skill is the fishing rod. Each user catches their own fish.

### Observability

Make extension behavior visible and controllable by default.

#### OTel Instrumentation

Instrument extensions so behavior is measurable and debuggable.

| Extension Type | OTel | Key Spans |
|----------------|------|-----------|
| **Agents** | Required | `agent_run`, `llm_call`, `tool_call` |
| **MCP Servers** | Required | `mcp_server`, `mcp_call` |
| **SDK Apps** | Required | `session`, `turn`, `tool_call` |
| **Skills** | Recommended | `skill_check`, `skill_match`, `skill_load` |
| **Hooks** | Recommended | `hook_trigger`, `hook_handler` |
| **Commands** | Recommended | `command`, `command_execute` |

**Minimum attributes to capture:**
- `success` (bool), `duration_ms` (int), `error` (string if failed)
- For LLM calls: `input_tokens`, `output_tokens`, `model`
- For tool calls: `tool_name`, `tool_args` (truncated)

**Local-first tracing:**
```python
# Phoenix (local, no cloud required)
import phoenix as px
px.launch_app()  # localhost:6006

from opentelemetry import trace
tracer = trace.get_tracer("my-extension")
```

See [observability.md](references/observability.md) for complete instrumentation patterns.

#### Hook Behavior

Hooks fall into two categories with different design patterns:

| Hook Type | Purpose | Pattern |
|-----------|---------|---------|
| **Validation** | Review actions before/after | Suggest, don't block |
| **Action-triggering** | Detect patterns, cause response | Directive, cause action |

**Validation hooks** (PreToolUse, most PostToolUse):

Suggest alternatives, let user proceed with original choice.

```bash
# Good: Shows alternative, lets user proceed
{"decision": "allow", "message": "Consider using rg instead of grep (faster). Proceeding with grep."}

# Bad: Removes choice without escape
{"decision": "block", "message": "Use rg instead."}
```

**Action-triggering hooks** (pattern detection):

When detecting conditions that should trigger a response (debugging loops, user frustration, security concerns), use directive language that causes action.

```bash
# Good: Directive that causes action
{"decision": "allow", "message": "🐺 DEBUGGING LOOP DETECTED (3 consecutive failures). You MUST now: 1) Tell the user what's happening. 2) Spawn the appropriate agent to handle this systematically."}

# Bad: Mere suggestion that gets ignored
{"decision": "allow", "message": "Consider using Mr. Wolf for this problem."}
```

**Why the distinction matters:** Validation hooks preserve user agency over individual actions. Action-triggering hooks respond to emergent patterns where the whole point is to interrupt the current approach — suggesting doesn't accomplish that.

**Opt-out mechanism:**
Every hook-based extension must:
- Document how to disable
- Respect environment variables (e.g., `SKIP_HOOKS=1`)
- Never hard-block without escape hatch

**Reasoning traces:**
When hooks modify behavior, show:
- What triggered the hook
- What the hook recommends (or requires)
- Why (brief reasoning)
- For validation hooks: how to proceed with original if desired

---

## Five Extension Types

| type | purpose | what it extends |
|------|---------|-----------------|
| **skill** | knowledge + decision frameworks | what Claude knows |
| **hook** | event-triggered actions | session behavior |
| **agent** | specialized subagent | reasoning delegation |
| **command** | workflow shortcuts | repeatable procedures |
| **mcp** | external system integration | reach beyond Claude |

---

## Building a Skill

Skills are the most common extension. Follow Anthropic's patterns.

### Structure

```
skill-name/
├── SKILL.md           (required - < 500 lines)
├── references/        (detailed docs, load as needed)
├── scripts/           (executable code)
└── assets/            (templates, files for output)
```

### SKILL.md Anatomy

**Frontmatter** (required):
```yaml
---
name: skill-name
description: "What it does. Use when: specific triggers."
---
```

The description is the trigger. Claude reads this to decide when to load. Be specific abo