From plugin-manager
Audits, synchronizes, and maintains the health of the plugin ecosystem. Handles structural compliance checks against Open Standards, agent environment sync (install + cleanup orphans), and README scaffolding. Trigger when validating new plugins, syncing plugins to agent configs, or performing routine ecosystem health checks.
How this skill is triggered — by the user, by Claude, or both
Slash command
/plugin-manager:maintain-pluginsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill requires **Python 3.8+** and standard library only. No external packages needed.
acceptance-criteria.mdassets/diagrams/cleanup_flow.mmdassets/resources/cleanup_flow.mmdevals/evals.jsonevals/results.tsvfallback-tree.mdplugin.jsonreferences/acceptance-criteria.mdreferences/cleanup_flow.mmdreferences/cleanup_process.mdreferences/fallback-tree.mdrequirements.txtscripts/audit_structure.pyscripts/bridge_installer.pyscripts/generate_readmes.pyscripts/plugin_bootstrap.pyscripts/plugin_inventory.pyscripts/sync_with_inventory.pyThis skill requires Python 3.8+ and standard library only. No external packages needed.
To install this skill's dependencies:
pip-compile ./requirements.in
pip install -r ./requirements.txt
See ../../requirements.txt for the dependency lockfile (currently empty — standard library only).
This skill is the ecosystem health hub. It covers three operations:
plugins/, cleaning up orphaned artifactsCore constraint: Custom, project-specific plugins are NEVER deleted during sync. Only vendor-managed plugins that have been locally removed are cleaned up.
cleanup_process.mdcleanup_flow.mmdCRITICAL: Do not immediately generate bash commands. Operate as an interactive assistant.
When invoked, ask what operation the user needs:
Which maintenance operation?
1. [Audit] — Check plugin(s) against structural Open Standards
2. [Sync] — Sync plugins/ to all agent environments (install + cleanup orphans)
3. [README] — Scaffold missing README.md files from plugin metadata
State exactly what you are about to do and ask for confirmation:
### Proposed Maintenance Task
- **Operation**: [Audit / Sync (Dry Run) / Sync (Apply) / README Generation]
- **Target**: [All plugins / Specific plugin: name]
- **Impact**: [Read-only / Modifies agent config directories]
> Does this look correct? I will generate the commands once you confirm.
For Sync: Always propose a Dry Run first before offering to Apply.
Wait for explicit confirmation (yes, looks good, ok).
python3 ./scripts/audit_structure.py
For deeper semantic + security checks, invoke
analyze-pluginfromagent-plugin-analyzer.
Run after every structure scan to catch hardcoded or non-portable paths (ADR-003/004):
python3 plugins/agent-plugin-analyzer/scripts/audit_plugin_paths.py plugins/
Expected output: ✅ Clean! 0 violations found.
If violations are found, invoke the fix-plugin-paths skill from agent-plugin-analyzer to
remediate each file. A clean path audit is a mandatory gate before any merge or release.
Common violations it catches:
plugins/<name>/scripts/foo.py → ./scripts/foo.py).agents/skills/<skill>/scripts/ paths that break on reinstall/Users/<name>/...) that break portability across machinesFor each plugin being audited, classify every file by type and check against Open Standards:
File Type Classification:
| Type | Path Pattern | Notes |
|---|---|---|
| Skill definition | skills/*/SKILL.md | One per skill dir |
| Command | commands/*.md | Slash-command instructions |
| Reference | skills/*/references/*.md | Progressive disclosure content |
| Script | scripts/*.py | Python only — no .sh/.ps1 |
| Manifest | ../../../.claude-plugin/plugin.json | Required |
| Connectors | CONNECTORS.md | Required if Supercharged/Integration-Dependent |
| Diagram | *.mmd | Architecture diagrams |
| README | README.md | Required |
7 Structural Dimensions:
| Dimension | Pass Condition |
|---|---|
| Layout | Each skill has its own directory. No flat file mixing. |
| Progressive Disclosure | Every SKILL.md is under 500 lines. Deep content is in references/. |
| Naming | Plugin name: kebab-case, lowercase. Skill names: same convention, matching directory. |
| README Quality | Has directory tree, usage examples, skill table. |
| CONNECTORS.md | Present if plugin uses external tools. Uses ~~category abstraction. |
| Architecture fit | Is Standalone / Supercharged / Integration-Dependent clearly declared? |
| ././././plugin.json | Has unique name, version, description, author.url, repository. |
SKILL.md Frontmatter Quality Checks:
description written in third personname matches directory name (kebab-case, lowercase)SKILL.md Body Structure Checks:
references/ for deep content (not inline)allowed-tools declared if tool-restrictedThree Compliance Absolutes (from Open Standards):
.html, .svg, or .js artifacts, MUST implement Client-Side Compute Sandbox (hardcoded loop bounds) + XSS Compliance Gate (no external script tags)tools: allowlistFor each violation found, report with severity:
../../../.claude-plugin/plugin.json, shell=True in scripts, hardcoded credentialsallowed-toolsCONNECTORS.md for tool-using plugin, missing fallback-treerepository in ././././plugin.jsonFor L5 maturity scoring, invoke the
l5-red-team-auditoragent fromagent-plugin-analyzer.
python3 ./scripts/sync_with_inventory.py --dry-run
python3 ./scripts/sync_with_inventory.py
local-plugins-inventory.json (generated in project root) for current state.plugins/..agent, .gemini, etc.python3 ./scripts/generate_readmes.py --apply
| Condition | Response |
|---|---|
| "Vendor directory not found" | Clone vendor: git clone https://github.com/richfrem/agent-plugins-skills.git .vendor/agent-plugins-skills |
shell=True detected in any script | STOP — CRITICAL: Command Injection Vector. Report before proceeding. |
| Custom plugin accidentally cleaned | STOP. Restore via git checkout -- plugins/<name>/. Never re-run until cause identified. |
| SKILL.md exceeds 500 lines | FLAG HIGH: Progressive Disclosure Violation. Suggest extracting to references/. |
plugin-installer from plugin-manager to deploy updated plugins to agent environments.l5-red-team-auditor from agent-plugin-analyzer for full L5 maturity assessment.create-skill from agent-scaffolders to fix scaffolding gaps in audited plugins.npx claudepluginhub richfrem/agent-plugins-skills --plugin plugin-managerAudits agent lifecycles in Claude Code plugins, validating execution capabilities against configs via 8 semantic audits on alignments, skill loading, contracts, prompts, tools, dead agents, and patterns. Writes reports to .claude/audits/.
Audits Claude Code plugins for manifest validity, component organization, namespace compliance, documentation, and marketplace readiness before releases or periodic checks.
Audits plugin skills, commands, and agents for agentic output optimization including missing compact/JSON flags, Agentic Optimizations tables, and stale review dates.