kenneth-liao/ai-launchpad-marketplace/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 ``

1. 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

1. 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 ``

1. 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.

1. 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 ``

1. Fetch the models overview page:

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

1. 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

1. 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:

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.

1. 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.

1. 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:

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:

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]

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

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