Agent-Skills.md

Agent Skills: Validating Plugins

Scans all SKILL.md, agent, rules, and plugin manifest files for frontmatter errors, broken links, orphaned files, and invalid variables, generating a Markdown report with targeted fixes. Use when auditing plugin structure after migration or refactoring. Use when user says "validate plugin", "audit skills", "check plugin structure", "run validation after refactor".

UncategorizedID: wayne930242/Reflexive-Claude-Code/validating-plugins
165

Install this agent skill to your local

pnpm dlx add-skill https://github.com/wayne930242/Reflexive-Claude-Code/tree/HEAD/plugins/rcc/skills/validating-plugins

Skill Files

Browse the full folder contents for validating-plugins.

Download Skill

Loading file tree…

plugins/rcc/skills/validating-plugins/SKILL.md

Skill Metadata

Name
validating-plugins
Description
Scans all SKILL.md, agent, rules, and plugin manifest files for frontmatter errors, broken links, orphaned files, and invalid variables, generating a Markdown report with targeted fixes. Use when auditing plugin structure after migration or refactoring. Use when user says "validate plugin", "audit skills", "check plugin structure", "run validation after refactor".

Validating Plugins

Overview

Runs batch structural validation across all plugin components, writes a report, then proposes fixes.

Core principle: Validation should be cheap to run and easy to act on. The report is the source of truth — read it fully before proposing any fixes.

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

  1. Run validator script
  2. Read report
  3. Propose fixes

Announce: "Created 3 tasks. Starting execution..."

Task 1: Run Validator Script

Goal: Execute validate_all.py and capture the report path.

{ command -v uv >/dev/null 2>&1 && uv run "${CLAUDE_SKILL_DIR}/../../hooks/validate_all.py"; } \
  || { python3 --version >/dev/null 2>&1 && python3 "${CLAUDE_SKILL_DIR}/../../hooks/validate_all.py"; } \
  || python "${CLAUDE_SKILL_DIR}/../../hooks/validate_all.py"

Parse stdout for:

  • report:<path> — path to the generated Markdown report
  • issues:<N> files, <M> warnings — summary if issues exist
  • status:clean — no issues

If script fails to run: Check that validate_all.py exists at plugins/rcc/hooks/validate_all.py. If missing, stop and report.

Verification: Script ran, report path captured.

Task 2: Read Report

Goal: Read the full validation report and understand all issues.

Read the file at the report path captured in Task 1.

For each issue entry, note:

  • File path
  • Warning type: extra frontmatter field / broken link / orphaned file / invalid variable / plugin validate
  • Specific value flagged

If no issues (status:clean): Report to user that everything is valid and mark all tasks complete.

Verification: All issues catalogued.

Task 3: Propose Fixes

Goal: For each issue, propose a concrete fix. Group by file.

Fix patterns:

| Warning type | Fix | |---|---| | extra frontmatter field: "X" | Remove field X from frontmatter (or rename if it's a valid field with wrong name) | | broken link: path/to/file.md | Either create the missing file, or remove the dead link from SKILL.md | | orphaned file: path/to/file.md | Either add a markdown link to SKILL.md, or delete the file if unused | | invalid variable: ${CLAUDE_PLUGIN_ROOT} | Replace with ${CLAUDE_SKILL_DIR}/../../ pattern, or move the reference to hooks/hooks.json | | plugin validate: <error> | Fix the specific manifest error reported |

Present fixes grouped by file. For each file, show the exact edit needed (old → new).

Ask user to confirm before applying any fixes.

Verification: User has reviewed and approved (or rejected) proposed fixes.

Red Flags - STOP

  • "Skip reading the full report" — every issue needs to be seen
  • "Fix issues without user approval" — always confirm before editing
  • "Guess what the fix should be" — derive from the warning type table above
  • "Run the script without capturing report path" — the path is needed for Task 2

Common Rationalizations

| Excuse | Reality | |--------|---------| | "The validator already ran clean" | Validator checks structure, not content quality. Manual review catches semantic issues. | | "It's just frontmatter" | Wrong frontmatter means skills don't trigger, agents get wrong tools, hooks don't fire. | | "I'll fix it later" | Invalid plugin files silently degrade. Fix now or users hit confusing errors. | | "Only one file has issues" | One broken link or orphaned file signals systemic neglect. Check everything. |