Agent files for skill-only components waste tokens and error on invocation

[terry-li-hm]

Problem

Several components ship with agent .md files in agents/ but are actually skills, not agents. This causes two issues:

1. Token waste: Agent descriptions are eagerly loaded into the Task tool definition on every API call (~100-200 tokens each). Skills are lazy-loaded (name + 1-line description only). Having skill-only components in agents/ means their full descriptions load every session whether used or not.

2. Runtime error: Invoking these via the Task tool produces Unknown Agent Type because they lack proper agent persona configurations. Users must know to use the Skill tool instead.

Affected components

• workflow/agent-browser.md
• workflow/brainstorming.md
• docs/compound-docs.md
• design/frontend-design.md
• design/gemini-imagegen.md
• workflow/skill-architect.md

Expected behaviour

These should either:

• Not have agent files — if they're skills-only, remove the .md from agents/ so they don't load into the Task tool description
• Work as agents — if they're meant to be invocable via Task, add the necessary agent persona/configuration

Workaround

Deleting the files from the plugin cache manually (automated via a shell script on startup). They reappear on plugin updates.

Context

Related to #139 (selective agent loading). This is a narrower issue — these specific files shouldn't exist as agents at all, regardless of whether selective loading is implemented.

[terry-li-hm]

Note: I've closed my earlier PRs #129 and #149 which took the opposite approach (adding agent personas). After living with a trim-based workaround and seeing the token impact, I believe removal is the right path.

One thing to flag: some workflow commands (e.g. /workflows:compound) currently try to spawn these as agents via the Task tool. If agent files are removed, those workflow commands would need updating to invoke the corresponding skills via the Skill tool instead. Happy to help with that PR if useful.

[Yash-xoxo]

Hey @terry-li-hm,

This is a really clean catch - totally agree that removal is the better approach over adding personas.

The Fix

Your analysis is spot on:

• Token waste: ~100-200 tokens per fake agent × every session = significant overhead
• Runtime errors: Confusing UX when Task tool fails on these
• Solution: Delete the agent files, update workflows to use Skill tool instead

Quick Implementation

For the workflow commands that reference these:

// Before (broken)
await taskTool.invoke({ agentName: "agent-browser" });

// After (working)
await skillTool.invoke({ skillName: "agent-browser" });

Should be a straightforward find-replace in the workflow files.

Suggested PR Scope

1. Remove the 6 agent .md files you listed
2. Update any /workflows:* commands that reference them
3. Add a test to catch future skill-as-agent mixups (check that all files in agents/ have proper persona config)

Happy to review the PR when you put it up!

[hvhvuvkb]

Guy y

[mvanhorn]

PR up: #234

After auditing all 29 agent files against the 20 existing skills, every-style-editor is the only clear duplicate (agent file + skill directory with same name and overlapping purpose). The other near-matches (ankane-readme-writer vs andrew-kane-gem-writer, dhh-rails-reviewer vs dhh-rails-style) serve different scopes so I left them alone.

Removed the agent file, updated counts in both plugin.json files and README. Saves ~100-200 tokens/session from the Task tool definition.