Skill Lifeguard

Use this skill to make an existing or new skill self-maintaining enough for real agent work. It complements skill-audit and skill-creator: use this skill for the reliability contract, then use those skills for library fit and authoring.

Read references/examples.md when you need example contract wording. Use assets/reliable-contract-template.md when drafting a reusable section.

Reliable Skill Contract

Every high-value workflow skill should either include these five elements or record why an element is intentionally deferred:

| Element | Required Evidence | | --- | --- | | Explicit negative examples | Named forbidden behaviors and concrete alternatives. | | Verification checkpoints | Pass/fail checks after important phases, not only at the end. | | Machine-checkable done conditions | Commands, assertions, artifacts, or state queries from the current session. | | Replay or smoke hooks | A small way to rerun or sample the workflow, plus a log-to-patch loop. | | Drift signal detection | Observable signs that the skill is stale, undertriggering, overtriggering, or producing false success. |

Workflow

1. Search before creating or moving skill files.
2. Read the target skill and nearby docs that define its expected workflow.
3. Classify the skill maturity:

• manual: workflow still needs human validation.
• skill: manually validated and packaged as reusable instructions.
• automation: repeatedly reliable and safe enough for scheduled or hook-driven use.

1. Score the five contract elements as present, partial, missing, or deferred.
2. Patch the smallest durable home: SKILL.md for routing and boundaries,

references/ for long examples, scripts/ for deterministic checks, assets/ or templates/ for reusable report shapes.

1. Run repository validation and any skill-specific smoke check.

Operating Contract

• Direct actions: audit skill files, draft contract gaps, patch local skill

instructions, and run local validation.

• Escalate before: publishing skills, installing into user runtime directories,

deleting user files, changing secrets, or promoting manual workflows into scheduled automation.

• Evidence-backed pushback: refuse reliability claims that lack fresh

verification, replay hooks, or drift signals.

• Feedback loop: turn repeated corrections, false-success signals, or failed

smoke runs into a skill patch and rerun validation.

Gotchas

• A checklist without pass/fail evidence is not a checkpoint.
• A warning-only fallback can hide missing data; fail loud when output would be

incomplete or misleading.

• A one-time successful manual run is not automation maturity.

Output

For audits, lead with findings:

text
reliable_skill_contract:
- target:
- maturity:
- score:
  negative_examples:
  verification_checkpoints:
  machine_done_conditions:
  replay_or_smoke_hooks:
  drift_signals:
- blocking_gaps:
- patch_plan:
- verification:

For edits, keep the patch scoped to the missing contract elements. Do not rewrite the skill's domain behavior unless the reliability gap requires it.

Negative Examples

Reject these patterns and name the safer alternative:

• "Verify by saying it should work." Use a fresh command, fixture, or state

query instead.

• "Swallow a failed helper and continue with a generic fallback." Surface the

failure or mark the workflow blocked.

• "Add a broad reminder to be careful." Add a concrete forbidden behavior and

an allowed replacement.

• "Automate a workflow that has never passed manually." Keep it in manual

maturity and add smoke checks first.

Checkpoints

Place checkpoints where a future agent could otherwise drift:

• after startup discovery and applicable instructions are read
• before edits that touch high-context files or generated metadata
• after each deterministic verification command
• before commit, push, PR, merge, or automation
• after a failure log produces a skill patch

Drift Signals

Treat these as evidence to patch the skill:

• users repeat the same correction
• the skill triggers for the wrong task boundary
• the skill fails to trigger for its primary phrase
• the expected verification command no longer exists
• output format changes without downstream docs or examples changing
• a silent fallback hides missing data, auth, files, or external state

Verification

For Spellbook skills, run:

bash
python3 ./scripts/validate_skills.py --check
python3 ./scripts/audit_skill_quality.py skill-name

If the skill owns scripts, also run the relevant syntax check or fixture. Report missing prerequisites instead of marking the contract complete.