/heal-skill — Automated Skill Maintenance

Purpose: Detect and auto-fix common skill hygiene issues across the skills/ directory.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Quick Start

/heal-skill                    # Check all skills (report only)
/heal-skill --fix              # Auto-repair all fixable issues
/heal-skill --strict           # Check all skills, exit 1 on findings (CI mode)
/heal-skill skills/council     # Check a specific skill
/heal-skill --fix skills/vibe  # Fix a specific skill

What It Detects

Ten checks, run in order:

Execution Steps

Step 1: Run the heal script

# Check mode (default) -- report only, no changes
bash skills/heal-skill/scripts/heal.sh --check

# Fix mode -- auto-repair what it can
bash skills/heal-skill/scripts/heal.sh --fix

# Target a specific skill
bash skills/heal-skill/scripts/heal.sh --check skills/council
bash skills/heal-skill/scripts/heal.sh --fix skills/council

Step 1A: Audit Codex Parity Drift When The Codex Bundle Looks Wrong

When the problem is not source-skill hygiene but skills-codex/ drift, run the Codex parity audit first:

bash scripts/audit-codex-parity.sh
bash scripts/audit-codex-parity.sh --skill swarm

Use this when a checked-in Codex skill still contains Claude-era primitives (TaskCreate, TaskList, Tool: Task), Claude backend references, or obviously broken runtime rewrites.

Repair rule: keep canonical shared behavior in skills/<name>/SKILL.md. Update skills-codex/<name>/SKILL.md when the shipped Codex artifact is wrong, and keep durable Codex-only tailoring in skills-codex-overrides/<name>/SKILL.md.

After repair:

bash scripts/audit-codex-parity.sh
bash scripts/validate-codex-override-coverage.sh
bash scripts/validate-codex-generated-artifacts.sh --scope worktree

Step 2: Interpret results

• Exit 0: All clean, no findings. Also exit 0 for --check mode with findings (report-only).
• Exit 1: Findings reported with --strict or --fix flag. In --fix mode, fixable issues were repaired; re-run --check to confirm.

Step 3: Report to user

Show the output. If --fix was used, summarize what changed. If DEAD_REF findings remain, advise the user to remove or update the broken references manually.

Output Format

One line per finding:

[MISSING_NAME] skills/foo: No name field in frontmatter
[MISSING_DESC] skills/foo: No description field in frontmatter
[NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo'
[UNLINKED_REF] skills/foo: refs/bar.md not linked in SKILL.md
[EMPTY_DIR] skills/foo: Directory exists but no SKILL.md
[DEAD_REF] skills/foo: SKILL.md links to non-existent refs/bar.md
[SCRIPT_REF_MISSING] skills/foo: references scripts/bar.sh but file not found
[INVALID_AO_CMD] skills/foo: references 'ao badcmd' which is not a valid subcommand
[DEAD_XREF] skills/foo: references /nonexistent but skill directory not found
[CATALOG_MISSING] using-agentops: bar is user-invocable but missing from catalog

Notes

• The script is idempotent -- running --fix twice produces the same result.
• DEAD_REF, SCRIPT_REF_MISSING, INVALID_AO_CMD, DEAD_XREF, and CATALOG_MISSING are warn-only because the correct resolution requires human judgment.
• INVALID_AO_CMD only runs if the ao CLI is available on PATH. Skipped silently otherwise.
• CATALOG_MISSING is a global check (not per-skill) and only runs when using-agentops/SKILL.md exists.
• When run without a path argument, scans all directories under skills/.
• Use --strict for CI gates: exits 1 on any finding. Without --strict, check mode exits 0 even with findings.
• For Codex parity drift, use the audit script plus override-layer repair workflow in references/codex-parity.md. The shell fixer is intentionally not allowed to rewrite generated Codex bodies directly.

Examples

Running a health check across all skills

User says: /heal-skill

What happens:

1. The heal script scans every directory under skills/, checking each for the ten issue types (missing name, missing description, name mismatch, unlinked references, empty directories, dead references, script reference integrity, CLI command validation, cross-reference validation, catalog completeness).
2. Findings are printed one per line with issue codes (e.g., [NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo').
3. The script exits with code 0 in check mode (even with findings), or code 1 with --strict or --fix flags.

Result: A diagnostic report showing all skill hygiene issues across the repository, with no files modified.

Auto-fixing a specific skill

User says: /heal-skill --fix skills/vibe

What happens:

1. The heal script inspects only skills/vibe/, running all per-skill checks against that skill.
2. For each fixable issue found (e.g., MISSING_NAME, UNLINKED_REF), the script applies the repair automatically -- adding the name from the directory, converting bare backtick references to markdown links, etc.
3. Any DEAD_REF findings are reported as warnings since they require human judgment to resolve.

Result: The skills/vibe/SKILL.md is repaired in place, with a summary of changes applied and any remaining warnings.

Troubleshooting

References

• references/skill-stocktake.md
• references/codex-parity.md