agentleFS
Schramm2Schramm2/spyglass/skills/maintain-verification-skill/SKILL.md

maintain-verification-skill

Skill0 starsChanged 25 days agoMITView on GitHub

Audit a project's verification skill and feature map against source and live behavior, then deliver proven corrections.

80 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-pstack, ketchup-video and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bnemaSkill

    setup-pstack

    Configure which Pi models pstack uses per role. Detects available provider/model specs and writes pstack's user configuration. Use for /setup-pstack, "configure pstack models", or changing pstack model choices.

    Also in 25 projects that use this

  • tristanphvnSkill

    ketchup-video

    Catch the user up like /keel:ketchup, with a short subtitled video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.

    Also in 13 projects that use this

  • ianclearySkill

    poteto-help

    Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.

    Also in 14 projects that use this

  • eryzerzSkill

    make-bot-ui

    Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.

    Also in 19 projects that use this

  • ianclearySkill

    principle-explain-the-number

    Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.

    Also in 27 projects that use this

  • drafaelSkill

    in-your-own-words

    Restate the user's goals and the problem they are trying to solve to check understanding. Manual invocation only; use when the user explicitly invokes in-your-own-words or requests this understanding check. Do not solve the task or rewrite the assistant's last answer.

    Also in 26 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 8 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 80 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this pass for a project skill with launch and drive steps and a feature map.

    line 9
  2. Distinctive:

    clean: every mapped feature has source and live coverage.

    line 17
  3. Distinctive:

    Keep a product defect separate from the skill outcome.

    line 24
  4. Very specific:

    Find the skill: Read repository instructions and locate the project verification skill.

    line 37
  5. Very specific:

    Read the contract: Read the feature map index, every feature file, the profile, the applicable claim plan, and spyglass --help.

    line 41
  6. Very specific:

    If Spyglass is not installed, follow its README's terminal setup or mark live coverage blocked.

    line 47
  7. Distinctive:

    Plan the live pass: Write claims for every mapped feature and each affected entry point.

    line 53
  8. Very specific:

    Prepare and drive: Use the repository's existing lifecycle tool to prepare an isolated target.

    line 57
  9. Distinctive:

    Prove corrections: After each skill, map, profile, or helper change, repeat the affected live proof on the final source.

    line 76
  10. Distinctive:

    Keep failed attempts and earlier source identity in the report.

    line 80
  11. Very specific:

    Clean up and deliver: Use the owner's cleanup command for owned app, database, and installation resources.

    line 81
  12. Very specific:

    Health: run both owner and Spyglass Doctor before the first drive and after an unexpected failure.

    line 90
  13. Distinctive:

    Stop only resources that this run owns.

    line 97
  14. Distinctive:

    Keep short run notes in a scratch location.

    line 103

“Common” is measured: kept by at least 6 in 10 of the 80 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Maintain a verification skill

Use this pass for a project skill with launch and drive steps and a feature map. The unit of review is the feature: check each map entry against source, then drive each feature live. A source review alone cannot complete the pass.

Outcomes

End with exactly one outcome and name it:

  • clean: every mapped feature has source and live coverage. The skill and map need no correction. Report any product defect separately.
  • changed: proven corrections to the skill, profile, map, or an owned verification helper are live-tested against the final source.
  • blocked: required coverage did not finish, or a correction could not be proved. State the exact missing access, tool, or behavior.

Keep a product defect separate from the skill outcome. This pass does not edit product code or weaken an expected result to hide a defect.

Scope

Edit only verification assets: the skill's SKILL.md and features/, the Spyglass profile and plan that it owns, and its helper scripts. Do not change product code. Report a missing Spyglass capability as an adapter gap for the Spyglass owner. A project-owned helper may fill a narrow gap only when it has a clear owner, repeatable output, and a live proof.

Pass

  1. Find the skill. Read repository instructions and locate the project verification skill. Check .agents/skills/, .claude/skills/, and .cursor/skills/. If several candidates can own the app, ask which one. If none exists, stop and name create-verification-skill.
  2. Read the contract. Read the feature map index, every feature file, the profile, the applicable claim plan, and spyglass --help. Read the installed profile, plan, and result schemas with spyglass schema profile, spyglass schema plan, and spyglass schema result. In the Spyglass source, consult the schema and example files. Use the installed CLI version's syntax. If Spyglass is not installed, follow its README's terminal setup or mark live coverage blocked.
  3. Check the map. Compare every feature with current source. Fix missing, extra, duplicate, or dead index entries. Check recent changes for affected user-facing routes, commands, and consumers that the map omits. Cite the concrete source path for each suspected gap.
  4. Plan the live pass. Write claims for every mapped feature and each affected entry point. Include preconditions, expected results, relevant failure cases, named checks, and evidence. List exclusions with reasons. Group overlapping recipes so one prepared state can cover them safely.
  5. Prepare and drive. Use the repository's existing lifecycle tool to prepare an isolated target. Keep its Doctor and Cleanup authoritative. Bind the target to Spyglass and record the owner's results. Run both Doctors before driving. Drive every mapped feature at least once and every affected path. Wait for asynchronous work to finish. Read side effects separately. Open and inspect actual screenshots for visual claims; record viewport, expected state, and observed state.
  6. Triage each failure.
    • Map drift: source shows the app's working user path changed, while the feature map or recipe still names the old path. Update the map or recipe, then drive the new path.
    • Adapter gap: the user behavior works, but Spyglass or its configured browser, API, or command adapter cannot drive or observe it. Keep the expected result. Fix a narrow owned helper when that is within scope; otherwise report the missing capability and mark its claim blocked.
    • Product defect: the app fails the existing expected result. Keep that expectation unchanged. Record the failed claim and report the product defect separately; do not edit product code or relabel the failure as map drift.
  7. Prove corrections. After each skill, map, profile, or helper change, repeat the affected live proof on the final source. If a verification claim or check changed, run a safe negative control that fails its intended assertion, restore the target, and show that the same expectation passes. Keep failed attempts and earlier source identity in the report.
  8. Clean up and deliver. Use the owner's cleanup command for owned app, database, and installation resources. Then clean up Spyglass's resources. Confirm the report and evidence remain after cleanup. Re-read each changed file. Follow the repository's Git flow and report the diff, evidence, coverage, limits, cleanup, and final outcome. Leave changes uncommitted when the repository or task gives no authority to commit.

Live-pass invariants

  • Health: run both owner and Spyglass Doctor before the first drive and after an unexpected failure. Reset a stuck UI to a known state or relaunch the owner-managed target before retrying.
  • Evidence: each passed claim cites completed steps and evidence from the same source. A visual claim cites an inspected image. A side-effect claim cites its independent read. Check that evidence remains after cleanup.
  • No residue: clean up every failed or completed target through its owner. Stop only resources that this run owns. Retain proof while removing runtime state.
  • No false pass: a process that accepts connections is not ready until the owner's readiness check passes. A request accepted with 202 is not a completed action. A screenshot or green exit code alone is not a claim.

Keep short run notes in a scratch location. Record features covered, blocked preconditions, drift, adapter gaps, product defects, cleanup, and the selected outcome. Do not commit those scratch notes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.