majiayu000/spellbook / skills/skill-lifeguard
skill-lifeguard
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| assets/reliable-contract-template.md | markdown | 424 B |
| references/examples.md | markdown | 1.5 KB |
SKILL.md
View on GitHub---
name: skill-lifeguard
description: "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."
---
# 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.
4. Score the five contract elements as `present`, `partial`, `missing`, or `deferred`.
5. 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.
6. 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |