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
- Search before creating or moving skill files.
- Read the target skill and nearby docs that define its expected workflow.
- 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.
- Score the five contract elements as
present, partial, missing, or deferred.
- 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.
- 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:
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:
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.
1---2name: skill-lifeguard3description: Use when a skill is brittle, drifting, repeatedly failing, or needs a Reliable Skill Contract. Trigger for phrases like skill lifeguard, reliable skill, self-maintaining skill, negative examples, verification checkpoints, drift signals, replay hooks, or failure log to skill patch. Audits or patches skills so high-value workflows include explicit forbidden behaviors, checkpoints, machine-checkable done conditions, replay or smoke hooks, and drift detection.4---5
6# Skill Lifeguard
7
8Use this skill to make an existing or new skill self-maintaining enough for real
9agent work. It complements `skill-audit` and `skill-creator`: use this skill for
10the reliability contract, then use those skills for library fit and authoring.
11
12Read `references/examples.md` when you need example contract wording. Use
13`assets/reliable-contract-template.md` when drafting a reusable section.
14
15## Reliable Skill Contract
16
17Every high-value workflow skill should either include these five elements or
18record why an element is intentionally deferred:
19
20| Element | Required Evidence |
21| --- | --- |
22| Explicit negative examples | Named forbidden behaviors and concrete alternatives. |
23| Verification checkpoints | Pass/fail checks after important phases, not only at the end. |
24| Machine-checkable done conditions | Commands, assertions, artifacts, or state queries from the current session. |
25| Replay or smoke hooks | A small way to rerun or sample the workflow, plus a log-to-patch loop. |
26| Drift signal detection | Observable signs that the skill is stale, undertriggering, overtriggering, or producing false success. |
27
28## Workflow
29
301. Search before creating or moving skill files.
312. Read the target skill and nearby docs that define its expected workflow.
323. Classify the skill maturity:
33 - `manual`: workflow still needs human validation.
34 - `skill`: manually validated and packaged as reusable instructions.
35 - `automation`: repeatedly reliable and safe enough for scheduled or hook-driven use.
364. Score the five contract elements as `present`, `partial`, `missing`, or `deferred`.
375. Patch the smallest durable home: `SKILL.md` for routing and boundaries,
38 `references/` for long examples, `scripts/` for deterministic checks,
39 `assets/` or `templates/` for reusable report shapes.
406. Run repository validation and any skill-specific smoke check.
41
42## Operating Contract
43
44- Direct actions: audit skill files, draft contract gaps, patch local skill
45 instructions, and run local validation.
46- Escalate before: publishing skills, installing into user runtime directories,
47 deleting user files, changing secrets, or promoting manual workflows into
48 scheduled automation.
49- Evidence-backed pushback: refuse reliability claims that lack fresh
50 verification, replay hooks, or drift signals.
51- Feedback loop: turn repeated corrections, false-success signals, or failed
52 smoke runs into a skill patch and rerun validation.
53
54## Gotchas
55
56- A checklist without pass/fail evidence is not a checkpoint.
57- A warning-only fallback can hide missing data; fail loud when output would be
58 incomplete or misleading.
59- A one-time successful manual run is not automation maturity.
60
61## Output
62
63For audits, lead with findings:
64
65```text
66reliable_skill_contract:
67- target:
68- maturity:
69- score:
70 negative_examples:
71 verification_checkpoints:
72 machine_done_conditions:
73 replay_or_smoke_hooks:
74 drift_signals:
75- blocking_gaps:
76- patch_plan:
77- verification:
78```
79
80For edits, keep the patch scoped to the missing contract elements. Do not
81rewrite the skill's domain behavior unless the reliability gap requires it.
82
83## Negative Examples
84
85Reject these patterns and name the safer alternative:
86
87- "Verify by saying it should work." Use a fresh command, fixture, or state
88 query instead.
89- "Swallow a failed helper and continue with a generic fallback." Surface the
90 failure or mark the workflow blocked.
91- "Add a broad reminder to be careful." Add a concrete forbidden behavior and
92 an allowed replacement.
93- "Automate a workflow that has never passed manually." Keep it in `manual`
94 maturity and add smoke checks first.
95
96## Checkpoints
97
98Place checkpoints where a future agent could otherwise drift:
99
100- after startup discovery and applicable instructions are read
101- before edits that touch high-context files or generated metadata
102- after each deterministic verification command
103- before commit, push, PR, merge, or automation
104- after a failure log produces a skill patch
105
106## Drift Signals
107
108Treat these as evidence to patch the skill:
109
110- users repeat the same correction
111- the skill triggers for the wrong task boundary
112- the skill fails to trigger for its primary phrase
113- the expected verification command no longer exists
114- output format changes without downstream docs or examples changing
115- a silent fallback hides missing data, auth, files, or external state
116
117## Verification
118
119For Spellbook skills, run:
120
121```bash
122python3 ./scripts/validate_skills.py --check
123python3 ./scripts/audit_skill_quality.py skill-name
124```
125
126If the skill owns scripts, also run the relevant syntax check or fixture. Report
127missing prerequisites instead of marking the contract complete.
majiayu000