extend-agent

name	extend-agent
description	Create new skills, commands, hooks, or subagents for your AI agent. Use when you need to add new capabilities to Claude Code or Cursor — any type of extension.

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

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.

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

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