akunzai/agent-skills / skills/setup-agent-ready-repo
setup-agent-ready-repo
UnverifiedSet up a repository so agents can file tickets, open pull or merge requests, and verify their own changes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| agents/openai.yaml | config | 172 B |
| assets/guarantees.tsv | other | 3.7 KB |
| assets/templates/issue-tracker.md | markdown | 5.8 KB |
| assets/templates/pull-request.md | markdown | 4.9 KB |
| assets/templates/verification.md | markdown | 5.2 KB |
| references/capture.md | markdown | 4.9 KB |
| references/gitlab-cli.md | markdown | 2.1 KB |
| references/re-running.md | markdown | 2.1 KB |
| references/ticket-and-pr.md | markdown | 7.4 KB |
| references/verification.md | markdown | 8.0 KB |
| scripts/check-drift.shexecutable | script | 7.7 KB |
| scripts/install-templates.shexecutable | script | 7.2 KB |
| skill.oms.sig | other | 14.6 KB |
references/verification.md
View on GitHub# Verification setup
## Finding the entrypoint
Read, in order, and stop at the first that starts the whole stack:
`mise.toml` tasks, `package.json` scripts, `Makefile` targets,
`compose.yml` / `docker-compose.yml`, an existing `scripts/setup*`, then
the `README`'s run section. What comes out is one command, not a
narrative.
Where a setup script exists but prompts, wrap it rather than rewriting
it. Where only prose exists, condense the prose into a command; do not
relocate the prose.
## Non-interactive contract
This applies to a script this skill writes. Where the project already has
one non-interactive command, record that command and skip the contract;
a wrapper exists only to satisfy a checklist, and it drifts.
A script, where one is warranted, must satisfy all five:
- **Mode detection, layered**: an explicit `--non-interactive` flag,
then `NON_INTERACTIVE=true|false`, then `CI=true`, then stdin not
being a TTY.
- **Fail fast on a typo.** A `NON_INTERACTIVE` or `CI` value that is
neither true nor false exits non-zero. Silently falling back to
interactive mode leaves an agent hanging with no diagnosis.
- **Never prompt.** A step needing a human aborts with a message naming
the prerequisite. It does not ask.
- **Prove it came up.** A health endpoint, a port accepting a
connection, or a command exiting zero. A running container is not
evidence.
- **Bound the wait.** Give each long step, a test run above all, a
wall-clock limit that fails the script. On expiry, report what was
still running (the tests that started but never finished, a stack
sample of the test process) before killing it. A framework's per-test
time limit cannot end a test whose thread is blocked, and a hang with
no limit leaves an agent waiting with no diagnosis.
A dependency's own log is often too quiet to show the request that
proves an integration. Raise its level for the check and restore the
repo's configuration afterwards, rather than concluding from silence.
## What the repo already documents
Link to what a `README` or `CONTRIBUTING.md` already says, and keep only
what is agent-specific. Where `AGENTS.md` already lists build and test
commands, `verification.md` becomes their single source and the
`AGENTS.md` entry shrinks to the pointer.
## Sweeping after the move
Where `AGENTS.md`'s build and test commands moved into `verification.md`,
grep the source tree, not Markdown and config alone. A doc comment naming
an `AGENTS.md` section outlives the move as readily as a task-runner
comment does, and it is the hit a docs-only sweep misses. Run the sweep
even where this skill relocated nothing: it catches whatever moved things
last, not only this skill's move.
## Human prerequisites
Installing tools, `mkcert -install` and friends, anything needing sudo,
obtaining credentials, setting CI secrets. These go into
`verification.md` as a checklist and into the script as fail-fast
checks.
**Test a credential for presence, never print it.** `[ -n "${VAR:-}" ]`
answers the only question a prerequisite check asks. A bare expansion,
an `echo`, or a `set -x` around one puts the value in the transcript,
and a transcript is not a place a secret can be taken back from — the
remedy is rotation, paid by whoever owns the credential. This applies to
every `.env` line, not only the ones that look secret.
### A setup script for people
Built only when the developer asks, with the `wizard` skill. It is a
layer over the entrypoint, never a second implementation of it:
- **The entrypoint owns every check.** Give it a check subcommand (a
`doctor` task, say) that reports each prerequisite as passing or
failing without prompting. The wizard walks only what needs a person —
opening a token page, hidden entry, a choice between installed tools —
then finishes by running that same check. A wizard with checks of its
own drifts from the ones agents run.
- **It refuses to run without a person.** Apply the layered mode
detection above; in non-interactive mode it exits non-zero naming the
check command agents run instead. The wizard template ships no such
guard, so add it below the template's stages marker.
- **A choice persists where the check reads it**, such as a key in a
gitignored `.env`, so an agent's later run uses the person's choice
without asking.
`verification.md` names both: the script for people, the check for
agents.
## Container engine
A compose file this skill adds — mocks, or anything else — runs under
both `docker compose` and `podman compose`:
- **Fully qualified image names** (`docker.io/<owner>/<image>:<tag>`).
Podman may prompt for a registry on a short name, which breaks the
never-prompt rule. Take the tag from the registry, not from memory.
- **`:z` on every bind mount**, or containers on an SELinux host cannot
read the mounted files. Docker accepts the same option.
The entrypoint picks the engine in order: an explicit variable such as
`CONTAINER_ENGINE`, then the same key in the gitignored `.env`, then
whichever engine answers `<engine> info`. Any other value exits non-zero;
an engine that is installed but stopped exits naming how to start it.
Prove the engine rather than assume it: bring the file up under each
engine available and confirm a mounted file is served, not only that the
containers run. An engine this machine lacks goes under the unverified
section.
## Ports, with several agents at once
Two strategies, chosen by how the project is reached.
**Reached by port** — derive a fixed offset from the worktree path, and
parameterise the compose ports minimally as `${SERVICE_PORT:-8080}`,
keeping the current value as the default so unset behaviour is
unchanged. Write the resolved ports to a runtime file the agent reads,
so nothing has to guess where the app is listening.
**Reached by hostname or TLS** — offsetting the port breaks the URL, so
this does not apply. Fall back to a lockfile mutex and record in
`verification.md` that only one agent runs the environment at a time.
## Mocks
Opt-in, and scaffold only. Add the service, an empty mapping directory,
and a documented way to add a scenario. Stop there.
Real stubs encode business rules — which identifier is matched, which
account gets the non-empty response — that cannot be derived from client
code. A generated stub passes while asserting nothing, which is worse
than no mock at all. Suggest filing a ticket to implement them.
Pick the tool by probing what the project already uses. Otherwise
propose by protocol: HTTP takes WireMock, Mockoon, or msw; LDAP takes an
openldap container; a database takes the real database in a container
rather than a mock.
## A remote test environment
Record three things and no more: how to reach it, where credentials come
from — the vault or variable name, never the value — and whether the
agent may deploy to it. That flag defaults to no.
Deploying to a shared environment affects other people's work, and an
agent's judgement about whether now is a safe moment is not reliable.
Opening it up should be a deliberate act by the developer, not a
checkbox during setup.
Evidence captured from such an environment carries two extra
requirements, because it is shared and its data may be real:
- **Cite the source**: the pipeline or deployment id and the commit SHA.
Without them the evidence cannot be tied to this change rather than to
someone else's deploy.
- **Assume PII is present** unless the environment is known to hold only
test data. Mask, crop, or use a dedicated test account.
## Recording what could not be verified
An explicit section, not a silent omission. Each entry names the path
that went unverified and why — missing credentials, a service this repo
does not run, a device that is not available. A document that quietly
claims full coverage is worse than one that admits a gap.
A gap you could have closed is not a gap. Check each entry against what
this session already probed: a dependency you saw running is a reason to
run the check, not a reason to record it as unrunnable. A check you
merely skipped belongs in the hand-back, named as untried — the document
records what this repo cannot verify, not what this session did not get
to.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |