Which documentation needs improvement?
Skill documentation
Specific Location
plugins/plugin-dev/skills/hook-development/SKILL.md - "Temporarily Active Hooks" section (approximately lines 296-350)
What's unclear or missing?
The "Temporarily Active Hooks" section in SKILL.md duplicates content that already exists in references/patterns.md as Pattern 9: Temporarily Active Hooks and Pattern 10: Configuration-Driven Hooks.
This violates the skill-development best practice guideline:
"Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window."
Evidence
SKILL.md contains (~50 lines):
- "Temporarily Active Hooks" section with flag file activation pattern
- "Configuration-based activation" pattern
references/patterns.md contains the same content:
- Pattern 9: Temporarily Active Hooks (flag file activation)
- Pattern 10: Configuration-Driven Hooks (JSON configuration)
Impact
- SKILL.md is currently 2,125 words (above the ideal 1,500-2,000 target)
- Removing this duplicated section would reduce it to approximately 2,000 words
- Follows progressive disclosure principle (details in references/, core in SKILL.md)
Suggested Improvement
- Remove the "Temporarily Active Hooks" section from SKILL.md
- Add a brief reference in its place, such as:
For temporarily active hooks (flag files, configuration-driven activation), see Pattern 9 and Pattern 10 in `references/patterns.md`.
Or simply ensure the existing "Additional Resources" section adequately points to patterns.md.
Type of issue
Additional Context
Discovered during comprehensive skill review against official Claude Code plugin documentation and the skill-development skill best practices.
Which documentation needs improvement?
Skill documentation
Specific Location
plugins/plugin-dev/skills/hook-development/SKILL.md- "Temporarily Active Hooks" section (approximately lines 296-350)What's unclear or missing?
The "Temporarily Active Hooks" section in SKILL.md duplicates content that already exists in
references/patterns.mdas Pattern 9: Temporarily Active Hooks and Pattern 10: Configuration-Driven Hooks.This violates the skill-development best practice guideline:
Evidence
SKILL.md contains (~50 lines):
references/patterns.md contains the same content:
Impact
Suggested Improvement
Or simply ensure the existing "Additional Resources" section adequately points to patterns.md.
Type of issue
Additional Context
Discovered during comprehensive skill review against official Claude Code plugin documentation and the skill-development skill best practices.