| name | maintain-plugins |
| description | 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.
|
| allowed-tools | Bash, Write, Read |
Plugin Maintenance
Overview
This skill is the ecosystem health hub. It covers three operations:
- Audit — structural compliance checking against Open Standards
- Sync — keep agent environments in sync with
plugins/, cleaning up orphaned artifacts
- README — scaffold missing documentation
Core constraint: Custom, project-specific plugins are NEVER deleted during sync. Only vendor-managed plugins that have been locally removed are cleaned up.
References
- Sync process guide:
../../references/cleanup_process.md
- Sync flow diagram:
../../references/cleanup_flow.mmd
Execution Protocol
CRITICAL: Do not immediately generate bash commands. Operate as an interactive assistant.
Phase 1: Guided Discovery
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
Phase 2: Recap-Before-Execute
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.
Phase 3: Command Execution
Wait for explicit confirmation (yes, looks good, ok).
[Audit] Structural Compliance Check
Step 1: Run Deterministic Scanner
python3 ./scripts/audit_structure.py
For deeper semantic + security checks, invoke analyze-plugin from agent-plugin-analyzer.
Step 2: Manual Audit Checklist (if script unavailable)
For 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:
SKILL.md Body Structure Checks:
Three Compliance Absolutes (from Open Standards):
- All skills MUST end with a Source Transparency Declaration if querying external sources
- If plugin generates
.html, .svg, or .js artifacts, MUST implement Client-Side Compute Sandbox (hardcoded loop bounds) + XSS Compliance Gate (no external script tags)
- Sub-agents MUST have an explicit
tools: allowlist
Step 3: Flag and Report
For each violation found, report with severity:
- CRITICAL — Missing
plugin.json, shell=True in scripts, hardcoded credentials
- HIGH — SKILL.md over 500 lines, name convention violations, missing
allowed-tools
- MEDIUM — Missing
CONNECTORS.md for tool-using plugin, missing fallback-tree
- LOW — Missing README, no
repository in plugin.json
For L5 maturity scoring, invoke the l5-red-team-auditor agent from agent-plugin-analyzer.
[Sync] Agent Environment Synchronization
Preview Changes (Always Run First)
python3 ./scripts/sync_with_inventory.py --dry-run
Apply Changes
python3 ./scripts/sync_with_inventory.py
Post-Sync Verification
- Check
local-plugins-inventory.json (generated in project root) for current state.
- Confirm custom plugins (not in vendor list) still present in
plugins/.
- Confirm artifacts for removed vendor plugins are gone from
.agent, .gemini, etc.
[README] Generate Missing Documentation
python3 ./scripts/generate_readmes.py --apply
Escalation Taxonomy
| 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/. |
When to Use
- After adding a new plugin — run Audit to verify correct structure
- After removing a vendor plugin — run Sync to clean orphaned agent artifacts
- Periodically — to catch drift or accidental file placements
- Before a release — to ensure clean distribution state
Next Actions
- Run
bridge-plugin from plugin-manager to deploy updated plugins to agent environments.
- Run
l5-red-team-auditor from agent-plugin-analyzer for full L5 maturity assessment.
- Run
create-skill from agent-scaffolders to fix scaffolding gaps in audited plugins.
