Developer tools for maintaining Claude Code plugins — upgrade skills, session retrospectives, audit structure, align with latest platform capabilities

GitHub stars
128

Install

/plugin install plugin-tools@ai-launchpad

Run it inside Claude Code after adding the marketplace with /plugin marketplace add kenneth-liao/ai-launchpad-marketplace.

Contents

Discovered from source

Skills 2

Skill Retro

Analyze how skills performed in the current session and apply improvements via skill-creator.

Process

Step 1: Preprocess Session

Run the preprocessing script to extract a clean transcript from the current session's JSONL log:

node ${CLAUDE_SKILL_DIR}/scripts/preprocess.mjs --cwd <current-working-directory>

Capture the JSON output. Key fields:

  • transcript_file — path to the temp file containing the full transcript (at ~/.claude/tmp/skill-retro-<session-id>.json)
  • stats.skill_invocations — count of skills used

The script writes the full transcript to a temp file to avoid flooding the main thread's context window. Only the summary (stats + file path) appears in stdout.

If the script fails (e.g., no session files found), report the error and stop.

If skill_invocations is 0, tell the user: "No skills were invoked in this session — nothing to analyze." and stop.

Step 2: Analyze (Sub-Agent)

Spawn an analysis sub-agent (using the Agent tool, model: sonnet):

  • Load the prompt from ${CLAUDE_SKILL_DIR}/references/analysis-prompt.md
  • Tell the agent to read the transcript file at the path from transcript_file in Step 1's output
  • The agent should read the SKILL.md file for each invoked skill to compare intended vs. actual behavior. Skill paths are discoverable from the transcript's system-reminder blocks (which list installed skill base directories) or from [SKILL INVOCATION] markers combined with installed plugin cache paths.
  • The agent returns a JSON object with findings, well_executed, and severity_summary

Parse the agent's response into structured findings.

Once the analysis agent has finished, delete the temp file created in Step 1:

rm <transcript_file>

If the agent returns 0 findings, tell the user: "All skills performed well this session. No improvements identified." Show the well_executed list and stop.

Step 3: Interpret and Recommend

Don't just present raw findings — interpret them. For each finding, add your own reasoning:

  1. What the fix looks like — Is it a one-line description tweak? A new section in SKILL.md? A script rewrite? Be specific about what changes would actually be made.
  2. Effort estimate — Quick fix (description/wording change), moderate (new section or error handling), or high-lift (architectural change, script rewrite, new scripts).
  3. Recommendation — Whether to action it now, defer it, or skip it entirely. Explain why.

Group findings by skill and present with your interpretation:

## Skill Performance Report

### scheduler:manage (3 findings)

**1. [high] gap_coverage — pause command doesn't verify unload succeeded**
The `_launchctl_unload` helper silently swallows errors, so the registry can say "paused" while the job is still running.
- **Fix:** Add return-code checking to `_launchctl_unload` in the manage script, and add a post-unload verification step in SKILL.md's Pause operation.
- **Effort:** Moderate — script change + SKILL.md update
- **Recommend: Action** — This caused real user confusion in this session.

**2. [medium] gap_coverage — No error recovery entry for "task still runs after pausing"**
The assistant had to improvise the entire investigation.
- **Fix:** Add a new row to the Error Recovery table in SKILL.md.
- **Effort:** Quick — one table row addition
- **Recommend: Action** — Low effort, high value.

**3. [low] execution_quality — list command shows registry status without cross-checking launchd**
Would require the list command to shell out to `launchctl list` and reconcile.
- **Fix:** Add launchd state reconciliation to the list operation in the manage script.
- **Effort:** High-lift — requires new script logic and testing across platforms.
- **Recommend: Defer** — Nice-to-have but significant work. Not worth addressing now.

### Well Executed
- list presented clean, accurate registry data
- Assistant correctly went outside the skill to diagnose the real issue

---
I recommend actioning findings 1 and 2. Finding 3 is high-lift and better deferred.

Proceed with these? (y/adjust/none)

Key principles:

  • Lead with your recommendation — don't make the user figure out what's worth doing
  • Be honest about high-lift items — don't propose changes that would require major rewrites unless they're clearly worth it
  • Group related findings that would be addressed together
  • The user can adjust your recommendation (add/remove items) or accept it

Wait for user confirmation. If "none", show summary and stop.

