diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index 64dfd08..8744afa 100644
--- a/plugins/plugin-dev/skills/agent-development/SKILL.md
+++ b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -17,6 +17,8 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen
 - Model and color customization
 
 > **Important - Field Name Difference:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. Don't confuse these when switching between component types.
+>
+> **Note on Official Documentation:** The `color` field documented in this skill is supported by Claude Code and is generated by the built-in `/agents` command, but it is not yet reflected in the [official sub-agents documentation](https://docs.claude.com/en/docs/claude-code/sub-agents). See [anthropics/claude-code#8501](https://github.com/anthropics/claude-code/issues/8501) for tracking. The [plugins-reference.md](https://docs.claude.com/en/docs/claude-code/plugins-reference) may show an older agent format using a `capabilities` field; for Claude Code plugins, prefer the structure documented in this skill which uses `tools` for tool restrictions.
 
 ## Quick Start
 
@@ -206,6 +208,8 @@ Which model the agent should use.
 
 Visual identifier for agent in UI.
 
+> **Note:** This field is supported by Claude Code but not yet in official documentation. See the [Overview note](#overview) for details.
+
 **Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
 
 **Guidelines:**