Agent skill

Make your agent's work verifiable in your repo

A skill that audits your repo and adds the checks your agent needs to catch its own mistakes before they reach your review.

Install first: npx skills add itsfaqih/agent-ready-codebase-recipe

  1. Audit
  2. Fill the gaps
  3. Audit again
  • Tools: You pick one per job
  • Parallel work: Worktrees don't clash
  • Linting: Strict rules per file type
  • Tests: Start their own services
  • Sign-in: Test users, no real accounts
  • UI tests: E2E or component tests
  • App use: Agent can drive the app
  • Logging: Queryable request logs
  • PR proof: Annotated screenshots
  • Lessons: Repeat mistakes become rules
  • Test review: Every test seen failing
  • Instructions: Tells agents where to look
The problem

Why you still check your agent's work yourself

Six gaps that leave the checking to you. Each row shows the same screen before the skill runs and after it.

Your agent's tests don't touch real services

Every unit test passes, yet none of them run against the database or services your app uses in production.

Before
The tests mock the database, so they pass and the broken query ships.
After
Tests run against a real Postgres, so the bug fails a test and the agent fixes it before your review.

Your agent can't sign in on its own

It has no account to sign in with and no database it can reach, so you end up checking that work yourself.

Before
The agent stops at the login page and asks you to check.
After
It signs in as a seeded test user and checks the page itself.

Two agents can't run the project at once

They use the same ports, files and local database, and break each other's runs.

Before
The second dev server can't start, because the first one holds the port and the database.
After
Each worktree gets its own URL, ports and database.

You still review what a tool could check

Formatting and lint errors reach your review when a formatter and linter could have rejected them first.

Before
Your review comments are about an unused import and indentation.
After
The linter and formatter reject those first, so your review covers the feature.

Your agent can't use your app

It can't open the app and click through it as a user would, so it never sees what its change does.

Before
It reports that the change should work, without having opened the app.
After
It opens the app, clicks through the flow and sees the result.

Your logs are plain text

When something breaks, your agent scrolls through lines of output instead of querying for the request that failed.

Before
No request id, so the agent guesses which lines belong to the failure.
After
One event per request, with the user and the failing field, found by its id.
How a run works

It checks what you have before it adds anything

First it learns what the project is, who uses it and what a broken release costs. Then you confirm how deep each area goes.

Audit

Mark each area with evidence

For each area it proposes a depth of full, light or n/a, and you confirm it. Then it marks each area done, partial or missing and cites the file or command output that shows it.

Fill the gaps

Add only what's missing

It leaves done areas alone, finishes partial ones and builds missing ones. You pick the tool for each job, and it merges existing docs instead of overwriting them.

Audit again

Stop when nothing changes

The run ends when every area that applies is done and the second audit changes no file.

What the agent reads afterwards

Your agent reads a doc only when the task needs it

AGENTS.md has one line per doc that says when to read it. A project gets only the docs it needs.

AGENTS.md

Read a doc when

  • Worktrees: you add a port, path, compose service, migration or env var → docs/worktrees.md
  • Dependencies in tests: a test needs a database, queue, cloud service or third-party API → docs/hermetic-dependencies.md
  • Falsifiable tests: you write or review any test, or fix a bug → docs/falsifiable-tests.md
  • Agent access: you add auth, a provider, a verification step or a seeded user → docs/agent-access.md
  • E2E: you add or change a user flow or screen → docs/e2e.md
  • Pull request: you open or update a pull request → docs/pull-requests.md
  • Lessons: you make the same mistake twice → docs/lessons.md

Project facts

The task adds a compose service and a test that needs Redis, so the agent opens those two docs and skips the other five.

Get your repo ready for agents in one run.

Spend your review on the decisions. Your agent formats, lints, tests and tries the change in the app before it asks you to look.