Step 4: Resolve Source Locations

For each skill with selected findings, determine where to edit:

Resolution order:

  1. Project-level skill — path contains .claude/skills/ relative to a project → Candidate: edit in place (user owns it)

  2. User-level skill — path is under ~/.claude/skills/ → Candidate: edit in place (user owns it)

  3. Installed plugin — path is under ~/.claude/plugins/cache/ → Try to trace to source: a. Extract plugin name from the path b. Check if cwd is a marketplace project containing that plugin's source (look for <plugin-name>/skills/<skill-name>/SKILL.md) c. If not found, ask user: "Where is the source code for the <plugin-name> plugin? Provide a path, or type 'installed' to edit the installed copy." → If "installed": warn that changes will be overwritten on plugin update, proceed only if user confirms → If user provides a path: verify it exists and contains the skill

  4. Current project contains source — cwd has ./<plugin-name>/skills/<skill-name>/SKILL.md → Candidate: edit in place

For each resolved path, confirm with the user before proceeding:

I'll make changes to <skill-name> at:
→ /path/to/resolved/source/SKILL.md

Is this the right location? (y/n or provide correct path)

Do NOT proceed to implementation until every path is confirmed.

Step 5: Implement Improvements (Parallel Sub-Agents)

For each affected skill (with confirmed source path), spawn an implementation sub-agent:

  • One agent per skill — can run in parallel since they edit different files

  • Agent prompt:

    "You are improving a Claude Code skill based on performance analysis findings.

    Skill: <skill-name> Source path: <confirmed-path-to-skill-directory> SKILL.md location: <confirmed-path>/SKILL.md

    Findings to address: <list all selected findings for this skill with full observation, evidence, and proposed_improvement>

    Instructions:

    1. Read the current SKILL.md at the source path
    2. Invoke the skill-creator:skill-creator skill
    3. When skill-creator asks what you want to do, explain you are improving an existing skill based on session analysis
    4. Provide the findings as the basis for changes
    5. Follow skill-creator's process to apply the improvements
    6. After changes are made, report what was modified"

Step 6: Summary

After all implementation agents complete, present a summary:

## Skill Retro Complete

### Changes Applied
| Skill | Source Path | Changes |
|-------|------------|---------|
| scheduler:manage | /path/to/SKILL.md | Added return-code checking to _launchctl_unload, post-unload verification step |
| scheduler:manage | /path/to/SKILL.md | Added "task still runs after pausing" to Error Recovery table |

### Deferred
- scheduler:manage #3 (launchd state reconciliation) — high-lift, deferred

### Well Executed
- list operation presented clean, accurate registry data

Important Notes

  • This skill is designed to run late in sessions when context may be full. All analysis and implementation happens in sub-agents to preserve main thread context.
  • The preprocessing script writes the full transcript to ~/.claude/tmp/skill-retro-*.json and only outputs a summary to stdout. Clean up the temp file after the analysis sub-agent has finished reading it.
  • The preprocessing script has zero dependencies beyond Node.js.
  • Never edit a skill without user confirmation of the source path.
  • When invoking skill-creator in implementation agents, let it guide the process — don't bypass its workflow.

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:

RatingMeaningAction
ActivePlatform/model doesn't replicate this. Skill adds clear value.Proceed to structural audit in Phase 2
AugmentedPlatform/model handles the basics, but skill adds meaningful structure, guardrails, or workflow orchestration on top.Audit normally, but note what the platform handles natively
SupersededPlatform/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:

ComponentTypeRatingRationale
[name]skill/agentActive/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:

CategoryCheck
Skill structureFrontmatter follows latest conventions? Under 500 lines? Progressive disclosure?
DescriptionsTriggering descriptions specific enough per skill-creator guidance?
PatternsUses latest Claude Code features? No deprecated patterns?
CompositionFollows plugin:skill invocation syntax? Voice/brand hooks applied correctly?
ScriptsBundled scripts use best practices? No reinventing common patterns?
Plugin architectureUsing all beneficial plugin components (agents, MCP, output styles)?
Component coverageAll existing components up to date with latest conventions?
Test coverageSkills 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

Sponsors

Details

Marketplace
kenneth-liao/ai-launchpad-marketplace
Source
plugin-tools
Category
Community

More from kenneth-liao/ai-launchpad-marketplace

All 5