aeon-skill-repair
Targeted repair for one failing skill. Build a diagnostic dossier, classify the failure, apply the matching playbook, attach a verification recipe.
Inputs
| Param |
Description |
target |
Skill name or SKILL.md path. Required. |
error_output |
Recent failed output (paste from run log). Required if not auto-detectable. |
mode |
repair (default) or dry-run (diagnose only). |
Diagnosis sources
- The skill file (frontmatter, declared sources, env-var references).
- Error output signature (HTTP codes, common API errors, rate-limit hits, refusal markers).
- Source liveness — WebFetch on referenced URLs to detect 404s, redirects, schema changes.
- Frontmatter integrity (valid YAML).
Failure categories and fix scope
| Category |
Detection |
Fix scope |
api-change |
404/410, schema mismatch |
Update endpoints/payload/headers per live spec. Cite the spec URL. |
rate-limit |
429, "too many requests" |
Add backoff or fallback endpoint. Never raise the limit. |
timeout |
Killed mid-run, partial output |
Stage the work, add early-return on partial success. |
sandbox-limitation |
Auth-bearing curl fails |
Convert to prefetch / postprocess pattern. |
prompt-bug |
Hallucination, refusal, missing required section |
Minimum-edit specificity insertion. < 30 lines diff. |
output-format |
Output passes execution but fails downstream parser |
Edit until next run satisfies the failing assertion. |
missing-secret |
"API key missing", env var unset |
No code change. Name the missing var for the operator. Exit REPAIR_DIAGNOSED_NO_FIX. |
config |
Bad input config (watchlist, list file) |
Fix obvious shape errors. Never invent entries. |
unknown |
None of the above |
Don't edit blindly. Append dossier to repair-notes, exit REPAIR_DIAGNOSED_NO_FIX. |
Risk classes
- LOW — fallback added, comment-only, < 30 lines. Auto-applied.
- MED — data source change, output format edit. Auto-applied with verification recipe.
- HIGH — touches behavior fundamentally, changes defaults. Operator review required, not auto-applied.
Verification recipe (every repair)
1. Re-run the skill: <one-line invocation>
2. Expected: <category-specific signal — "no rate-limit in trace" / "≥ 200 words" / "matches pattern X">
3. If still failing: <fallback path>
Cooldown
24h cooldown per skill — prevents repair loops on fixes that didn't stick. State in local repair-history.json.
Rules
- One target per run. Never bundle unrelated repairs.
- Minimum-edit principle. Small diffs.
- Never modify env-var configuration. Missing secrets are flagged for the operator.
- Inside a git repo: branch + diff, never directly to main.
---
name: aeon-skill-repair
description: Diagnoses and fixes failing installed skills by reading the SKILL.md and error output, classifying the failure, applying the smallest fix, and attaching a verification recipe.
---
# aeon-skill-repair
Targeted repair for one failing skill. Build a diagnostic dossier, classify the failure, apply the matching playbook, attach a verification recipe.
## Inputs
| Param | Description |
|---|---|
| `target` | Skill name or SKILL.md path. Required. |
| `error_output` | Recent failed output (paste from run log). Required if not auto-detectable. |
| `mode` | `repair` (default) or `dry-run` (diagnose only). |
## Diagnosis sources
- The skill file (frontmatter, declared sources, env-var references).
- Error output signature (HTTP codes, common API errors, rate-limit hits, refusal markers).
- Source liveness — WebFetch on referenced URLs to detect 404s, redirects, schema changes.
- Frontmatter integrity (valid YAML).
## Failure categories and fix scope
| Category | Detection | Fix scope |
|---|---|---|
| `api-change` | 404/410, schema mismatch | Update endpoints/payload/headers per live spec. Cite the spec URL. |
| `rate-limit` | 429, "too many requests" | Add backoff or fallback endpoint. Never raise the limit. |
| `timeout` | Killed mid-run, partial output | Stage the work, add early-return on partial success. |
| `sandbox-limitation` | Auth-bearing curl fails | Convert to prefetch / postprocess pattern. |
| `prompt-bug` | Hallucination, refusal, missing required section | Minimum-edit specificity insertion. < 30 lines diff. |
| `output-format` | Output passes execution but fails downstream parser | Edit until next run satisfies the failing assertion. |
| `missing-secret` | "API key missing", env var unset | **No code change.** Name the missing var for the operator. Exit `REPAIR_DIAGNOSED_NO_FIX`. |
| `config` | Bad input config (watchlist, list file) | Fix obvious shape errors. Never invent entries. |
| `unknown` | None of the above | Don't edit blindly. Append dossier to repair-notes, exit `REPAIR_DIAGNOSED_NO_FIX`. |
## Risk classes
- **LOW** — fallback added, comment-only, < 30 lines. Auto-applied.
- **MED** — data source change, output format edit. Auto-applied with verification recipe.
- **HIGH** — touches behavior fundamentally, changes defaults. **Operator review required, not auto-applied.**
## Verification recipe (every repair)
```
1. Re-run the skill: <one-line invocation>
2. Expected: <category-specific signal — "no rate-limit in trace" / "≥ 200 words" / "matches pattern X">
3. If still failing: <fallback path>
```
## Cooldown
24h cooldown per skill — prevents repair loops on fixes that didn't stick. State in local `repair-history.json`.
## Rules
- One target per run. Never bundle unrelated repairs.
- Minimum-edit principle. Small diffs.
- Never modify env-var configuration. Missing secrets are flagged for the operator.
- Inside a git repo: branch + diff, never directly to main.
