heal-skill

/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.

Constraints

• Resolve every explicit target to a real direct child of skills/ or skills-codex/ before processing; reject traversal, missing/outside paths, and every symlink spelling because aliases make mutation ownership ambiguous.
• Run --check and deep audit read-only before any repair, because their exact finding codes and target path define the permitted mutation.
• Use --fix only for the documented auto-fixable structural codes, then rerun strict validation; never hand-edit generated Codex artifacts because parity projections have owned regeneration paths.
• Treat WARN/FAIL as ordinary repair evidence: redo and re-audit automatically while the breaker remains closed; only a breaker enters HOLD/helper routing, because a plain refutation is not an andon.

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
 
bash skills/heal-skill/scripts/audit.sh skills/council   # Deep audit (read-only; see "Deep audit mode" below)

What It Detects

Auto-fix allowlist and principal diagnostics:

CATALOG_MISSING was removed: it only ran when skills/using-agentops/SKILL.md existed, and that skill is gone. Catalog completeness is gated by MISSING_DISPOSITION against docs/contracts/skill-dispositions.yaml.

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

Checkpoint: before accepting any mutation, confirm the target path and finding code are present in the read-only report and the code is documented as auto-fixable.

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

Checkpoint: after a Codex repair, require parity, override coverage, and generated-artifact validation to exit zero before reporting the runtime bundle healthy.

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

Artifact directory: stdout for human findings; .agents/audits/ for JSON reports. Filename convention: <skill>-audit.json. Serialization/schema format: JSON matching schemas/audit-report.json. Validator command: jq -e . .agents/audits/<skill>-audit.json. Downstream handoff: consumed by the validation wave before repair.

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

Deep audit mode (absorbed from /skill-auditor)

Requests for /skill-auditor route here: the audit is the detect phase of heal, and it lives at scripts/audit.sh. Unlike --fix, the audit is read-only — it reports; repairs go through heal.sh --fix (Pass-1 issues) or hand edits (Pass-2 issues).

bash skills/heal-skill/scripts/audit.sh [--strict] [--json <path>] skills/<name>

Two passes, then an aggregate verdict:

• Pass 1 — structural (delegated): runs heal.sh --check --strict <target> and gates on its exit code; it never reimplements the hygiene checks (heal is the source of truth). A strict failure forces the aggregate verdict to FAIL but does NOT short-circuit Pass 2.
• Pass 2 — content discipline: 8 checks in audit.sh (triggers, frontloaded constraints, rationale, checkpoints, output spec, quality rubric, references modularization, trigger clarity). Definitions and accepted forms: references/audit-checks.md [blocked].
• Verdict aggregation: any check fail → FAIL; otherwise any warn → WARN; otherwise PASS. Max-severity wins — no silent downgrade. Exit 0 on PASS/WARN (1 on WARN under --strict), 1 on FAIL, 2 on usage error.
• 0-30 rubric (Pass 3) is ADVISORY-only: scripts/score_agentops_skill.py --audit-block folds a deterministic 10-category score (band C/B/A/S) into the report under rubric. It never changes the PASS/WARN/FAIL verdict — it is a productization backlog signal, not a ship blocker. The density block (references/context-density-checks.md [blocked]) is advisory too.
• Accepted trigger forms: description-has-triggers accepts only the forms declared by the authoritative repo-runtime profile (finding f-2026-05-06-auditor-checks-must-fit-host-conventions — audit checks must fit the host's existing valid conventions).

Report JSON conforms to schemas/audit-report.json [blocked]; skill-builder owns the canonical SKILL.md template. Executable spec: references/skill-auditor.feature [blocked].

Notes

• The script is idempotent -- running --fix twice produces the same result.
• Explicit targets contain mutation: --fix skills/foo may change foo only; source siblings remain byte-identical.
• DEAD_REF, SCRIPT_REF_MISSING, INVALID_AO_CMD, and DEAD_XREF 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.
• 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 [blocked]. The shell fixer is intentionally not allowed to rewrite generated Codex bodies directly.

Quality Checklist

• Scope fidelity: every changed path is the audited target or its owned parity projection, and every repair maps to a reported finding code.
• Verification quality: strict heal/deep-audit and applicable Codex parity commands rerun after mutation with zero unresolved findings.
• Idempotence: a second identical repair run produces no additional diff, while non-auto-fixable findings remain explicit rather than guessed through.

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 nine issue types (missing name, missing description, name mismatch, unlinked references, empty directories, dead references, script reference integrity, CLI command validation, cross-reference validation).
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/validate

What happens:

1. The heal script inspects only skills/validate/, 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/validate/SKILL.md is repaired in place, with a summary of changes applied and any remaining warnings.

Troubleshooting

See Also

• skill-builder — scaffolds new skills against the unified template; runs heal-skill (hygiene + deep audit) as self-checks
• red-team — complementary; probes USABILITY (does the workflow actually work) vs the audit (is the structure correct)

References

• skill-conformance-profiles.yaml — authoritative rules, severities, and boundary

• references/skill-stocktake.md [blocked]

• references/codex-parity.md [blocked]

• references/heal-skill.feature [blocked] — Executable spec: detect hygiene issues, flag Codex-parity drift, auto-fix + report, --strict fails on remaining findings (soc-qk4b)

• references/audit-checks.md [blocked] — deep-audit Pass-2 check definitions + accepted forms + PRODUCT.md mapping

• references/context-density-checks.md [blocked] — advisory density coverage logic and false-positive handling

• references/skill-auditor.feature [blocked] — Executable spec for the absorbed deep audit mode: Pass 1 heal delegation, Pass 2 content checks, density report + productization score (soc-qk4b)