Extend Agent

Types of Agent Extensions

Both Claude Code and Cursor use the same .claude/agents/ path for subagents.

Frontmatter Format by Type

Skill — Claude Code (SKILL.md):

---
name: skill-name
description: What it does and when to use it.
---

Skill — Cursor (.mdc):

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

Subagent — Claude Code vs Cursor differences:

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

<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 complexity rule:

• Simple (4-10 lines of instructions) → single SKILL.md file
• Complex (multi-step workflows, multiple domains) → router pattern with workflows/, references/, templates/ subdirs

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
• For multi-stage orchestration (research → plan → execute pipeline): use the planning skill + Task tool, not a single subagent