Plugin Maintenance

Systematic maintenance of Claude Code plugins including skills, commands, agents, hooks, and reference sheets.

Core Principle

Maintenance = behavioral validation, not syntactic checking. Test if components guide Claude correctly, not if they parse correctly.

Scope: What This Skill Maintains

Component Location Frontmatter

Skills skills/*/SKILL.md

name , description , allowed-tools

Reference sheets skills/using-/.md

(none - content files)

Commands commands/*.md

description , allowed-tools , argument-hint

Agents agents/*.md

description , model , tools

Hooks hooks/hooks.json

JSON with event matchers

When to Use

Use for:

• Enhancing existing plugins (e.g., "refresh yzmir-deep-rl")

• Adding/removing/modifying components

• Identifying coverage gaps

• Validating component quality

Do NOT use for:

• Creating new plugins from scratch (design first)

• Creating brand new skills (use superpowers:writing-skills )

Reference Sheet Location

All reference sheets are in this skill's directory:

• analyzing-pack-domain.md

• Domain investigation

• reviewing-pack-structure.md

• Structure review, scorecard

• testing-skill-quality.md

• Behavioral testing methodology

• implementing-fixes.md

• Execution and versioning

When reading analyzing-pack-domain.md , find it at: skills/using-skillpack-maintenance/analyzing-pack-domain.md

Workflow: Review → Discuss → Execute

Stage 1: Investigation

Load: analyzing-pack-domain.md

• User scope - Ask about intent, boundaries, target audience

• Domain mapping - What should this plugin cover?

• Inventory audit - What exists? Skills, commands, agents, hooks?

• Gap analysis - What's missing vs. coverage map?

Output: Coverage map, component inventory, gaps identified

Stage 2: Structure Review

Load: reviewing-pack-structure.md

Generate fitness scorecard:

• Critical - Plugin unusable, consider rebuild

• Major - Significant gaps or structural issues

• Minor - Polish and improvements

• Pass - Structurally sound

Decision gate: Present scorecard → User decides: Proceed / Rebuild / Cancel

Stage 3: Behavioral Testing

Load: testing-skill-quality.md

Test each component with challenging scenarios:

• Pressure tests - Does it hold under "just do it quickly" pressure?

• Edge cases - Does it handle corner cases?

• Real-world complexity - Does it guide correctly in messy situations?

Output: Per-component test results (Pass / Fix needed)

Stage 4: Discussion

Present findings by category:

Gaps requiring new components:

• Skills needing superpowers:writing-skills (each = separate RED-GREEN-REFACTOR)

• Commands to create

• Agents to create

Existing components needing fixes:

• Skills/commands/agents with behavioral failures

• Hooks with issues

Get user approval before execution.

Stage 5: Execution

Load: implementing-fixes.md

CRITICAL CHECKPOINT: If gaps were identified → Use superpowers:writing-skills for EACH new skill first. Do NOT create new skills inline. They require behavioral testing.

Execute approved changes:

• Structural fixes (remove duplicates, update router)

• Content enhancements (fix behavioral failures)

• Component creation (commands, agents - NOT skills)

• Version bump and commit

Component-Specific Guidance

Skills (SKILL.md)

name: skill-name description: When to use this skill and what it does allowed-tools: [Read, Grep, Glob] # optional

Key questions:

• Does description trigger correct activation?

• Is guidance actionable under pressure?

• Are there missing anti-patterns?

Commands (commands/*.md)

description: What this command does allowed-tools: [Read, Bash, Glob, Grep] argument-hint: "[optional_arg]"

Key questions:

• Is the command user-invocable (vs skill which is model-invoked)?

• Does it have clear entry point?

• Are tool restrictions appropriate?

Agents (agents/*.md)

description: What this agent specializes in model: sonnet # or opus, haiku tools: [Read, Grep, Glob, Bash, Write]

Key questions:

• Clear scope boundaries (what it does / doesn't do)?

• Appropriate model selection for complexity?

• Activation examples (positive and negative)?

Hooks (hooks/hooks.json)

{ "hooks": { "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{"type": "command", "command": "script.sh"}] }] } }

Events: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact

Key questions:

• Correct event type for the use case?

• Matcher pattern accurate?

• Script executable and tested?

Version Bump Rules

Impact Bump Examples

Low Patch (x.y.Z) Typos, formatting, minor clarifications

Medium Minor (x.Y.0) Enhanced guidance, new components, better examples

High Major (X.0.0) Components removed, structural changes, philosophy shifts

Default for maintenance: Minor bump

Red Flags - Stop and Reconsider

Thought Reality

"I'll write new skills during execution" NO. Use superpowers:writing-skills for each gap

"Syntax looks correct, no need to test" Parsing ≠ effectiveness. Test behavior.

"This is a quick fix, skip the process" Quick untested = broken later

"The command/agent is simple enough" Simple things fail in edge cases. Test anyway.

Quick Reference

Investigation → Scorecard → Testing → Discussion → Execution ↓ ↓ ↓ ↓ ↓ Domain map Fitness Behavioral Present Apply

• inventory rating validation + approve changes

Load briefings at each stage. Test with scenarios. Get approval. Execute.