maintenance

Audits a Claude plugin for convention drift across skills, commands, hooks, and plugin registration.

6|1|Updated Nov 26, 2025
One-click install
npx skills add https://github.com/nathanvale/side-quest-marketplace-old --skill maintenance-nathanvale
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: maintenance
Source: https://github.com/nathanvale/side-quest-marketplace-old/tree/main/plugins/para-obsidian/skills/maintenance
Command: npx skills add https://github.com/nathanvale/side-quest-marketplace-old --skill maintenance-nathanvale

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Plugin repositories accumulate convention drift over time: skills missing from plugin.json, frontmatter fields that don't match the schema, broken cross-references, and routing tables pointing at deleted components. This Skill automates a read-only audit across 8 domains so maintainers can detect and fix drift before it breaks the plugin. ## Core Features & Use Cases - Plugin Registration Audit: Compares skills, commands, and agents on disk against entries in .claude-plugin/plugin.json, flagging missing registrations and orphaned entries. - Frontmatter & Tooling Validation: Verifies required SKILL.md frontmatter fields (name, description, user-invocable, allowed-tools) and checks that tools referenced in skill bodies match the allowed-tools declaration. - Cross-Reference & Routing Checks: Validates that skill/command/file references resolve, that every user-invocable skill appears in the brain routing table, and that references/ directories contain no dead content. - Observability Audit: Confirms the brain-telemetry PostToolUse hook is registered and that routed skills emit SKILL_RESULT completion signals. - Use Case: After adding a new skill to the para-obsidian plugin, run the audit to confirm it is registered in plugin.json, reachable via brain routing, and emitting a completion signal for telemetry. ## Quick Start Ask the assistant to run a maintenance audit on the para-obsidian plugin and report any convention drift by domain and severity.

Frequently Asked Questions about maintenance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a Claude plugin for convention drift?

Run the maintenance audit, which scans 8 domains: plugin registration, frontmatter schema, completion signals, allowed-tools accuracy, cross-references, brain routing coverage, references directory integrity, and observability gaps. It reports issues grouped by domain with error, warning, or info severity.

How to check that plugin.json matches skills on disk?

The audit globs skills/*/SKILL.md, commands/*.md, and agents/*.md, then compares them against the arrays in .claude-plugin/plugin.json. Components missing from plugin.json are reported as errors, and entries pointing to non-existent paths are flagged as warnings.

What frontmatter fields are required in a SKILL.md file?

Required fields are name, description, user-invocable, and allowed-tools. The name must match the skill's directory name, and user-invocable skills should also include argument-hint, otherwise the audit emits a warning.

Does the maintenance audit modify any plugin files?

No, the audit is strictly read-only. It only detects and reports drift using Glob, Grep, and Read operations, and never edits files. Each reported issue includes a suggested fix for the maintainer to apply manually.

Why does a skill show undefined status in brain telemetry?

A skill shows undefined status when it lacks a SKILL_RESULT completion signal in its SKILL.md. The brain-telemetry PostToolUse hook parses SKILL_RESULT to record status, so skills without it cannot be tracked. The audit flags these as observability warnings.

Can the audit conventions be customized for a plugin?

Yes, the audit reads references/conventions.md as its source of truth before running checks. Updating that file with new rules automatically adapts the audit without changing the SKILL.md instructions.