mcpField
H
heal-skill

heal-skill

github.com/boshu2Agent workflows4501.2k installsUpdated today
Repository

About heal-skill

heal-skill is a command-line skill hygiene checker for maintainers of skill packages. It reports structural issues and can regenerate owned metadata and Codex projections without changing unrelated files.

Key features

  1. 01Read-only structural checks
  2. 02Strict mode returns failure on findings
  3. 03Repairs owned projections through generators
  4. 04Optional content audit with JSON output
  5. 05Idempotent repeated fixes

Use cases

  1. 01Check SKILL.md metadata before release
  2. 02Repair generated Codex twins
  3. 03Audit skill authoring quality
  4. 04Inspect findings in machine-readable form

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/boshu2/agentops --skill heal-skill

After installing, type/heal-skillin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
audit-checks.md
codex-parity.md
context-density-checks.md
heal-skill.feature
skill-auditor.feature
schemas/
audit-report.json
scripts/
audit.sh
heal.sh
score_agentops_skill.py
test-mutation-boundaries.sh
validate.sh

Details

From the project README

/heal-skill — Check one or more skill packages

heal-skill is a specialist hygiene tool. It reports structural defects in canonical source skills and generated Codex twins. With --fix, it repairs only owned projections through their generators. It does not schedule work, operate Git, validate a software candidate, or decide what happens after a failure.

Inputs

bash skills/heal-skill/scripts/heal.sh --check [skills/<slug> ...]
bash skills/heal-skill/scripts/heal.sh --check --strict [skills/<slug> ...]
bash skills/heal-skill/scripts/heal.sh --fix [skills/<slug> ...]

Every explicit target must be a real, direct child of skills/ or skills-codex/. Missing paths, traversal, and symlink spellings are rejected.

Procedure

  1. Resolve and contain all requested target directories.
  2. Parse each SKILL.md frontmatter.
  3. Check the path/name match, description, API version, disposition metadata, and linked local references.
  4. Print every finding once.
  5. In --fix mode only, regenerate metadata-owned projections and scoped Codex twins, then stop.

--check is read-only. --strict makes any finding produce exit 1. A failed fix is returned to the caller; the skill does not retry or select another action.

Deep content audit

The optional read-only content audit is:

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

It combines the structural result with deterministic authoring checks and an advisory quality score. It is not the core Validate phase, does not write a verdict.v2, and has no delivery authority. Check definitions live in audit-checks.md; density scoring is described in context-density-checks.md.

Output

Structural findings are printed as:

[FINDING_CODE] skills/example: concrete explanation

Deep audit JSON conforms to audit-report.json. The caller owns any subsequent edit or invocation.

Checks

  • Check mode never mutates files.
  • Fix mode changes only an explicit source target and its owned projections.
  • A second identical fix is idempotent.
  • Generated Codex parity follows codex-parity.md.
  • Remaining non-fixable findings stay explicit.

Related executable specifications

Comments

Markdown supported