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 .agents/skills/maintain-plugins/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:

7 Structural Dimensions:

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 .agents/skills/maintain-plugins/scripts/sync_with_inventory.py --dry-run

Apply Changes

python3 .agents/skills/maintain-plugins/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 .agents/skills/maintain-plugins/scripts/generate_readmes.py --apply

Escalation Taxonomy

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