heal-skill — Skillopedia

/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 --- What It Detects Ten checks, run in order: | Code | Issue | Auto-fixable? | |------|-------|---------------| | | No field in SKILL.md frontmatter | Yes -- adds name from directory | | | No field in SKILL.md frontmatter | Yes -- adds placeholder | | | Frontmatter differs from directory name | Yes -- updates to match directory | | | File in references/ not linked in SKILL.md | Yes -- converts…

\"\ncheck \"Codex parity reference exists\" \"[ -f '$SKILL_DIR/references/codex-parity.md' ]\"\ncheck \"SKILL.md links Codex parity reference\" \"grep -q 'references/codex-parity.md' '$SKILL_DIR/SKILL.md'\"\n\necho \"\"; echo \"Results: $PASS passed, $FAIL failed\"\n[ $FAIL -eq 0 ] && exit 0 || exit 1\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":644,"content_sha256":"38d65128ab21a1934ed3d5f84d9efbd297989f8509987856a41aa94261a56e98"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"/heal-skill — Automated Skill Maintenance","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Purpose:","type":"text","marks":[{"type":"strong"}]},{"text":" Detect and auto-fix common skill hygiene issues across the skills/ directory.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.","type":"text","marks":[{"type":"strong"}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Start","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"/heal-skill # Check all skills (report only)\n/heal-skill --fix # Auto-repair all fixable issues\n/heal-skill --strict # Check all skills, exit 1 on findings (CI mode)\n/heal-skill skills/council # Check a specific skill\n/heal-skill --fix skills/vibe # Fix a specific skill","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"What It Detects","type":"text"}]},{"type":"paragraph","content":[{"text":"Ten checks, run in order:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Issue","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auto-fixable?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MISSING_NAME","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No ","type":"text"},{"text":"name:","type":"text","marks":[{"type":"code_inline"}]},{"text":" field in SKILL.md frontmatter","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes -- adds name from directory","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MISSING_DESC","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"code_inline"}]},{"text":" field in SKILL.md frontmatter","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes -- adds placeholder","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"NAME_MISMATCH","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Frontmatter ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" differs from directory name","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes -- updates to match directory","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"UNLINKED_REF","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File in references/ not linked in SKILL.md","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes -- converts bare backtick refs to markdown links","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EMPTY_DIR","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skill directory exists but has no SKILL.md","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes -- removes empty directory","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"DEAD_REF","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SKILL.md references a non-existent references/ file","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No -- warn only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SCRIPT_REF_MISSING","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SKILL.md references a scripts/ file that does not exist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No -- warn only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"INVALID_AO_CMD","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SKILL.md references an ","type":"text"},{"text":"ao","type":"text","marks":[{"type":"code_inline"}]},{"text":" subcommand that does not exist (only runs if ","type":"text"},{"text":"ao","type":"text","marks":[{"type":"code_inline"}]},{"text":" is on PATH)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No -- warn only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"DEAD_XREF","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SKILL.md references a ","type":"text"},{"text":"/skill-name","type":"text","marks":[{"type":"code_inline"}]},{"text":" that has no matching skill directory","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No -- warn only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CATALOG_MISSING","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"A user-invocable skill is missing from the using-agentops catalog","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No -- warn only","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Steps","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Run the heal script","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check mode (default) -- report only, no changes\nbash skills/heal-skill/scripts/heal.sh --check\n\n# Fix mode -- auto-repair what it can\nbash skills/heal-skill/scripts/heal.sh --fix\n\n# Target a specific skill\nbash skills/heal-skill/scripts/heal.sh --check skills/council\nbash skills/heal-skill/scripts/heal.sh --fix skills/council","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1A: Audit Codex Parity Drift When The Codex Bundle Looks Wrong","type":"text"}]},{"type":"paragraph","content":[{"text":"When the problem is not source-skill hygiene but ","type":"text"},{"text":"skills-codex/","type":"text","marks":[{"type":"code_inline"}]},{"text":" drift, run the Codex parity audit first:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bash scripts/audit-codex-parity.sh\nbash scripts/audit-codex-parity.sh --skill swarm","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this when a checked-in Codex skill still contains Claude-era primitives (","type":"text"},{"text":"TaskCreate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"TaskList","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Tool: Task","type":"text","marks":[{"type":"code_inline"}]},{"text":"), Claude backend references, or obviously broken runtime rewrites.","type":"text"}]},{"type":"paragraph","content":[{"text":"Repair rule:","type":"text","marks":[{"type":"strong"}]},{"text":" keep canonical shared behavior in ","type":"text"},{"text":"skills/\u003cname>/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Update ","type":"text"},{"text":"skills-codex/\u003cname>/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the shipped Codex artifact is wrong, and keep durable Codex-only tailoring in ","type":"text"},{"text":"skills-codex-overrides/\u003cname>/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"After repair:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bash scripts/audit-codex-parity.sh\nbash scripts/validate-codex-override-coverage.sh\nbash scripts/validate-codex-generated-artifacts.sh --scope worktree","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Interpret results","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exit 0:","type":"text","marks":[{"type":"strong"}]},{"text":" All clean, no findings. Also exit 0 for ","type":"text"},{"text":"--check","type":"text","marks":[{"type":"code_inline"}]},{"text":" mode with findings (report-only).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exit 1:","type":"text","marks":[{"type":"strong"}]},{"text":" Findings reported with ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag. In ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" mode, fixable issues were repaired; re-run ","type":"text"},{"text":"--check","type":"text","marks":[{"type":"code_inline"}]},{"text":" to confirm.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Report to user","type":"text"}]},{"type":"paragraph","content":[{"text":"Show the output. If ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" was used, summarize what changed. If ","type":"text"},{"text":"DEAD_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":" findings remain, advise the user to remove or update the broken references manually.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output Format","type":"text"}]},{"type":"paragraph","content":[{"text":"One line per finding:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"[MISSING_NAME] skills/foo: No name field in frontmatter\n[MISSING_DESC] skills/foo: No description field in frontmatter\n[NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo'\n[UNLINKED_REF] skills/foo: refs/bar.md not linked in SKILL.md\n[EMPTY_DIR] skills/foo: Directory exists but no SKILL.md\n[DEAD_REF] skills/foo: SKILL.md links to non-existent refs/bar.md\n[SCRIPT_REF_MISSING] skills/foo: references scripts/bar.sh but file not found\n[INVALID_AO_CMD] skills/foo: references 'ao badcmd' which is not a valid subcommand\n[DEAD_XREF] skills/foo: references /nonexistent but skill directory not found\n[CATALOG_MISSING] using-agentops: bar is user-invocable but missing from catalog","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Notes","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The script is ","type":"text"},{"text":"idempotent","type":"text","marks":[{"type":"strong"}]},{"text":" -- running ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" twice produces the same result.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DEAD_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"SCRIPT_REF_MISSING","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"INVALID_AO_CMD","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"DEAD_XREF","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"CATALOG_MISSING","type":"text","marks":[{"type":"code_inline"}]},{"text":" are warn-only because the correct resolution requires human judgment.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"INVALID_AO_CMD","type":"text","marks":[{"type":"code_inline"}]},{"text":" only runs if the ","type":"text"},{"text":"ao","type":"text","marks":[{"type":"code_inline"}]},{"text":" CLI is available on PATH. Skipped silently otherwise.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CATALOG_MISSING","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a global check (not per-skill) and only runs when ","type":"text"},{"text":"using-agentops/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When run without a path argument, scans all directories under ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" for CI gates: exits 1 on any finding. Without ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":", check mode exits 0 even with findings.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For Codex parity drift, use the audit script plus override-layer repair workflow in ","type":"text"},{"text":"references/codex-parity.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/codex-parity.md","title":null}}]},{"text":". The shell fixer is intentionally not allowed to rewrite generated Codex bodies directly.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Running a health check across all skills","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/heal-skill","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"What happens:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The heal script scans every directory under ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":", 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).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Findings are printed one per line with issue codes (e.g., ","type":"text"},{"text":"[NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo'","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The script exits with code 0 in check mode (even with findings), or code 1 with ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" flags.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" A diagnostic report showing all skill hygiene issues across the repository, with no files modified.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Auto-fixing a specific skill","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/heal-skill --fix skills/vibe","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"What happens:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The heal script inspects only ","type":"text"},{"text":"skills/vibe/","type":"text","marks":[{"type":"code_inline"}]},{"text":", running all per-skill checks against that skill.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each fixable issue found (e.g., ","type":"text"},{"text":"MISSING_NAME","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"UNLINKED_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":"), the script applies the repair automatically -- adding the name from the directory, converting bare backtick references to markdown links, etc.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Any ","type":"text"},{"text":"DEAD_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":" findings are reported as warnings since they require human judgment to resolve.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" The ","type":"text"},{"text":"skills/vibe/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is repaired in place, with a summary of changes applied and any remaining warnings.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cause","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Solution","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"DEAD_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":" findings persist after ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Dead references are warn-only because the correct fix (delete, create, or update) requires human judgment","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Manually inspect each dead reference and either create the missing file, remove the link from SKILL.md, or update the path","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Script reports ","type":"text"},{"text":"EMPTY_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a skill in progress","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The skill directory was created but SKILL.md has not been written yet","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Either add a SKILL.md to the directory or remove the empty directory. Running ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" will remove it automatically","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"NAME_MISMATCH","type":"text","marks":[{"type":"code_inline"}]},{"text":" fix changed the wrong name","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The script always updates the frontmatter ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" to match the directory name, not the other way around","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"If the directory name is wrong, rename the directory first, then re-run ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Script exits 0 but a skill still has issues","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The issue type is not one of the ten checks the heal script detects","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The heal script covers structural hygiene only. Content quality issues require manual review or ","type":"text"},{"text":"/council","type":"text","marks":[{"type":"code_inline"}]},{"text":" validation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Running ","type":"text"},{"text":"--fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" twice produces different output","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"This should not happen -- the script is idempotent","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File a bug. Check if another process modified the skill files between runs","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"skills-codex/","type":"text","marks":[{"type":"code_inline"}]},{"text":" keeps regressing after sync","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mechanical conversion is preserving the wrong semantics","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"bash scripts/audit-codex-parity.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":", then move the durable Codex body rewrite into ","type":"text"},{"text":"skills-codex-overrides/\u003cname>/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead of patching generated output","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"See Also","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skill-auditor","type":"text","marks":[{"type":"link","attrs":{"href":"../skill-auditor/SKILL.md","title":null}}]},{"text":" — extends heal's structural checks (Pass 1) with 8 content-discipline checks (Pass 2: rationale, output spec, quality rubric, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skill-builder","type":"text","marks":[{"type":"link","attrs":{"href":"../skill-builder/SKILL.md","title":null}}]},{"text":" — scaffolds new skills against the unified template; runs heal-skill + skill-auditor as self-checks","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/skill-stocktake.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/skill-stocktake.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/codex-parity.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/codex-parity.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/heal-skill.feature","type":"text","marks":[{"type":"link","attrs":{"href":"references/heal-skill.feature","title":null}}]},{"text":" — Executable spec: detect hygiene issues, flag Codex-parity drift, auto-fix + report, --strict fails on remaining findings (soc-qk4b)","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"heal-skill","author":"@skillopedia","source":{"stars":375,"repo_name":"agentops","origin_url":"https://github.com/boshu2/agentops/blob/HEAD/skills/heal-skill/SKILL.md","repo_owner":"boshu2","body_sha256":"97875eb13433ffaddd9add06469a0fdefd6a88049cffe5a2932786ffa3d0bc2a","cluster_key":"8b3509f11bed070699ea04c0a3d0cc141034a58bda4550c57214dab889b9f67b","clean_bundle":{"format":"clean-skill-bundle-v1","source":"boshu2/agentops/skills/heal-skill/SKILL.md","attachments":[{"id":"57f21c9a-ed92-5e11-95e7-256d696b00a1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/57f21c9a-ed92-5e11-95e7-256d696b00a1/attachment.md","path":"references/codex-parity.md","size":2342,"sha256":"bb8cc99e1bf9db690a5fd50d2220893474d754e46ac5064d99d74248f95fa01e","contentType":"text/markdown; charset=utf-8"},{"id":"bc616929-c473-5dc9-b894-e58611f4b77a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bc616929-c473-5dc9-b894-e58611f4b77a/attachment.feature","path":"references/heal-skill.feature","size":1233,"sha256":"12a8d29cc67ab3e9570bf28094643f51384699b3a0043160a27bce8756f65c62","contentType":"text/plain; charset=utf-8"},{"id":"927b4a64-96e8-57c9-b44b-f3b3b346a8fc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/927b4a64-96e8-57c9-b44b-f3b3b346a8fc/attachment.md","path":"references/skill-stocktake.md","size":4679,"sha256":"cb6a19a7698c5049a34d620b882bca370bac610518fd488b114c3da2f77dfd84","contentType":"text/markdown; charset=utf-8"},{"id":"cf740f3f-393c-5343-a625-2252f83ddce0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cf740f3f-393c-5343-a625-2252f83ddce0/attachment.sh","path":"scripts/heal.sh","size":18005,"sha256":"bf1b9b58a046d1f56e5b20211a5cd3da65b32cf341aa358519ee5f3b0cc7b5b5","contentType":"application/x-sh; charset=utf-8"},{"id":"a87a70c3-56fb-5c98-b9cf-77266cfdce54","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a87a70c3-56fb-5c98-b9cf-77266cfdce54/attachment.sh","path":"scripts/validate.sh","size":644,"sha256":"38d65128ab21a1934ed3d5f84d9efbd297989f8509987856a41aa94261a56e98","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"0b59766aa31f4a1894b2dc01308704ee5de965b1cb3cb10a4689fa5796948a94","attachment_count":5,"text_attachments":4,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":1,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/heal-skill/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"general","category_label":"General"},"exact_dupes_collapsed_into_this":0},"context":{"intent":{"mode":"none"},"window":"isolated","sections":{"exclude":["HISTORY","INTEL","TASK"]},"intel_scope":"none"},"version":"v1","category":"general","consumes":[],"metadata":{"tier":"meta","dependencies":[]},"produces":[],"practices":["refactoring","code-complete"],"import_tag":"clean-skills-v1","context_rel":[{"kind":"customer-of","with":"skill-auditor"}],"description":"Repair skill hygiene.","hexagonal_role":"supporting","output_contract":"stdout: heal report, auto-fixed skill files","skill_api_version":1}},"renderedAt":1782981644972}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.