/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: Code Issue Auto-fixable? MISSING_NAME No name: field in SKILL.md frontmatter Yes -- adds name from directory MISSING_DESC No description: field in SKILL.md frontmatter Yes -- adds placeholder NAME_MISMATCH Frontmatter name differs from directory name Yes -- updates to match directory UNLINKED_REF File in references/ not linked in SKILL.md Yes -- converts bare backtick refs to markdown links EMPTY_DIR Skill directory exists but has no SKILL.md Yes -- removes empty directory DEAD_REF SKILL.md references a non-existent references/ file No -- warn only SCRIPT_REF_MISSING SKILL.md references a scripts/ file that does not exist No -- warn only INVALID_AO_CMD SKILL.md references an ao subcommand that does not exist (only runs if ao is on PATH) No -- warn only DEAD_XREF SKILL.md references a /skill-name that has no matching skill directory No -- warn only CATALOG_MISSING A user-invocable skill is missing from the using-agentops catalog No -- warn only 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 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. Examples Running a health check across all skills User says: /heal-skill What happens: 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). Findings are printed one per line with issue codes (e.g., [NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo' ). 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: The heal script inspects only skills/vibe/ , running all per-skill checks against that skill. 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. 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 Problem Cause Solution DEAD_REF findings persist after --fix Dead references are warn-only because the correct fix (delete, create, or update) requires human judgment Manually inspect each dead reference and either create the missing file, remove the link from SKILL.md, or update the path Script reports EMPTY_DIR for a skill in progress The skill directory was created but SKILL.md has not been written yet Either add a SKILL.md to the directory or remove the empty directory. Running --fix will remove it automatically NAME_MISMATCH fix changed the wrong name The script always updates the frontmatter name to match the directory name, not the other way around If the directory name is wrong, rename the directory first, then re-run --fix Script exits 0 but a skill still has issues The issue type is not one of the ten checks the heal script detects The heal script covers structural hygiene only. Content quality issues require manual review or /council validation Running --fix twice produces different output This should not happen -- the script is idempotent File a bug. Check if another process modified the skill files between runs