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

skills/*/SKILL.md

name

description

allowed-tools

skills/using-*/*.md

commands/*.md

description

allowed-tools

argument-hint

agents/*.md

description

model

tools

hooks/hooks.json

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

skills/using-skillpack-maintenance/analyzing-pack-domain.md

Workflow: Review → Discuss → Execute

Stage 1: Investigation

Load:

analyzing-pack-domain.md

1. User scope - Ask about intent, boundaries, target audience
2. Domain mapping - What should this plugin cover?
3. Inventory audit - What exists? Skills, commands, agents, hooks?
4. 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

Execute approved changes:

1. Structural fixes (remove duplicates, update router)
2. Content enhancements (fix behavioral failures)
3. Component creation (commands, agents - NOT skills)
4. 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

Default for maintenance: Minor bump

Red Flags - Stop and Reconsider

superpowers:writing-skills

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.