Agent Skills: 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]

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