maintain-plugins

Dependencies

This 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).

---

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: cleanup_process.md
• Sync flow diagram: 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 1.5: Path Portability Audit

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:

• Self-referential absolute paths (plugins/<name>/scripts/foo.py → ./scripts/foo.py)
• Environment-specific .agents/skills/<skill>/scripts/ paths that break on reinstall
• Absolute machine paths (/Users/<name>/...) that break portability across machines

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):

1. All skills MUST end with a Source Transparency Declaration if querying external sources
2. If plugin generates .html, .svg, or .js artifacts, MUST implement Client-Side Compute Sandbox (hardcoded loop bounds) + XSS Compliance Gate (no external script tags)
3. Sub-agents MUST have an explicit tools: allowlist

Step 3: Flag and Report

For each violation found, report with severity:

• CRITICAL — Missing ../../../.claude-plugin/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

1. Check local-plugins-inventory.json (generated in project root) for current state.
2. Confirm custom plugins (not in vendor list) still present in plugins/.
3. 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 + Path Portability 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 and path portability regressions
• Before a release — to ensure clean distribution state (both structure and path audits must pass)

Next Actions

• Run plugin-installer 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.