extend-agent

<essential_principles>

Types of Agent Extensions

| Type | Claude Code | Cursor | Purpose | |------|-------------|--------|---------| | Skill | ~/.claude/skills/<name>/SKILL.md | .cursor/rules/<name>.mdc | Domain knowledge + workflows | | Command | ~/.claude/commands/<name>.md | .cursor/rules/<name>.mdc (on-demand rule) | Quick action shortcuts | | Hook | .claude/hooks.json | alwaysApply: true rules | Event-driven automation | | Subagent | ~/.claude/agents/<name>.md | .cursor/agents/<name>.md | Specialist AI instances |

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: | Field | Claude Code | Cursor | |-------|-------------|--------| | name | ✅ Required | ✅ Required | | description | ✅ Required | ✅ Required | | model | sonnet/opus/haiku/inherit | fast/inherit/<model-id> | | tools | ✅ Restricts tool access | Ignored | | readonly | Ignored | ✅ Read-only mode | | is_background | Ignored | ✅ Background execution |

</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: | Event | When | Blocking? | |-------|------|-----------| | PreToolUse | Before tool runs | Yes | | PostToolUse | After tool runs | No | | UserPromptSubmit | User submits prompt | Yes | | Stop | Agent tries to stop | Yes | | SubagentStop | Subagent tries to stop | Yes | | SessionStart | Session begins | No | | SessionEnd | Session ends | No | | PreCompact | Before context compaction | Yes | | Notification | Claude needs input | No |

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> | Workflow | Purpose | |----------|---------| | workflows/create-simple-skill.md | Build a single-file skill or a complex router skill with subdirectories | | workflows/convert-to-cursor.md | Transform a SKILL.md to Cursor .mdc format | | workflows/create-subagent.md | Build a specialist agent for Claude Code or Cursor | </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>