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:

• description written in third person

• Includes specific trigger phrases ("Trigger when...")

• Under 1024 characters

• name matches directory name (kebab-case, lowercase)

SKILL.md Body Structure Checks:

• Clear numbered phases or execution steps

• Uses Recap-Before-Execute for destructive operations

• Tables used for structured comparisons

• Links to references/ for deep content (not inline)

• allowed-tools declared if tool-restricted

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.