Extend Agent

<essential_principles>

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:

</​essential_principles>

<intake> What would you like to create?

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. </​intake>

<routing> | Choice | Instructions | |--------|-------------| | 1, "skill", "rule", "mdc" | Read `workflows/​create-simple-skill.md` | | 2, "command", "slash" | See `<create_command>` below | | 3, "hook", "automation" | See `<create_hook>` below | | 4, "subagent", "agent" | Read `workflows/​create-subagent.md` | </​routing>

<create_command>

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

</​create_command>

<create_hook>

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.

</​create_hook>

<create_skill_and_subagent_notes>

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

</​create_skill_and_subagent_notes>

<reference_index>

• references/​skill-structure.md — Complete skill patterns and XML tags
• references/​cursor-format.md — Cursor .mdc format in depth
• references/​core-principles.md — Prompting principles for all extension types </​reference_index>

<workflows_index>

<success_criteria>

• Valid YAML frontmatter for the target platform
• XML-structured body (no markdown headings in body)
• Description specific enough to trigger at the right time
• Installed in the correct location for the platform
• Tested with a representative user request </​success_criteria>