heal-skill

Savant verdict: Review advised

Security analysis or source-hub review identified patterns requiring attention.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• 4 referenced files aren't in the packagereferences/heal-skill.feature, references/skill-auditor.feature, references/heal-skill.featu, references/skill-auditor.featu. They may be binary, too large to catalog, or missing upstream.
• Ships 5 executable scriptsscripts/audit.sh, scripts/heal.sh, scripts/score_agentops_skill.py, scripts/test-mutation-boundaries.sh, scripts/validate.sh. Review what they do before enabling the skill for agents with tool access.
• No license declaredConfirm you may reuse this skill before importing it into your repository.
• The source hub's security checks flagged this skillRunlayer: warn (2/3 files flagged)

SKILL.md

---
name: heal-skill
description: 'Check or repair structural hygiene in AgentOps skill packages. Triggers: "heal skill", "repair skill hygiene", "audit skill structure", "check skill package".'
practices:
- refactoring
hexagonal_role: supporting
consumes: []
produces:
- skill-hygiene-report
context_rel:
- kind: customer-of
  with: skill-builder
skill_api_version: 1
context:
  window: isolated
  intent:
    mode: none
  sections:
    exclude: [HISTORY, INTEL, TASK]
  intel_scope: none
metadata:
  capabilities: [heal_skill]
  effects: [optional_skill_projection_repair]
  canonical_status: canonical
  disposition: keep_specialist
  tier: meta
  dependencies: []
output_contract: skills/heal-skill/schemas/audit-report.json
---

# /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
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
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](references/audit-checks.md); density scoring is described in
[context-density-checks.md](references/context-density-checks.md).

## Output

Structural findings are printed as:

```text
[FINDING_CODE] skills/example: concrete explanation
```

Deep audit JSON conforms to [audit-report.json](schemas/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](references/codex-parity.md).
- Remaining non-fixable findings stay explicit.

## Related executable specifications

- [heal-skill.feature](references/heal-skill.feature)
- [skill-auditor.feature](references/skill-auditor.feature)