Which documentation needs improvement?
Skill documentation
Specific Location
plugins/plugin-dev/skills/agent-development/SKILL.md
What's unclear or missing?
During a comprehensive review of the plugin's subagents against official Claude Code documentation, two discrepancies were discovered that should be documented in the agent-development skill:
1. The color field is not in official documentation
The agent-development skill lists color as a required field with valid values: blue, cyan, green, yellow, magenta, red.
However, the official Claude Code documentation (sub-agents.md) does not mention the color field at all. The documented fields are:
name (required)description (required)tools (optional)model (optional)permissionMode (optional)skills (optional)
The color field appears to be a valid internal feature (agents work with it), but users following only official docs wouldn't know about it.
2. plugins-reference.md shows different agent structure
The official plugins-reference.md shows a different agent structure using capabilities field:
---
description: What this agent specializes in
capabilities: ["task1", "task2", "task3"]
---
This conflicts with sub-agents.md which shows tools, model, etc. This may confuse users referencing both documents.
Suggested Improvement
Add a note or section to the agent-development skill clarifying:
> **Note on Official Documentation:** The `color` field documented here is supported by Claude Code but not yet reflected in the official sub-agents.md documentation. The plugins-reference.md may show an older agent format; prefer the structure documented in this skill which aligns with sub-agents.md for standard fields plus the `color` field for UI identification.
This helps users understand which format to follow and that color is a valid but undocumented feature.
Type of issue
Additional Context
This was discovered during a comprehensive review of the 3 plugin subagents (agent-creator, plugin-validator, skill-reviewer) against:
- Official Claude Code sub-agents.md
- Official Claude Code plugins-reference.md
- agent-development skill best practices
All 3 agents use color and follow the skill's documented format, which works correctly. The issue is documentation clarity, not functionality.
Which documentation needs improvement?
Skill documentation
Specific Location
plugins/plugin-dev/skills/agent-development/SKILL.mdWhat's unclear or missing?
During a comprehensive review of the plugin's subagents against official Claude Code documentation, two discrepancies were discovered that should be documented in the agent-development skill:
1. The
colorfield is not in official documentationThe agent-development skill lists
coloras a required field with valid values:blue,cyan,green,yellow,magenta,red.However, the official Claude Code documentation (sub-agents.md) does not mention the
colorfield at all. The documented fields are:name(required)description(required)tools(optional)model(optional)permissionMode(optional)skills(optional)The
colorfield appears to be a valid internal feature (agents work with it), but users following only official docs wouldn't know about it.2. plugins-reference.md shows different agent structure
The official plugins-reference.md shows a different agent structure using
capabilitiesfield:This conflicts with sub-agents.md which shows
tools,model, etc. This may confuse users referencing both documents.Suggested Improvement
Add a note or section to the agent-development skill clarifying:
> **Note on Official Documentation:** The `color` field documented here is supported by Claude Code but not yet reflected in the official sub-agents.md documentation. The plugins-reference.md may show an older agent format; prefer the structure documented in this skill which aligns with sub-agents.md for standard fields plus the `color` field for UI identification.This helps users understand which format to follow and that
coloris a valid but undocumented feature.Type of issue
Additional Context
This was discovered during a comprehensive review of the 3 plugin subagents (agent-creator, plugin-validator, skill-reviewer) against:
All 3 agents use
colorand follow the skill's documented format, which works correctly. The issue is documentation clarity, not functionality.