agentleFS
radiovisualradiovisual/claude-skills/skills/verify-setup/SKILL.md

verify-setup

Skill0 starsChanged 57 days agoMITView on GitHub

Make a repository ready for agent work where every change can be verified. Finds or defines one verify command, writes the CLAUDE.md commands and workflow rules, pre-approves safe commands, installs hooks that block finishing on failing checks and editing secrets or applied migrations, adds CI and a plan-reviewer subagent, then reports what's ready. Run once per project, before plan-verify-fix.

  • Reads credentials
  • Commits and pushes

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Look before proposing anything:

    line 20
  2. Very specific:

    If a check is missing but the tools are already installed (e.g.

    line 42
  3. Very specific:

    Add it as a single entry point where the ecosystem expects one ("verify" in package.json, a make verify target), so humans, hooks and CI …

    line 45
  4. Distinctive:

    Create it or merge into it.

    line 54
  5. Distinctive:

    Leave out rules that don't apply (no migrations, no e2e).

    line 70
  6. Very specific:

    Add to .claude/settings.json (merge with any existing permissions.allow) so the user reviews diffs instead of approval prompts.

    line 74
  7. Distinctive:

    Use the project's real commands.

    line 96
  8. Very specific:

    Test each hook once by piping a sample input into it (a .env path must exit 2, a normal file 0), and tell the user to check /hooks in their …

    line 127
  9. Very specific:

    If .github/workflows/ has no workflow running the verify command, add verify.yml that installs dependencies and runs it on pushes to the …

    line 137

“Common” is measured: kept by at least 6 in 10 of the 4 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

Verify setup

Input: $ARGUMENTS

Make verification cheap before any feature work: one command that proves the project works, and guard rails so agents can't skip it. With --check-only, stop after the readiness report.

Change nothing the user hasn't approved, and never install new tools or dependencies without a yes. Merge into existing files; don't overwrite them.

Phase 1: Inspect

Look before proposing anything:

  • Stack and surfaces: package.json (scripts, TypeScript, test runner), pyproject.toml, go.mod, Cargo.toml, Makefile/justfile, and subfolders with their own config (frontend/, backend/, packages/*).
  • Existing checks: lint, type-check, unit and integration tests, build, end-to-end (Playwright, Cypress).
  • Agent setup: CLAUDE.md, .claude/settings.json, .claude/agents/, .claude/hooks/.
  • CI: .github/workflows/*.
  • Risky areas: .env* files, migration folders, generated code.
  • Visual verification: a Playwright config, or a browser tool available in this session.

Phase 2: Readiness report and choices

Show a checklist of each item below as ✅ present, ⚠️ partial or ❌ missing, with one line on what you'd do. Then ask (AskUserQuestion, multi-select) which items to set up. With --check-only, stop here.

Phase 3: The verify command

The whole setup depends on this one command.

  1. Build it from checks that already exist: lint → type-check → unit tests → build. Run each from the folder where its config lives (cd backend && uv run pytest, not uv run pytest from the root). A monorepo gets one command that runs every surface.
  2. If a check is missing but the tools are already installed (e.g. TypeScript without a typecheck script), offer to add the script (tsc --noEmit). If the tool itself is missing, list it as a gap and ask; don't install it on your own.
  3. Add it as a single entry point where the ecosystem expects one ("verify" in package.json, a make verify target), so humans, hooks and CI run the same thing.
  4. Run it. Report the real result. If it fails on the current code, list the failures as known issues for the user; don't disable or loosen checks to get green.
  5. Separate a fast check (lint, type-check, unit tests; under about a minute) from the full command. The Stop hook uses the fast one.

Phase 4: CLAUDE.md

Create it or merge into it. Keep it short; add only what Claude can't infer from the code:

# Commands
- Verify everything: <verify command>
- Fast check: <fast check>
- E2E: <e2e command, if any>

# Workflow
- Work in small tasks; one task = one commit.
- Before saying a task is done, run the verify command and show its output.
- Fix root causes; never skip, weaken or delete a failing test to get green.
- Never edit an applied migration; add a new one.
- When compacting, keep the list of modified files and the verify command.

Leave out rules that don't apply (no migrations, no e2e). Don't duplicate what's already there.

Phase 5: Permissions

Add to .claude/settings.json (merge with any existing permissions.allow) so the user reviews diffs instead of approval prompts. Use the space form, which also matches the bare command:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint *)",
      "Bash(npm run typecheck *)",
      "Bash(npm test *)",
      "Bash(npm run build *)",
      "Bash(npm run verify *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ]
  }
}

Use the project's real commands. Don't pre-approve git push, deletions, deploys or database commands.

Phase 6: Hooks

Copy the bundled scripts to .claude/hooks/, make them executable, and fill in the placeholders:

  • stop-verify.sh: set FAST_CHECK to the fast check. It runs only when there are uncommitted changes and blocks Claude from finishing while they fail. Claude Code stops honouring a Stop hook after it blocks several times in a row, so a stuck loop can't run forever.
  • protect-files.sh: set MIGRATION_DIRS to the project's migration folders (or leave them out if there are none). It blocks edits to .env files (not .env.example) and to committed migrations. It needs python3 to read the hook input.

Register both in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-verify.sh" }] }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }]
      }
    ]
  }
}

Test each hook once by piping a sample input into it (a .env path must exit 2, a normal file 0), and tell the user to check /hooks in their next session.

Phase 7: Reviewer subagent

Install the plan-reviewer template as .claude/agents/plan-reviewer.md. It reviews diffs against docs/work/<slug>/SPEC.md and PLAN.md with read-only tools, which is what plan-verify-fix expects.

Phase 8: CI

If .github/workflows/ has no workflow running the verify command, add verify.yml that installs dependencies and runs it on pushes to the default branch and on pull requests. Add e2e as a separate job if the project has it. If a workflow exists, add only the missing steps. Use the project's real runtime versions.

Phase 9: Visual verification (report only)

Say which option the project can use for UI checks: existing Playwright tests, a browser tool in Claude Code, or none. Recommend one if needed, but don't install it without a yes.

Phase 10: Wrap up

Report what was set up, the verify command's real output, known failures, and what's still missing. Suggest a trial run: /plan-verify-fix on a trivial change (such as a page title) to see the whole loop pass once. Offer to commit the setup with piv-commit.

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.