validate-cross-refs

Validates cross-reference integrity across Claude Code plugin components and detects orphaned skills.

1|Updated Mar 22, 2026
One-click install
npx skills add https://github.com/JaviMontano/mao-plugin-qa --skill validate-cross-refs-javimontano
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: validate-cross-refs
Source: https://github.com/JaviMontano/mao-plugin-qa/tree/main/skills/validate-cross-refs
Command: npx skills add https://github.com/JaviMontano/mao-plugin-qa --skill validate-cross-refs-javimontano

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Claude Code plugins accumulate broken references as they evolve: agents point to renamed skills, aliases target deleted commands, and orphaned components linger unreferenced. This Skill audits every internal reference so structural errors are caught before they become runtime failures. ## Core Features & Use Cases - Reference Validation: Checks agent-to-skill, command-to-skill, and command-to-agent references against a full component inventory, reporting broken links with file, line number, and edit-distance suggestions. - Alias & Settings Audits: Verifies alias-of targets, detects circular aliases and alias chains, and validates the agent declared in settings.json. - Orphan Detection: Flags skills and agents that exist on disk but are never referenced, plus commands missing from CLAUDE.md documentation. - Use Case: Before publishing a plugin to a marketplace, run this audit to confirm all 20 skills are referenced by agents, all aliases resolve, and no stale entries remain in CLAUDE.md. ## Quick Start Validate all cross-references in my plugin and report any broken references or orphaned components.

Frequently Asked Questions about validate-cross-refs

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

FAQPage Schema
How do I validate cross-references in a Claude Code plugin?▼

Run the validation to build an inventory of skills, agents, and commands, then check every reference between them. Broken references are reported as CRITICAL with the source file, line number, and a suggested correction based on edit distance.

How to detect orphaned skills in a plugin project?▼

A skill is orphaned when no agent file and no command file references it by name. The audit reports each orphaned skill as a WARNING with its path, while commands are never flagged since they are user-invocable entry points.

What happens when an alias command points to a missing command?▼

An alias whose alias-of target does not exist is reported as CRITICAL. Circular aliases (A aliases B, B aliases A) are also CRITICAL, while alias chains longer than one level produce a WARNING recommending direct aliasing.

Does the validation modify any plugin files?▼

No, the validation is strictly read-only. It only reads skill, agent, command, settings.json, and CLAUDE.md files to produce a findings report and never creates or modifies anything.

What are the limitations of orphan detection in plugins?▼

Orphan detection can produce false positives for skills invoked implicitly by convention rather than explicit reference. It also cannot detect runtime references, such as hooks that invoke skills dynamically via environment variables.