agents-analyze

# /agents:analyze Analyze the plugin collection to identify where sub-agents would improve workflows by isolating verbose output, enforcing constraints, or specializing behavior. ## When to Use This Skill | Use this skill when... | Use a sibling skill instead when... | |---|---| | Auditing the whole plugin collection for sub-agent opportunities (verbose-output skills, model mismatches, tool over-permissions) | Auditing a single agent's frontmatter, tool list, and prompt completeness — use `agent-patterns-plugin:meta-audit` | | Mapping delegation gaps and producing a list of proposed new agents | Authoring the new agent file from that proposal — use `agent-patterns-plugin:custom-agent-definitions` | | Confirming every agent runs on Opus (the always-Opus standard) | Configuring an agent's hooks, permissions, or settings.json wiring — use `hooks-plugin:hooks-configuration` | | Focusing the analysis on a single plugin's skills (`--focus <plugin>`) | Coordinating multiple agents at runtime — use `agent-patterns-plugin:agent-teams` or `parallel-agent-dispatch` | ## Agentic Optimizations | Context | Command | |---------|---------| | List all plugins | `find . -maxdepth 1 -type d -name '*-plugin'` | | Count skills per plugin | `find <plugin>/skills -name 'SKILL.md' -o -name 'skill.md' \| wc -l` | | List existing agents | `find agents-plugin/agents -maxdepth 1 -name '*.md'` | | Check agent model field | `grep -r '^model:' agents-plugin/agents/` | | Check agent allowed-tools | `grep -r '^allowed-tools:' agents-plugin/agents/` | | Skill tool permissions | `grep -r '^allowed-tools:' */skills/*/SKILL.md` | ## Context - Plugin directories: !`find . -maxdepth 1 -type d -name '*-plugin'` - Existing agents: !`find . -path '*/agents-plugin/agents/*' -maxdepth 3 -name '*.md'` - Skills: !`find . -path '*/skills/*/skill.md'` - Skills (user-invocable): !`find . -path '*/skills/*/SKILL.md' -not -path './agents-plugin/*'` ## Parameters - `$1`: Optional `--focus <plugin-name>` to analyze a single plugin in depth ## Your Task Perform a systematic analysis of the plugin collection to identify sub-agent opportunities. ### Step 1: Inventory Current State Scan the repository to build an inventory: 1. **List all plugins** with their skill/command counts 2. **Read existing agents** in `agents-plugin/agents/` to understand current coverage 3. **If `--focus` is provided**, restrict analysis to that plugin only ### Step 2: Identify Sub-Agent Opportunities For each plugin (or focused plugin), evaluate skills and commands against these criteria: #### Context Isolation (Primary Value) Operations that produce verbose output benefiting from isolation: | Indicator | Examples | |-----------|----------| | Build tools | docker build, cargo build, webpack, tsc | | Infrastructure ops | terraform plan/apply, kubectl describe | | Test runners | Full test suite output, coverage reports | | Profiling tools | Flame graphs, benchmark results | | Security scanners | Vulnerability reports, audit output | | Log analysis | Application logs, system logs | | Package managers | Dependency trees, audit results | #### Constraint Enforcement Operations that should be limited to specific tools: | Constraint | Rationale | |------------|-----------| | Read-only analysis | Security audit, code review - no writes | | No network | Pure code analysis tasks | | Limited bash | Tasks that shouldn't execute arbitrary commands | #### Model: Always Opus Every plugin agent runs on `model: opus`. A subagent's output re-enters the main loop as a tool result, so a weaker delegate quietly degrades everything downstream — and Opus-low beats Sonnet-high on both quality and tokens. So **`effort` (the agent's `effort:` frontmatter, falling back to the session effort), not `model`, is the cost lever**: a mechanical agent stays on Opus and dials `effort` down rather than downgrading the model. | Audit finding | Recommendation | |---------------|----------------| | Agent file declares `model: opus` | OK — no change | | Agent file declares `sonnet` / `haiku` / any non-opus | Flag it — recommend `model: opus`, and note that mechanical agents tune `effort` down instead | | Agent file omits `model:` | Flag it — agents require an explicit `model: opus` | | Agent file's Scope describes mechanical/high-volume work but sets no `effort:` | Recommend `effort: low` (advisory — not lint-enforced) | The sole sanctioned non-Opus subagent is the `agent-patterns-plugin:cold-read-gate` haiku reader, which is a **skill-inline** `Agent(model: haiku)` dispatch (the measurement instrument), **not** an agent file — so no `*/agents/*.md` is exempt. The `scripts/check-agent-model.sh` lint enforces this; see `.claude/rules/agent-development.md` § "Model Selection for Agents". ### Step 3: Gap Analysis Compare identified opportunities against existing agents: 1. **Missing agents**: Skills that have no corresponding agent 2. **Non-opus agents**: Any agent file not on `model: opus` (always-Opus standard) 3. **Tool over-permissions**: Agents with tools they don't need 4. **Consolidation opportunities**: Multiple agents that could be merged 5. **Delegation mapping**: Check if `/delegate` references agents that don't exist ### Step 4: Produce Recommendations For each recommended new agent, specify: ```markdown ### Proposed: <agent-name> - **Model**: opus (always; tune `effort` down for mechanical agents, never the model) - **Covers plugins**: <list> - **Context value**: <what verbose output it isolates> - **Tools**: <minimal set> - **Constraint**: <read-only, no-network, etc.> - **Priority**: HIGH | MEDIUM | LOW - **Rationale**: <why this is better than inline execution> ``` For model/tool corrections to existing agents: ```markdown ### Fix: <agent-name> - **Current model**: <non-opus> → **Recommended**: opus (then dial `effort` down if mechanical) - **Reason**: <why the change improves things — e.g. restores the always-Opus standard> ``` ### Step 5: Implementation Check If new agents are recommended, check: - [ ] Agent name doesn't conflict with existing - [ ] Agent fills a gap referenced by `/delegate` command - [ ] Model is `opus` (always-Opus standard; `effort` is the cost lever, not the model) - [ ] Tool set is minimal (principle of least privilege) - [ ] Agent has clear "does / does NOT do" boundaries ## Output Format ```markdown ## Sub-Agent Analysis Report **Scope**: [All plugins | focused plugin name] **Date**: [today] **Plugins analyzed**: N **Existing agents**: N **Skills without agent coverage**: N ### Current Coverage Map | Domain | Agent | Skills Covered | Gaps | |--------|-------|----------------|------| | ... | ... | ... | ... | ### Recommended New Agents [Proposals from Step 4] ### Recommended Fixes [Model/tool corrections from Step 4] ### Delegation Mapping Updates [Any updates needed for /delegate command's agent reference table] ### Priority Summary | Priority | Count | Top Recommendation | |----------|-------|-------------------| | HIGH | N | ... | | MEDIUM | N | ... | | LOW | N | ... | ``` ## Post-Actions After presenting the analysis: 1. Ask the user if they want to implement any of the recommendations 2. If yes, create the agent files following the existing patterns in `agents-plugin/agents/` 3. Update `agents-plugin/README.md` with new agents 4. Update `/delegate` command's agent reference table if needed