richfrem 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-pluginfromagent-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:
-
descriptionwritten in third person - Includes specific trigger phrases ("Trigger when...")
- Under 1024 characters
-
namematches 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-toolsdeclared 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.jsartifacts, 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=Truein scripts, hardcoded credentials - HIGH — SKILL.md over 500 lines, name convention violations, missing
allowed-tools - MEDIUM — Missing
CONNECTORS.mdfor tool-using plugin, missing fallback-tree - LOW — Missing README, no
repositoryin plugin.json
For L5 maturity scoring, invoke the
l5-red-team-auditoragent fromagent-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-pluginfromplugin-managerto deploy updated plugins to agent environments. - Run
l5-red-team-auditorfromagent-plugin-analyzerfor full L5 maturity assessment. - Run
create-skillfromagent-scaffoldersto fix scaffolding gaps in audited plugins.