Extend Agent

MANDATORY first step on every invocation. Claude Code's extension knobs (skill frontmatter fields, subagent options, hook events, the model lineup, slash-command behavior) change frequently. The tables in this SKILL.md are a SNAPSHOT — they go stale. Verify the LIVE docs FIRST, then design.

Step 1 — Fetch the current docs

Use WebFetch (preferred over delegating to web-research subagent, because WebFetch is often restricted in subagent contexts — the parent loop usually has it). Always go to the live URL first; if the doc has moved (HTTP 301), follow the redirect to the new canonical host.

Verified canonical hosts (as of late 2026):

1. https://code.claude.com/docs/en/skills — Skill frontmatter, invocation control, subagent execution, dynamic context injection
2. https://code.claude.com/docs/en/sub-agents — Subagent frontmatter, model defaults, invocation
3. https://code.claude.com/docs/en/hooks — Hook events (30+), handler types, blocking output JSON
4. https://code.claude.com/docs/en/slash-commands — Custom commands (note: commands are now merged into skills)
5. https://code.claude.com/docs/en/agent-teams and /agent-view — Cross-session orchestration
6. https://code.claude.com/docs/en/context-window — Compaction + token-cost visualization
7. https://docs.anthropic.com/en/docs/claude-code/* — fallback URL pattern; redirects to code.claude.com since the 2026 doc migration.
8. The repo's own ~/.claude/skills/extend-agent/SKILL.md snapshot — fallback only when the live docs are unreachable.

If the WebFetch returns "redirect detected," follow the redirect URL once. If both 404, the doc has moved — search https://www.anthropic.com/news for the latest Claude Code post.

Step 2 — Verify the specific knobs your new extension will use

The fields you'd use change quarterly. Always re-confirm:

• Skill frontmatter fields (name, description, disable-model-invocation, user-invocable, context: fork, allowed-tools, plus any new fields). Pay attention to context-cost rules (which fields load description: into context, which don't).
• Subagent frontmatter (model, tools, memory, skills, maxTurns, isolation). Default model when none is specified.
• Model lineup. What models can be set as model: ...? The lineup churns most often. Check anthropic.com/news for the latest.
• Hook events — verify each event you'll subscribe to is still listed; the event roster has grown to ~30. Verify payload shape for the event you use.
• Hook handler types — command / http / mcp_tool / prompt / agent (experimental) — verify the type you want exists.
• Recommended size caps — current docs suggest SKILL.md description: ≤200 chars; progressive disclosure to references/ for detail.

Step 3 — Surface what's NEW since the local snapshot

After verifying knobs the new extension needs, do a second pass: scan the live doc for capabilities NOT YET reflected in this SKILL.md, related skills, or the user's ~/.claude/agents/ / ~/.claude/skills/ configs. Report any "new since snapshot" features as recommendations the user might want to adopt — even if not directly relevant to the current extension. Examples to look for each run:

• New hook events (the PostToolBatch, TaskCreated, PostCompact series didn't exist in the snapshot).
• New handler types (prompt, agent hook types — verify which experimental flags are needed).
• New invocation modes (subagent skills, dynamic context injection, agent teams, background agents).
• New frontmatter fields (e.g., metadata.allowed-tools arrived in the AgentSkills standard).
• Model-lineup changes (a new haiku tier, opus pricing changes).
• Doc reorganization (URL migrations, merged docs).

For each gap, report: feature name, doc URL, one-line value-prop, and whether it's worth adopting now or filing as a follow-up. The user decides. The skill author surfaces.

Step 4 — If a live doc contradicts this SKILL.md, fix the SKILL.md AFTER the user's request lands

Treat the live doc as authoritative. The snapshot is hand-off context, not source of truth. Open a follow-up note (memory or a comment in the SKILL.md) so the next /strategic-compact run catches the drift.

Token budget for the freshness check

3-4 WebFetch calls (~10-30k tokens depending on doc size — they're large pages). It pays for itself by preventing a session-long detour fixing a wrong field name or recommending a removed feature.

• Skill bodies must be project-agnostic. A skill body loads into every future session regardless of repo. Before writing a new bullet, ask "would this make sense in a Go service / Rust CLI / TypeScript Next.js app?" If no, rewrite. No service names, file paths, ticket prefixes, or framework class names in the rule body — those belong in the "Why:" line or in a clearly-marked example block. See ~/.claude/skills/strategic-compact/references/promotion-quality-gates.md §Gate 1 for the full 5-criterion checklist.

Types of Agent Extensions

Skill Frontmatter — All Fields (Claude Code)

---
name: skill-name                    # Required: unique identifier
description: What and when to use   # Required: Claude reads this to decide invocation
disable-model-invocation: true      # Optional: only user can invoke via /name (zero context cost)
user-invocable: false               # Optional: hides from / menu, Claude auto-invokes only
context: fork                       # Optional: runs in isolated subagent context
agent: general-purpose              # Optional: which agent type for forked context
allowed-tools: Read, Grep, Glob     # Optional: restrict available tools
---

Context cost rules:

• disable-model-invocation: true → description NOT in context (zero cost, user-only)
• user-invocable: false → description IN context (Claude auto-invokes)
• Default → description IN context + appears in / menu

Skill Frontmatter — Cursor (.mdc)

---
description: What it does and when it applies
globs: ["**/*.py"]      # File patterns (empty = on-demand)
alwaysApply: false       # true = always in context
---

Skill Frontmatter — Copilot (.instructions.md)

---
applyTo: "**/*.py,**/*.ts"          # Glob patterns for file scope
excludeAgent: "code-review"         # Optional: exclude from specific agent
---

Subagent Frontmatter — All Fields (Claude Code)

---
name: agent-name                    # Required
description: When to use            # Required
tools: Read, Grep, Glob, Bash      # Optional: restrict tool access
model: sonnet                       # Optional: sonnet/opus/haiku
memory: user                        # Optional: persistent cross-session learning
skills:                             # Optional: preload skills at startup
  - testing
  - security
maxTurns: 10                        # Optional: limit agent turns
isolation: worktree                 # Optional: isolated git worktree
---

Command Frontmatter — Gemini CLI (.toml)

description = "What this command does"
prompt = "The prompt to send when invoked"

Rule Path-Scoping (Cross-Platform)

1. Skill — Domain expertise module (SKILL.md for Claude / .mdc for Cursor)
2. Command — Quick action shortcut
3. Hook — Event-driven automation
4. Subagent — Specialist AI instance

Wait for response before proceeding.

Creating a Command

Claude Code (.claude/commands/<name>.md):

---
description: What this command does (appears in /help)
argument-hint: [optional-arg]
allowed-tools: Bash(git add:*), Bash(git commit:*)  # Optional
# Note: allowed-tools matches per-pipeline-stage. `Bash(grep:*)` does NOT
# cover `grep ... | head` — the `head` tail is classified separately.
# Enumerate every stage or wrap the pipeline in a script. See
# `~/.claude/skills/strategic-compact/references/claude-code-best-practices.md`
# §Settings keys for full rationale.
---

<objective>
What to accomplish. Use $ARGUMENTS if taking user input.
</objective>

<context>
Current status: !`git status`
Relevant file: @package.json
</context>

<process>
1. Step one
2. Step two
3. Verify
</process>

<success_criteria>
Definition of done.
</success_criteria>

Install: cp command.md ~/.claude/commands/ Invoke: /command-name [args]

Cursor (.cursor/rules/<name>.mdc with alwaysApply: false):

---
description: When asked to [action], follow this workflow
globs: []
alwaysApply: false
---

<process>
1. Step one
2. Step two
</process>

Key difference: Cursor has no / invocation — the rule activates when the user describes the action.

Arguments:

• $ARGUMENTS — all args as one string: /fix-issue 123 → $ARGUMENTS = "123"
• $1, $2, $3 — positional: /review-pr 456 high → $1=456, $2=high
• No args — operates on current context (git status, open file, etc.)

Creating a Hook (Claude Code)

Hooks are event-driven automation in .claude/hooks.json.

Hook events:

Command hook template:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Blocking hook output (stdout from your script):

{"decision": "block", "reason": "Why this was blocked"}

Prompt hook template (LLM evaluates instead of a script):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "prompt", "prompt": "Is this command safe: $ARGUMENTS\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"...\"}"}]
    }]
  }
}

