Skip to content

docs: fix incorrect references in skill-reviewer agent#115

Merged
sjnims merged 1 commit intomainfrom
docs/112-incorrect-references-in-skill-reviewer-agent
Dec 11, 2025
Merged

docs: fix incorrect references in skill-reviewer agent#115
sjnims merged 1 commit intomainfrom
docs/112-incorrect-references-in-skill-reviewer-agent

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 11, 2025

Summary

Fixes two documentation inaccuracies in the skill-reviewer agent that could confuse users.

Problem

Fixes #112

The skill-reviewer agent contained two incorrect references:

  1. Line 44: Referenced "skill-creator best practices" but no skill-creator agent exists
  2. Line 57: Claimed when_to_use is deprecated without any source in Claude Code docs

Solution

  1. Updated line 44 to reference "best practices from the skill-development skill" which accurately points to the actual skill that documents these practices
  2. Simplified line 57 to remove the undocumented deprecation claim and note that optional fields may vary per Claude Code updates

Alternatives Considered

  • For fix 1: Could have used generic "skill development best practices" but opted for explicit skill reference for clarity
  • For fix 2: Could have added a source citation, but since when_to_use isn't documented anywhere in official Claude Code docs, removing the claim is the safest approach

Changes

  • plugins/plugin-dev/agents/skill-reviewer.md: Updated lines 44 and 57

Testing

  • Markdownlint passes
  • Changes are documentation-only (no functional code)

🤖 Generated with Claude Code

@sjnims @claude
docs: fix incorrect references in skill-reviewer agent
369fefb 
- Update line 44: change "skill-creator best practices" to reference
  the skill-development skill (skill-creator agent doesn't exist)
- Update line 57: remove undocumented when_to_use deprecation claim
  and simplify optional fields documentation

Fixes #112

🤖 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 encountered an error —— View job

I'll analyze this and get back to you.

@sjnims sjnims self-assigned this Dec 11, 2025
@claude claude Bot added documentation Improvements or additions to documentation component:agent Agents layer effort:small < 1 hour labels Dec 11, 2025
@claude
Copy link
Copy Markdown

claude Bot commented Dec 11, 2025 •
edited
Loading

Claude finished @sjnims's task in 1m 25s —— View job

PR Review Complete ✓

Tasks

  • Get PR diff to understand changes
  • Read modified agent file for context
  • Run markdownlint on changed files
  • Verify agent follows plugin-dev conventions
  • Review accuracy of documentation fixes
  • Post final review feedback

Summary

Looks good! This PR fixes two legitimate documentation inaccuracies in the skill-reviewer agent. The changes are accurate, well-justified, and improve documentation correctness.

What's Good

  1. Accurate Fix fix: correct invalid skill name fields to kebab-case #1: Correctly updates the reference from non-existent "skill-creator" to the actual "skill-development skill"

    • I verified that skill-development exists at plugins/plugin-dev/skills/skill-development/
    • The "skill-creator" was only found in reference files (e.g., skill-creator-original.md), not as an actual agent or skill
    • The new wording is more explicit and helpful

  2. Accurate Fix refactor: reduce SKILL.md word counts through progressive disclosure #2: Removes undocumented when_to_use deprecation claim

    • I searched the entire plugins/plugin-dev directory and found zero references to when_to_use as a frontmatter field
    • The skill-development documentation (skill-development/SKILL.md:45-65) only documents name, description, and allowed-tools as frontmatter fields
    • The new phrasing "others may exist per Claude Code updates" is appropriately flexible

  3. Clean Implementation:

    • Changes are minimal and surgical (2 lines changed)
    • Markdownlint passes with no issues
    • No functional code changes
    • Agent structure and frontmatter remain valid

Agent Validation

The skill-reviewer agent follows all plugin-dev conventions:

  • ✓ Valid YAML frontmatter with required fields (name, description)
  • ✓ Proper <example> blocks in description for triggering (3 examples provided)
  • ✓ Third-person description format ("Use this agent when...")
  • ✓ Appropriate tool restrictions (tools: ["Read", "Grep", "Glob"])
  • ✓ Model and color specified (model: inherit, color: cyan)

Checklist Verification

  • ✓ Markdownlint passes (verified)
  • ✓ Changes are documentation-only (confirmed)
  • ✓ References are now accurate (verified skill-development exists, when_to_use doesn't)
  • ✓ PR description clearly explains the problem and solution

Recommendation

Approve and merge. These are legitimate corrections that improve documentation accuracy.

@sjnims sjnims merged commit fb7dbd1 into main Dec 11, 2025
8 of 9 checks passed
@sjnims sjnims deleted the docs/112-incorrect-references-in-skill-reviewer-agent branch December 11, 2025 02:21
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:agent Agents 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]: Incorrect references in skill-reviewer agent

1 participant

@sjnims