/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/validate # 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/councilStep 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 swarmUse 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 worktreeStep 2: Interpret results
- Exit 0: All clean, no findings. Also exit 0 for
--checkmode with findings (report-only). - Exit 1: Findings reported with
--strictor--fixflag. In--fixmode, fixable issues were repaired; re-run--checkto 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
--fixtwice produces the same result. DEAD_REF,SCRIPT_REF_MISSING,INVALID_AO_CMD,DEAD_XREF, andCATALOG_MISSINGare warn-only because the correct resolution requires human judgment.INVALID_AO_CMDonly runs if theaoCLI is available on PATH. Skipped silently otherwise.CATALOG_MISSINGis a global check (not per-skill) and only runs whenusing-agentops/SKILL.mdexists.- When run without a path argument, scans all directories under
skills/. - Use
--strictfor 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:
- 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
--strictor--fixflags.
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/validate
What happens:
- The heal script inspects only
skills/validate/, 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_REFfindings are reported as warnings since they require human judgment to resolve.
Result: The skills/validate/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 |
skills-codex/ keeps regressing after sync | Mechanical conversion is preserving the wrong semantics | Run bash scripts/audit-codex-parity.sh, then move the durable Codex body rewrite into skills-codex-overrides/<name>/SKILL.md instead of patching generated output |
See Also
- skill-auditor — extends heal's structural checks (Pass 1) with 8 content-discipline checks (Pass 2: rationale, output spec, quality rubric, etc.)
- skill-builder — scaffolds new skills against the unified template; runs heal-skill + skill-auditor as self-checks
References
- references/skill-stocktake.md
- references/codex-parity.md
- references/heal-skill.feature — Executable spec: detect hygiene issues, flag Codex-parity drift, auto-fix + report, --strict fails on remaining findings (soc-qk4b)
