Heal Skill
Repair drift between canonical skills/ SKILL.md and checked-in skills-codex/ runtime artifacts using audit script and durable overrides.
Overview
Heal Skill is an agent skill most often used in Build (also Ship review) that runs Codex parity audits and repairs drift between skills/ canonical SKILL.md and skills-codex/ shipped artifacts.
Install
npx skills add https://github.com/boshu2/agentops --skill heal-skillWhat is this skill?
- Canonical source stays skills/<name>/SKILL.md; Codex ship target is skills-codex/<name>/SKILL.md
- Audit via bash scripts/audit-codex-parity.sh with optional --skill filter
- Flags Claude-era task primitives, backend naming drift, and duplicated runtime phrases
- Durable Codex body edits go to skills-codex-overrides/<name>/SKILL.md
- Codex operator-layer edits go to skills-codex-overrides/<name>/prompt.md plus catalog.json
- Audit script scripts/audit-codex-parity.sh with --skill single-target mode
- Three maintenance surfaces: skills/, skills-codex/, and skills-codex-overrides/
Adoption & trust: 773 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Codex runtime SKILL.md diverged from the canonical skill with Claude-only primitives and garbled replacements, but you are unsure which tree to edit.
Who is it for?
Maintainers of dual-target skill repos (skills/ + skills-codex/) who need a repeatable heal loop after refactors or catalog sync.
Skip if: Greenfield skills with only one agent target, or teams that never ship checked-in skills-codex artifacts.
When should I use this skill?
skills/<name>/SKILL.md is correct but skills-codex/<name>/SKILL.md shows Codex UX drift, duplicated phrases, or Claude-only references after refactors.
What do I get? / Deliverables
After audit-codex-parity.sh, you fix the canonical contract or apply skills-codex-overrides so regenerated Codex bodies match operator expectations.
- Clean audit-codex-parity report for targeted skills
- Updated skills-codex and/or override files aligned to canonical contract
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Codex parity maintenance happens while evolving agent skill packages—primary shelf is Build/agent-tooling for repos that ship dual Claude and Codex surfaces. Focuses on skill runtime contracts, operator prompts, and catalog overrides—not application feature code.
Where it fits
After syncing swarm skill from upstream, audit flags duplicated phrases in skills-codex/swarm/SKILL.md and you patch overrides.
Pre-release review runs audit-codex-parity.sh across the catalog so Claude-only backend names never ship to Codex users.
Operators report confusing Codex prompts; you update skills-codex-overrides/<name>/prompt.md without touching canonical workflow steps.
How it compares
Repo-specific Codex parity maintenance—not a general brainstorming or writing-plans skill for greenfield features.
Common Questions / FAQ
Who is heal-skill for?
Agent skill maintainers on boshu2/agentops-style repos who audit and fix mismatches between skills/ and skills-codex/ plus overrides.
When should I use heal-skill?
In Build when Codex artifacts drift after merges; in Ship/review before publishing a skill pack; and in Operate/iterate when audit-codex-parity reports Claude-era leftovers.
Is heal-skill safe to install?
It runs local bash audit scripts and edits skill markdown; review the Security Audits panel on this Prism page before executing repo scripts in untrusted forks.
SKILL.md
READMESKILL.md - Heal Skill
# Codex Parity Repair Use this workflow when `skills/<name>/SKILL.md` is canonically correct but `skills-codex/<name>/SKILL.md` has drifted into bad Codex UX in the checked-in runtime artifact. ## Principles 1. `skills/<name>/SKILL.md` remains the canonical workflow contract. 2. `skills-codex/<name>/` is the checked-in Codex runtime artifact and may need direct maintenance. 3. Durable Codex-only body edits that should survive broader refactors belong in `skills-codex-overrides/<name>/SKILL.md`. 4. Codex operator-layer prompt edits belong in `skills-codex-overrides/<name>/prompt.md`. ## Audit First Run: ```bash bash scripts/audit-codex-parity.sh ``` Or target one skill: ```bash bash scripts/audit-codex-parity.sh --skill swarm ``` The audit flags the failure classes that Codex maintenance keeps missing today: - Claude-era task primitives - Claude-only backend reference names and team terminology - duplicated runtime phrases created by blind search/replace ## Repair Loop For each flagged skill: 1. Read `skills/<name>/SKILL.md` to confirm whether the canonical contract is correct. 2. Read `skills-codex/<name>/SKILL.md` to see the broken checked-in Codex body. 3. Read `skills-codex-overrides/<name>/prompt.md` and `skills-codex-overrides/catalog.json`. 4. If the source contract is wrong, fix `skills/<name>/SKILL.md` first. 5. If the shipped Codex artifact is wrong, update `skills-codex/<name>/SKILL.md`. 6. If the source is correct but Codex needs a durable tailoring layer, create or update `skills-codex-overrides/<name>/SKILL.md`. 7. Re-run validation: - `bash scripts/audit-codex-parity.sh` - `bash scripts/validate-codex-generated-artifacts.sh --scope worktree` - `bash scripts/validate-codex-override-coverage.sh` ## LLM Repair Guidance When doing the actual rewrite, the LLM should: - preserve the behavior contract from `skills/<name>/SKILL.md` - remove Claude-only primitive/tool names from the Codex body - replace mechanical rewrites with real Codex-native instructions - keep durable Codex-only delta in `skills-codex-overrides/<name>/SKILL.md` when it should remain distinct from the checked-in artifact If a skill keeps needing Codex-only body surgery, update `skills-codex-overrides/catalog.json` so the treatment matches reality instead of pretending the skill is still parity-only. # Executable spec for the /heal-skill skill — skill hygiene repair (BC1 Corpus / Skill Catalog). # /heal-skill detects and auto-fixes common SKILL.md hygiene issues across skills/ (including # unlinked references and Codex-parity drift), then reports what it changed. Hexagon: # supporting; consumes: the skills/ tree; produces: a heal report + auto-fixed skill files. (soc-qk4b) Feature: Heal-skill repairs skill hygiene across the catalog As a catalog maintainer I want common hygiene issues detected and auto-fixed So that skills stay well-formed without manual sweeps Background: Given the skills/ directory with one or more skills Scenario: The heal script detects hygiene issues When /heal-skill runs Then it scans skills for hygiene issues including unlinked references Scenario: Codex parity drift is flagged When the Codex bundle looks wrong Then it audits and reports Codex-parity drift Scenario: Fixable issues are auto-fixed and reported When issues are found Then it auto-fixes the fixable ones and reports what changed Scenario: Strict mode fails on remaining findings When run with --strict Then it reports a non-clean result when unresolved findings remain # Skill Stocktake — AI-Powered Quality Audit > Beyond structural hygiene: evaluate skill quality, actionability, and fitness using AI judgment. ## Problem `heal.sh --strict` catches structural issues (missing frontmatter, unlinked refs, name mismatches). But it can't judge: - Is this skill still actionable and current? - Does it overlap with another skill? - Should it be retired, merged, or improved? - Is it used fre