Use prompt type when decision requires reasoning; command type for deterministic checks. Test hooks with: claude --debug

Matchers:

"Bash"           → Exact tool name
"Write|Edit"     → Multiple tools (regex OR)
"mcp__.*"        → All MCP tools
(omit matcher)   → Fires for all tools

Cursor equivalent: No native hook system. Use alwaysApply: true rules:

---
alwaysApply: true
---

NEVER run: rm -rf, git push --force, DROP TABLE.
ALWAYS check git status before committing.

See skills/security/hooks/ for working hook script examples.

Skill design patterns:

• Simple (4-10 lines of instructions) → single SKILL.md file
• Complex (multi-step workflows, multiple domains) → router pattern with workflows/, references/, templates/ subdirs
• Keep SKILL.md under 500 lines — move detailed content to references/ subdirectory
• Description is critical — Claude uses it to decide when to invoke. Be specific about triggers.
• Use progressive disclosure: lean SKILL.md routes to detailed workflow/reference files
• Dynamic-context injection (!`cmd`) runs under the invocation's working-directory sandbox. Direct reads of files outside the current project (grep ~/.claude/settings.json, cat ~/.claude/some-file) are BLOCKED at every invocation — the sandbox rejects the read before the skill body loads, breaking the skill in every session. Safe: ls ~/.claude/<subdir>/ (directory listing, no file content), date, git status. Unsafe: any grep/cat/find targeting a specific file under $HOME outside the working project. Fix: move the read into a script under ~/.claude/skills/<name>/scripts/* and pre-approve the scripts dir via allowed-tools: Bash(bash ~/.claude/skills/<name>/scripts/*). That single allow-tool grants the script's own read access without triggering the grep sandbox.

Subagent execution model — critical constraints:

• Subagents cannot use AskUserQuestion or wait for user input
• Run isolated — user sees only final output, not intermediate steps
• Invoked automatically (Claude matches description field) or explicitly via the Task tool
• Project subagents (.claude/agents/) override user subagents (~/.claude/agents/) on name conflict
• memory: user enables persistent learning at ~/.claude/agent-memory/<name>/
• skills: preloading injects full skill content at startup (no need for inline "read skills/X/SKILL.md")
• For multi-stage orchestration: use the planning skill + Task tool, not a single subagent

When to use subagents proactively:

Always launch independent agents in parallel when possible.

1. Enumerate ALL candidates first — never short-circuit on the first match.
2. Sort the candidates by a clear priority signal (usage count, severity, recency).
3. Present each as a numbered list [i/N] with rationale and proposed action.
4. Ask for per-candidate confirmation, with skip-skill / apply all shortcuts for batch decisions.

Anti-pattern: returning one match with "I found this" — the user can't see what you skipped, can't redirect priority, and trusts a partial scan as complete.

Repeat-use as a smell: if the user invokes the same skill 3+ times within one session/task, the skill body is probably under-specified. Make sure new scanner skills produce a complete pass per invocation; one call should fully discharge the user's intent.