upgrade-plugin

Upgrade Plugin

Upgrade a plugin's skills, hooks, and patterns to align with the latest Claude Code capabilities, model features, and skill-writing best practices.

Arguments: $ARGUMENTS -- plugin name (e.g., creator-stack, scheduler) and optional focus areas. If no plugin specified, ask which one.

Locate Target Plugin

Find the plugin to upgrade:

1. Check <cwd>/<plugin-name>/.claude-plugin/plugin.json (source mode -- marketplace repo)
2. If not found, check ~/.claude/plugins/cache/*/<plugin-name>/ (installed mode)

If neither found, list available plugins and ask the user to clarify.

Set PLUGIN_ROOT to the resolved path.

---

Phase 1: Research Latest Context

Run six research tasks in parallel using subagents. Each subagent summarizes its findings.

1A. Claude Code Changelog

Fetch the latest Claude Code releases:

WebFetch: https://github.com/anthropics/claude-code/releases

Also check the raw changelog:

WebFetch: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

Extract from the last 3-5 releases:

• New tool capabilities or parameters
• New hook events or rule features
• Changes to skill loading, triggering, or frontmatter
• New agent/subagent patterns
• Deprecations or breaking changes
• Performance improvements relevant to skill design

1B. Claude Code Documentation (Discovery-Driven)

Discover the Claude Code documentation landscape. Do NOT hardcode doc page URLs -- discover them dynamically.

1. Find available documentation:

   WebSearch: "Claude Code" site:docs.anthropic.com
   WebFetch: https://docs.anthropic.com/en/docs/claude-code/overview
   

2. From the search results and overview page, identify and fetch pages covering these categories:

   • Core infrastructure: skills, hooks, rules, CLAUDE.md
   • Agent capabilities: subagents/Agent tool, agent teams
   • Plugin system: commands, output styles, MCP servers, plugin architecture
   • Memory & context: auto memory, context management
   • Configuration: settings, permissions, tool gating
   • Workflow: worktrees, session management

3. For each fetched page, extract:

   • Current best practices and recommended patterns
   • New features relevant to the target plugin
   • Deprecated patterns the plugin might still use
   • Capabilities the plugin doesn't leverage yet

1C. Skill-Creator Best Practices

Find and read the installed skill-creator:

Glob: ~/.claude/plugins/cache/*/skill-creator/*/skills/skill-creator/SKILL.md

Extract:

• Current skill writing patterns
• Progressive disclosure guidelines (line limits, reference files)
• Description optimization guidance (triggering, "pushy" descriptions)
• Testing and evaluation patterns

1D. Superpowers & Platform Patterns

Check official plugins for patterns worth adopting:

Glob: ~/.claude/plugins/cache/*/superpowers/*/skills/*/SKILL.md

Note structural patterns, frontmatter conventions, or composition techniques.

1E. Plugin Architecture

Understand the full plugin specification and what the target plugin could be using:

1. Read the marketplace conventions (if in source mode):

   Read: <cwd>/CONVENTIONS.md
   

2. Examine other installed plugins for structural patterns:

   Glob: ~/.claude/plugins/cache/*/*/skills/*/SKILL.md
   Bash: ls ~/.claude/plugins/cache/*/*/ | head -50
   

   Focus on: plugin.json fields, agents/ directories, MCP server integration, output style patterns.

3. Compare the target plugin's structure against the full spec:

   • What directories does it have vs. what's available?
   • What plugin.json fields exist vs. what it uses?
   • Are other plugins using components this one doesn't?

1F. Model Capability Assessment

Check for model-level improvements that may supersede skills in the target plugin:

1. Search for recent Anthropic model releases:

   WebSearch: "Anthropic Claude" model release OR capability update site:anthropic.com
   WebSearch: "Claude" new capabilities 2026
   

2. Fetch the models overview page:

   WebFetch: https://docs.anthropic.com/en/docs/about-claude/models
   

3. Extract capabilities relevant to skill obsolescence:

   • Built-in tool use improvements (web search, code execution)
   • Reasoning and planning improvements
   • Multi-step task handling
   • Areas where dedicated prompting/orchestration adds less value

