Skip to content

docs: clarify official documentation discrepancies in agent-development skill#124

Merged
sjnims merged 1 commit intomainfrom
docs/123-clarify-official-documentation-discrepancies
Dec 11, 2025
Merged

docs: clarify official documentation discrepancies in agent-development skill#124
sjnims merged 1 commit intomainfrom
docs/123-clarify-official-documentation-discrepancies

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 11, 2025

Summary

Adds clarification notes to the agent-development skill explaining documentation discrepancies between this skill and official Claude Code documentation.

Problem

Fixes #123

Users following the agent-development skill may be confused when comparing it to official Claude Code documentation because:

  1. The color field is documented here but not in the official sub-agents docs
  2. The plugins-reference.md shows an older agent format using capabilities instead of tools

Solution

Added clarification notes in two locations:

  1. Overview section - Comprehensive note explaining both discrepancies and linking to anthropics/claude-code#8501 for upstream tracking
  2. color field section - Brief note pointing back to the overview for details

Alternatives Considered

  • Adding a dedicated "Documentation Notes" section: Rejected as it would add too much visual weight for a temporary discrepancy
  • Only documenting at the color field: Rejected as users need context early in the document

Changes

  • plugins/plugin-dev/skills/agent-development/SKILL.md: Added clarification notes about official documentation discrepancies

Testing

  • Linting passes (markdownlint)
  • Links to upstream issue and docs are valid

🤖 Generated with Claude Code

@sjnims @claude
docs: clarify official documentation discrepancies in agent-developme…
6527ba0 
…nt skill

Add notes explaining that the `color` field is supported by Claude Code
(generated by the `/agents` command) but not yet documented in the official
sub-agents documentation. Also clarify that plugins-reference.md may show
an older format using `capabilities`; plugins should use `tools` instead.

References anthropics/claude-code#8501 for upstream tracking.

Fixes #123

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@sjnims sjnims mentioned this pull request Dec 11, 2025
Closed
7 tasks
@claude
Copy link
Copy Markdown

claude Bot commented Dec 11, 2025 •
edited
Loading

Claude finished @sjnims's task in 59s —— View job

PR Review Complete ✓

Summary

Looks good - This PR makes valuable clarifications that will help users understand documentation discrepancies without changing any functionality.

What's Good

Clear Problem Identification: The PR addresses a real issue (#123) where users comparing this skill's documentation with official Claude Code docs would encounter confusing discrepancies about the color field and capabilities vs tools format.

Well-Placed Notes: The clarifications are strategically positioned:

  1. Overview section (line 21): Comprehensive note that explains both discrepancies upfront when users first read the skill
  2. color field section (line 211): Contextual reminder with link back to overview for full details

Excellent External References: Links to both the official documentation and the upstream tracking issue (anthropics/claude-code#8501) provide transparency and allow users to track when these discrepancies are resolved.

Markdown Quality: ✓ All markdownlint checks pass with no issues

Minimal, Focused Change: The PR stays tightly focused on the specific problem - adding only the necessary clarification without over-documenting or restructuring unnecessarily.

Checklist Verification

  • ✓ Component Documentation: The skill maintains proper frontmatter (name, description) and progressive disclosure pattern
  • ✓ Markdown Linting: Passes markdownlint --config .markdownlint.json with zero errors
  • ✓ Links: Both external links (official docs, GitHub issue) are valid
  • ✓ Consistency: Maintains existing tone and style of the document
  • ✓ User Experience: Helps users understand that differences from official docs are known and intentional

Minor Observations

No Action Required - Just noting for context:

  1. The note mentions that /agents command generates the color field, which validates this is current Claude Code behavior
  2. The phrasing "prefer the structure documented in this skill" appropriately guides users to follow this plugin's documentation while acknowledging the official docs difference

Recommendation: ✅ Approve and merge

This PR successfully addresses issue #123 with clear, well-placed documentation that will reduce user confusion. The changes are minimal, accurate, and helpful.

@sjnims sjnims self-assigned this Dec 11, 2025
@claude claude Bot added documentation Improvements or additions to documentation component:skill Skills layer effort:small < 1 hour labels Dec 11, 2025
@sjnims sjnims merged commit ec70f87 into main Dec 11, 2025
8 checks passed
@sjnims sjnims deleted the docs/123-clarify-official-documentation-discrepancies branch December 11, 2025 03:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@sjnims sjnims

Labels

component:skill Skills layer documentation Improvements or additions to documentation effort:small < 1 hour

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Docs]: Clarify official documentation discrepancies in agent-development skill

1 participant

@sjnims