
plugin-tools
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-launchpadRun it inside Claude Code after adding the marketplace with /plugin marketplace add kenneth-liao/ai-launchpad-marketplace.
Contents
Discovered from sourceSkills 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_filein 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, andseverity_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:
- 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.
- Effort estimate — Quick fix (description/wording change), moderate (new section or error handling), or high-lift (architectural change, script rewrite, new scripts).
- 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:
-
Project-level skill — path contains
.claude/skills/relative to a project → Candidate: edit in place (user owns it) -
User-level skill — path is under
~/.claude/skills/→ Candidate: edit in place (user owns it) -
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 -
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.mdFindings to address: <list all selected findings for this skill with full observation, evidence, and proposed_improvement>
Instructions:
- Read the current SKILL.md at the source path
- Invoke the
skill-creator:skill-creatorskill - When skill-creator asks what you want to do, explain you are improving an existing skill based on session analysis
- Provide the findings as the basis for changes
- Follow skill-creator's process to apply the improvements
- 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-*.jsonand 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:
- Check
<cwd>/<plugin-name>/.claude-plugin/plugin.json(source mode -- marketplace repo) - 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.
-
Find available documentation:
WebSearch: "Claude Code" site:docs.anthropic.com WebFetch: https://docs.anthropic.com/en/docs/claude-code/overview -
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
-
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:
-
Read the marketplace conventions (if in source mode):
Read: <cwd>/CONVENTIONS.md -
Examine other installed plugins for structural patterns:
Glob: ~/.claude/plugins/cache/*/*/skills/*/SKILL.md Bash: ls ~/.claude/plugins/cache/*/*/ | head -50Focus on: plugin.json fields, agents/ directories, MCP server integration, output style patterns.
-
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:
-
Search for recent Anthropic model releases:
WebSearch: "Anthropic Claude" model release OR capability update site:anthropic.com WebSearch: "Claude" new capabilities 2026 -
Fetch the models overview page:
WebFetch: https://docs.anthropic.com/en/docs/about-claude/models -
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
-
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:
-
What does this skill do that a direct prompt to Claude cannot? If the answer is only "it saves typing a prompt" -- likely Superseded.
-
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.
-
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:
- One file at a time -- read the full file before editing
- Preserve intent -- upgrade patterns without changing what the skill does
- Explain reasoning -- prefer explaining why over heavy-handed MUSTs
- 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:skillsyntax
Version Bump
After all changes:
- Update
plugin.jsonversion according to semver - Update
CHANGELOG.mdwith 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
- Diff review -- show
git diffof all changes for user review - Frontmatter check -- verify all skills have valid frontmatter
- Line count check -- no SKILL.md over 500 lines
- Convention check -- all changes follow CONVENTIONS.md
- Cross-reference check -- any
plugin:skillreferences still valid - 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-skillfor 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