4. Compare against the target plugin's skill inventory:

   • For each skill, ask: "Does the model now do this well enough without specialized prompting?"
   • Flag skills where the answer is "yes" or "probably"

Research Output

After all research completes, compile a Research Summary with sections:

• New Claude Code Features (from changelog + docs)
• Updated Skill Best Practices (from skill-creator)
• Platform Patterns (from superpowers and other plugins)
• Plugin Architecture Gaps (capabilities the target plugin doesn't use yet)
• Deprecations & Breaking Changes
• Model Capability Overlap (skills potentially superseded by model improvements)

Save to <cwd>/.docs/upgrade-research/<plugin-name>-<date>.md for reference.

---

Phase 1.5: Obsolescence Screen

Using research findings from Phase 1 (especially 1A, 1B, and 1F), evaluate whether each skill, agent, and major component in the target plugin is still necessary.

Classification

For each skill and agent, assign one of:

Rating	Meaning	Action
Active	Platform/model doesn't replicate this. Skill adds clear value.	Proceed to structural audit in Phase 2
Augmented	Platform/model handles the basics, but skill adds meaningful structure, guardrails, or workflow orchestration on top.	Audit normally, but note what the platform handles natively
Superseded	Platform/model now does this natively with comparable quality. Skill adds marginal value over a direct prompt.	Skip structural audit. Recommend removal in Phase 3 plan.

How to Evaluate

For each skill, answer these three questions:

1. What does this skill do that a direct prompt to Claude cannot? If the answer is only "it saves typing a prompt" -- likely Superseded.

2. Does this skill enforce a process, workflow, or multi-step structure? Process skills (TDD, debugging, code review) remain valuable even when the model can do each step -- the skill enforces discipline. Likely Active.

3. Has the platform added a native feature that replaces this skill's core function? Example: Claude Code added native web search -> a "web research" skill that just wraps web search is Superseded. But a "competitor analysis" skill that orchestrates multiple searches into a structured report may be Augmented.

Output

Present results as a table:

Component	Type	Rating	Rationale
[name]	skill/agent	Active/Augmented/Superseded	[1-line reason]

If any component is rated Superseded, flag it for the user:

Obsolescence flag: [N] component(s) appear superseded by platform/model capabilities. These will appear in the "Recommend Removal" section of the upgrade plan. Review the rationale -- override to Active or Augmented if you disagree.

Proceed to Phase 2, skipping structural audit for Superseded components.

---

Phase 2: Audit Current Plugin

Read the target plugin's full structure and evaluate against the research findings.

2A. Plugin Inventory

echo "=== Plugin.json ===" && cat ${PLUGIN_ROOT}/.claude-plugin/plugin.json
echo "=== Skills ===" && find ${PLUGIN_ROOT}/skills -name "SKILL.md" -type f 2>/dev/null
echo "=== Hooks ===" && cat ${PLUGIN_ROOT}/hooks/hooks.json 2>/dev/null || echo "No hooks"
echo "=== Output Styles ===" && ls ${PLUGIN_ROOT}/output-styles/ 2>/dev/null || echo "No output styles"
echo "=== Agents ===" && ls ${PLUGIN_ROOT}/agents/ 2>/dev/null || echo "No agents"
echo "=== Test Suites ===" && find ${PLUGIN_ROOT}/skills -path "*/tests/evals.json" -type f 2>/dev/null || echo "No test suites"
echo "=== All Files ===" && find ${PLUGIN_ROOT} -type f -not -path "*/.DS_Store" -not -path "*/node_modules/*"

For each skill, read and note:

• Frontmatter fields (name, description, user-invocable, etc.)
• Line count (should be under 500)
• Whether it uses references/ or scripts/
• Composition patterns (does it invoke other skills?)
• Any hardcoded paths or assumptions
• Obsolescence rating from Phase 1.5 (skip detailed audit for Superseded components)

For other components, evaluate:

• Output styles: under 120 lines? Leveraging latest features?
• Plugin.json: all available fields used correctly?
• Hooks: using latest events? Non-blocking?
• Missing components: would agents/ or MCP servers benefit this plugin?

2B. Gap Analysis

Compare current state against research findings:

Category	Check
Skill structure	Frontmatter follows latest conventions? Under 500 lines? Progressive disclosure?
Descriptions	Triggering descriptions specific enough per skill-creator guidance?
Patterns	Uses latest Claude Code features? No deprecated patterns?
Composition	Follows plugin:skill invocation syntax? Voice/brand hooks applied correctly?
Scripts	Bundled scripts use best practices? No reinventing common patterns?
Plugin architecture	Using all beneficial plugin components (agents, MCP, output styles)?
Component coverage	All existing components up to date with latest conventions?
Test coverage	Skills have tests/evals.json? Flag untested skills as a gap.

2C. Project Conventions Check

Read and verify against marketplace conventions:

Read: <cwd>/CONVENTIONS.md
Read: <cwd>/CLAUDE.md

Ensure the plugin follows:

• Single-responsibility skill design
• Correct skill categorization (Task / Orchestrator / Knowledge)
• Voice and brand hook presence where required
• Flat layout with no nested SKILL.md files

---

Phase 3: Upgrade Plan

Present a structured upgrade plan organized by priority:

## Upgrade Plan: <plugin-name>

### Summary
- Current version: X.Y.Z
- Proposed version: X.Y.Z (justify MAJOR/MINOR/PATCH)
- Total changes: N skills affected
- Components affected: [skills, hooks, output styles, plugin.json]

### High Priority (Breaking/Deprecated)
1. [Change description]
   - **Why**: [What's wrong or deprecated]
   - **What**: [Specific change to make]
   - **Risk**: [What could break]

### Superseded (Recommend Removal)
Components flagged as Superseded in Phase 1.5. Review before approving removal.

1. [Component name] ([type])
   - **What it does**: [1-line summary]
   - **What replaces it**: [platform feature or model capability]
   - **Migration**: [user-facing steps if any -- update docs, remove references]
   - **Risk**: [what's lost if removed]

### Medium Priority (New Features/Improvements)
1. [Change description]
   - **Why**: [What new capability this enables]
   - **What**: [Specific change to make]

### Low Priority (Polish/Optimization)
1. [Change description]

### Not Recommended
- [Things considered but rejected, and why]

Wait for user approval before proceeding. The user may adjust priorities, skip items, or add their own.

---

Phase 4: Execute Upgrades

Apply approved changes systematically:

1. One file at a time -- read the full file before editing
2. Preserve intent -- upgrade patterns without changing what the skill does
3. Explain reasoning -- prefer explaining why over heavy-handed MUSTs
4. Keep prompts lean -- remove things that aren't pulling their weight

For each file being upgraded:

• Read the current file fully
• Apply the approved changes
• Verify line count stays under limits (500 for SKILL.md, 120 for output styles)
• Check that frontmatter is correct
• Ensure composition references use plugin:skill syntax

Version Bump

After all changes:

• Update plugin.json version according to semver
• Update CHANGELOG.md with all changes in Keep a Changelog format

---

Phase 5: Verify

Before declaring done:

for skill in $(find ${PLUGIN_ROOT}/skills -name "SKILL.md"); do
  echo "=== $skill ==="
  wc -l "$skill"
  head -5 "$skill"
  echo ""
done

1. Diff review -- show git diff of all changes for user review
2. Frontmatter check -- verify all skills have valid frontmatter
3. Line count check -- no SKILL.md over 500 lines
4. Convention check -- all changes follow CONVENTIONS.md
5. Cross-reference check -- any plugin:skill references still valid
6. Test suite check -- If any modified skills have tests/evals.json, offer to run them:
   • "N skills were modified. M have test suites. Run them now?"
   • If user approves, invoke plugin-tools:test-skill for each skill with tests
   • Surface any regressions before the user approves the upgrade

Present a final summary:

• Changes made (with file paths)
• Version bump applied
• CHANGELOG entry
• Any manual follow-up needed