gaia-self-check

Gaia Self-Check

Overview

Validates the internal consistency of a Gaia installation by inspecting only .claude/ on disk. The skill has one job: inventory the components, compare their declared state against their physical state, and surface discrepancies. It never reaches outside the installation -- no external repo, no network, no cloud API.

The principle that keeps this skill safe is ask-before-fix: the skill may detect a broken cross-reference and know exactly how to repair it, but it never applies the fix on its own. Every proposed change is presented to the user as a concrete propuesta and waits for explicit aprobación before any edit happens.

When to activate

The user says things like:

• "check gaia", "valida consistencia", "audita la instalación"
• "mis skills están rotas?", "hay referencias colgantes?"
• "gaia self-check", "self-check", "sanity check de .claude"

If the intent is to verify the install pipeline (npm, dry-run, beta, release), that is gaia-verify, not this skill. If the intent is to diagnose a symlink or path problem at the CLI level, that is gaia-doctor.

The 3-step cycle

Every run follows the same three phases. Detailed operational instructions for each phase live in reference.md.

1. Inventario

Walk .claude/skills/, .claude/agents/, .claude/commands/ and build a list of every component present. Read each component's frontmatter and record declared metadata (name, description, references). Hooks are only inventoried if settings.json references them. Nothing outside .claude/ is touched.

[expanded in T2 -- details on which directories to scan and how to parse frontmatter tolerantly]

2. Checks de consistencia

For each component, compare declared state against physical state. The categories of checks are:

• Frontmatter validity -- YAML parses, required fields present.
• Name vs dirname -- the name field matches the directory or file name.
• Cross-references -- skill-to-skill or agent-to-skill references point to components that exist physically.
• Routing consistency -- agents mentioned in routing config exist.
• README listings -- if a README exists, listed files are present and present files are listed.

[expanded in T2 -- full per-category check rules and report format]

3. Propuesta con aprobación

For every inconsistency found, build a concrete propuesta: which file, what change, what effect. Present the list to the user and wait for explicit aprobación per item (or a global confirmation if the mechanism does not support per-item). Record which fixes were aprobado and which were rechazado. Never apply a change without this approval step -- that is the ask-before-fix guard.

[expanded in T3 -- full propuesta format, approval mechanism, handling of ambiguous cases]

Operating principle: ask-before-fix

The skill is allowed to be wrong. A proposed fix may misread the user's intent, may touch a file the user wanted stale on purpose, or may conflict with an in-flight change. The ask-before-fix principle exists precisely because the skill cannot distinguish "inconsistency" from "deliberate deviation" on its own.

Practical consequence: the output of this skill is always a report + a list of propuestas, never a mutated file. The skill surfaces findings and waits. The user decides.

Output shape

The terminal output is the report. Structure and examples live in reference.md under "Output Format". The short version: one table per category, columns for component, type, inconsistencia, and fix propuesto.

Out of scope

• Anything outside .claude/ -- no cloning repos, no fetching remotes.
• Running tests or builds -- consistency checks only, no execution.
• Applying fixes automatically -- ask-before-fix applies always.
• Network access of any kind.

Anti-patterns

• Auto-fixing "obvious" issues -- every auto-fix bypasses ask-before-fix and teaches the skill that some categories of change are safe to take unilaterally. None are.
• Hard-failing on one bad frontmatter -- one malformed YAML should be reported as an inconsistency, not stop the whole scan.
• Cross-referencing external state -- the moment the skill reads outside .claude/, it stops being a self-check and becomes an environment audit.
• Silent propuestas -- a fix that is not shown to the user in human-readable form cannot be aprobado with informed consent.