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.