Add agent metadata to built-in agent prompt frontmatter

Extracts runtime metadata from Claude Code's compiled source and
includes it in the frontmatter of each built-in agent's prompt file:
- agentType, model, tools, disallowedTools, whenToUse
- permissionMode, color, criticalSystemReminder where applicable

Closes Piebald-AI/claude-code-system-prompts#12

README.md

@@ -205,7 +205,7 @@ Text for large system reminders.
 - [System Reminder: Output style active](./system-prompts/system-reminder-output-style-active.md) (**32** tks) - Notification that an output style is active.
 - [System Reminder: Output token limit exceeded](./system-prompts/system-reminder-output-token-limit-exceeded.md) (**35** tks) - Warning when response exceeds output token limit.
 - [System Reminder: Plan file reference](./system-prompts/system-reminder-plan-file-reference.md) (**62** tks) - Reference to an existing plan file.
-- [System Reminder: Plan mode is active (5-phase)](./system-prompts/system-reminder-plan-mode-is-active-5-phase.md) (**1500** tks) - Enhanced plan mode system reminder with parallel exploration and multi-agent planning.
+- [System Reminder: Plan mode is active (5-phase)](./system-prompts/system-reminder-plan-mode-is-active-5-phase.md) (**1506** tks) - Enhanced plan mode system reminder with parallel exploration and multi-agent planning.
 - [System Reminder: Plan mode is active (iterative)](./system-prompts/system-reminder-plan-mode-is-active-iterative.md) (**797** tks) - Iterative plan mode system reminder for main agent with user interviewing workflow.
 - [System Reminder: Plan mode is active (subagent)](./system-prompts/system-reminder-plan-mode-is-active-subagent.md) (**310** tks) - Simplified plan mode system reminder for sub agents.
 - [System Reminder: Plan mode re-entry](./system-prompts/system-reminder-plan-mode-re-entry.md) (**236** tks) - System reminder sent when the user enters Plan mode after having previously exited it either via shift+tab or by approving Claude's plan..

system-prompts/agent-prompt-claude-guide-agent.md

@@ -10,6 +10,23 @@ variables:
   - READ_TOOL_NAME
   - GLOB_TOOL_NAME
   - GREP_TOOL_NAME
+agentMetadata:
+  agentType: 'claude-code-guide'
+  model: 'haiku'
+  permissionMode: 'dontAsk'
+  tools:
+    - Glob
+    - Grep
+    - Read
+    - WebFetch
+    - WebSearch
+  whenToUse: >
+    Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...")
+    about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE
+    integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API
+    (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning
+    a new agent, check if there is already a running or recently completed claude-code-guide agent that
+    you can resume using the "resume" parameter.
 -->
 You are the Claude guide agent. Your primary responsibility is helping users understand and use Claude Code, the Claude Agent SDK, and the Claude API (formerly the Anthropic API) effectively.
 

system-prompts/agent-prompt-command-execution-specialist.md

@@ -2,6 +2,14 @@
 name: 'Agent Prompt: Command execution specialist'
 description: System prompt for command execution agent focusing on bash commands
 ccVersion: 2.0.77
+agentMetadata:
+  agentType: 'Bash'
+  model: 'inherit'
+  tools:
+    - Bash
+  whenToUse: >
+    Command execution specialist for running bash commands. Use this for git operations, command
+    execution, and other terminal tasks.
 -->
 You are a command execution specialist for Claude Code. Your role is to execute bash commands efficiently and safely.
 

system-prompts/agent-prompt-explore.md

@@ -7,6 +7,23 @@ variables:
   - GREP_TOOL_NAME
   - READ_TOOL_NAME
   - BASH_TOOL_NAME
+agentMetadata:
+  agentType: 'Explore'
+  model: 'haiku'
+  whenToUseDynamic: true
+  disallowedTools:
+    - Task
+    - ExitPlanMode
+    - Edit
+    - Write
+    - NotebookEdit
+  whenToUse: >
+    Fast agent specialized for exploring codebases. Use this when you need to quickly find files by
+    patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer
+    questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify
+    the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or
+    "very thorough" for comprehensive analysis across multiple locations and naming conventions.
+  criticalSystemReminder: 'CRITICAL: This is a READ-ONLY task. You CANNOT edit, write, or create files.'
 -->
 You are a file search specialist for Claude Code, Anthropic's official CLI for Claude. You excel at thoroughly navigating and exploring codebases.
 

system-prompts/agent-prompt-plan-mode-enhanced.md

@@ -7,6 +7,20 @@ variables:
   - GREP_TOOL_NAME
   - READ_TOOL_NAME
   - BASH_TOOL_NAME
+agentMetadata:
+  agentType: 'Plan'
+  model: 'inherit'
+  disallowedTools:
+    - Task
+    - ExitPlanMode
+    - Edit
+    - Write
+    - NotebookEdit
+  whenToUse: >
+    Software architect agent for designing implementation plans. Use this when you need to plan the
+    implementation strategy for a task. Returns step-by-step plans, identifies critical files, and
+    considers architectural trade-offs.
+  criticalSystemReminder: 'CRITICAL: This is a READ-ONLY task. You CANNOT edit, write, or create files.'
 -->
 You are a software architect and planning specialist for Claude Code. Your role is to explore the codebase and design implementation plans.
 

system-prompts/agent-prompt-status-line-setup.md

@@ -2,6 +2,14 @@
 name: 'Agent Prompt: Status line setup'
 description: System prompt for the statusline-setup agent that configures status line display
 ccVersion: 2.1.47
+agentMetadata:
+  agentType: 'statusline-setup'
+  model: 'sonnet'
+  color: 'orange'
+  tools:
+    - Read
+    - Edit
+  whenToUse: 'Use this agent to configure the user''s Claude Code status line setting.'
 -->
 You are a status line setup agent for Claude Code. Your job is to create or update the statusLine command in the user's Claude Code settings.
 

system-prompts/agent-prompt-task-tool.md

@@ -2,6 +2,14 @@
 name: 'Agent Prompt: Task tool'
 description: System prompt given to the subagent spawned via the Task tool
 ccVersion: 2.0.14
+agentMetadata:
+  agentType: 'general-purpose'
+  tools:
+    - *
+  whenToUse: >
+    General-purpose agent for researching complex questions, searching for code, and executing
+    multi-step tasks. When you are searching for a keyword or file and are not confident that you will
+    find the right match in the first few tries use this agent to perform the search for you.
 -->
 You are an agent for Claude Code, Anthropic's official CLI for Claude. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
 

system-prompts/agent-prompt-update-magic-docs.md

@@ -2,6 +2,12 @@
 name: 'Agent Prompt: Update Magic Docs'
 description: Prompt for the magic-docs agent.
 ccVersion: 2.0.30
+agentMetadata:
+  agentType: 'magic-docs'
+  model: 'sonnet'
+  tools:
+    - Edit
+  whenToUse: 'Update Magic Docs'
 -->
 IMPORTANT: This message and these instructions are NOT part of the actual user conversation. Do NOT include any references to "documentation updates", "magic docs", or these update instructions in the document content.