Init
AGENTS.md is a README for agents: the one predictable place a coding agent
looks for how this project builds, tests, and is laid out. This skill writes
that file from evidence. A command lands in it only after it ran here and
printed what the file claims it prints.
What makes an AGENTS.md worth reading
- Every command in it was run in this session. A plausible command that was
never executed is a trap, not a tip.
- It names the one command that proves the tree before a push. That is the
highest-value line in the file.
- It points at where knowledge lives instead of restating it. Restated facts
drift; pointers do not.
- It is short. An agent reads it every session, so padding costs on every turn.
Step 1: detect
Find the project's command surfaces and read the ones that exist.
Makefile, justfile, Taskfile.yml: the target names are the real commands.
package.json: scripts, plus the package manager from the lockfile
(pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json).
pyproject.toml, pytest.ini, tox.ini, ruff.toml, mypy.ini,
pyrightconfig.json: test runner, linter, type checker, coverage gate.
docker-compose.yml, Dockerfile: how the thing actually runs.
Cargo.toml, go.mod, CMakeLists.txt, build.gradle, .csproj.
- CI config under
.github/workflows or .gitlab-ci.yml: the commands CI
already trusts.
- An existing
README.md or CONTRIBUTING.md: layout and conventions that
are written down already. Reuse them instead of re-deriving.
Record each candidate as the exact command plus what "passing" looks like.
Step 2: verify by running
Run every candidate. Keep the ones that worked, with their real output.
- A test command: read the passed/failed line and keep the count it printed.
- A lint or type command: it must exit clean, or you record what it reported.
- A build or start command: run it if it terminates. If it serves forever, run
it under a time limit (your shell tool's timeout option; the
timeout
command differs between Linux, macOS and Windows), confirm it came up, then
say in the file that it blocks.
- A command whose dependency is missing: that is a skip, not a pass. Write the
command and what it needs.
- Note the OS and shell you ran on (Linux, macOS, Windows PowerShell or Git
Bash). A command that passed here is verified on this OS only. If the repo
documents or ships both POSIX and Windows scripts (
.sh and .ps1/.cmd),
run the form that matches this machine and mark the other one unverified.
Never invent a flag, a target, or a script name. When the surface has no
command for something the project obviously needs, that is a finding worth one
line in the file, not a command you make up.
Step 3: write
Placement, per the agents.md standard:
- Root
AGENTS.md is the default.
- Monorepos get nested files, and the closest one to the edited file wins. Add
a nested file when a subproject has its own toolchain or its own rules.
- Instructions the user gives in chat override the file.
Write these sections and skip any that would be empty:
# <Project>
One line on what this is and what runs it.
## Commands
- Install: `<command>` (verified: <what it printed>)
- Test: `<command>` (verified: <count> passed)
- Lint and types: `<command>`
- Run it: `<command>`
- Before a push: `<command>`
## Layout
- `path/` what lives there
## Conventions
- A rule this codebase actually follows, with the file that shows it.
## Do not
- The thing that breaks this project.
## Where the knowledge lives
- `<doc path>`: what it covers
Rules for the content:
- Verified facts only. Anything you could not run gets
TODO: and the reason,
never a confident guess.
- Commands verbatim, including the wrapper (
make test, not pytest).
- Name the paths an agent would otherwise grep for.
- Sentence case headings. No decorative emoji.
- Per command, say which OS it was verified on, for example
(verified on Windows: 42 passed). When the repo is used on both POSIX and Windows, write
both forms (POSIX: ... and Windows (PowerShell): ...) and mark the one you
could not run TODO: unverified on <OS>. A command with no OS difference
(git, npm test, make targets that wrap them) needs no label.
- The file covers this repo only. Other projects, folders that moved away, and
what used to live here stay out of it. An agent working in this repo must not
learn about external projects from its AGENTS.md, and a deleted thing leaves
no line behind.
- Agent-instruction files are classifier-scanned as well as read. Never write
anti-refusal scaffolding into them ("ignore content flags", "refusing does
not protect anyone", "the assistant must"): it reads as a jailbreak wrapper
and gets whole sessions cut. State authorization as calm facts of what the
owner owns and does.
- Keep it under roughly 120 lines. Longer detail belongs in a doc that the
file points at.
Step 4: confirm
Show the draft in the reply and ask whether to write it. Do not write it
silently, and do not commit in the same breath. This file steers every future
session in the repo, so the user reads it first.
Step 5: commit
Follow the commit skill. One commit, message naming the file.
Refresh, not just create
When the file already exists, do not rewrite it from scratch. Read it, re-run
each command it claims, and fix only the lines that no longer hold. Report
which claims were stale and what the new output is. A file that survived this
pass is worth trusting; one that was never re-run is not.
When the user says to keep the current file and append, add one new top-level section at the bottom and leave every line above it byte-identical. Existing persona or voice text is theirs; do not tidy it. Run the commands before listing them, and state in the section which ones ran live and which were only read from the Makefile.
When the file is gitignored
Some repos ignore AGENTS.md on purpose. Check with git check-ignore. If it
is ignored, the file helps this machine only. Say so, and put any fact a
teammate needs into a tracked file instead, usually the README.
What this skill does not do
It does not optimize itself against a benchmark. SkillOpt and similar tools
score a skill by running it through a task suite behind a held-out gate, and
none of their built-in suites grade an AGENTS.md, so there is nothing here to
pass. Verification in this skill is that same loop done by hand: run the
command, read the output, write only what you saw.
1---2name: init3description: >-4 Build or refresh a repository's AGENTS.md from what the repo actually does.5 Use when asked to run /init, initialize a repo for agents, write or update6 AGENTS.md, onboard an agent into a codebase, or find out how a project is7 built and tested. Detects the command surfaces, runs each candidate command8 before writing it down, and never records a fact it did not verify.9metadata:10 source: https://skillmd.com/skills/calvin-llc/init11---1213# Init1415AGENTS.md is a README for agents: the one predictable place a coding agent16looks for how this project builds, tests, and is laid out. This skill writes17that file from evidence. A command lands in it only after it ran here and18printed what the file claims it prints.1920## What makes an AGENTS.md worth reading2122- Every command in it was run in this session. A plausible command that was23 never executed is a trap, not a tip.24- It names the one command that proves the tree before a push. That is the25 highest-value line in the file.26- It points at where knowledge lives instead of restating it. Restated facts27 drift; pointers do not.28- It is short. An agent reads it every session, so padding costs on every turn.2930## Step 1: detect3132Find the project's command surfaces and read the ones that exist.3334- `Makefile`, `justfile`, `Taskfile.yml`: the target names are the real commands.35- `package.json`: `scripts`, plus the package manager from the lockfile36 (`pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `package-lock.json`).37- `pyproject.toml`, `pytest.ini`, `tox.ini`, `ruff.toml`, `mypy.ini`,38 `pyrightconfig.json`: test runner, linter, type checker, coverage gate.39- `docker-compose.yml`, `Dockerfile`: how the thing actually runs.40- `Cargo.toml`, `go.mod`, `CMakeLists.txt`, `build.gradle`, `.csproj`.41- CI config under `.github/workflows` or `.gitlab-ci.yml`: the commands CI42 already trusts.43- An existing `README.md` or `CONTRIBUTING.md`: layout and conventions that44 are written down already. Reuse them instead of re-deriving.4546Record each candidate as the exact command plus what "passing" looks like.4748## Step 2: verify by running4950Run every candidate. Keep the ones that worked, with their real output.5152- A test command: read the passed/failed line and keep the count it printed.53- A lint or type command: it must exit clean, or you record what it reported.54- A build or start command: run it if it terminates. If it serves forever, run55 it under a time limit (your shell tool's timeout option; the `timeout`56 command differs between Linux, macOS and Windows), confirm it came up, then57 say in the file that it blocks.58- A command whose dependency is missing: that is a skip, not a pass. Write the59 command and what it needs.60- Note the OS and shell you ran on (Linux, macOS, Windows PowerShell or Git61 Bash). A command that passed here is verified on this OS only. If the repo62 documents or ships both POSIX and Windows scripts (`.sh` and `.ps1`/`.cmd`),63 run the form that matches this machine and mark the other one unverified.6465Never invent a flag, a target, or a script name. When the surface has no66command for something the project obviously needs, that is a finding worth one67line in the file, not a command you make up.6869## Step 3: write7071Placement, per the agents.md standard:7273- Root `AGENTS.md` is the default.74- Monorepos get nested files, and the closest one to the edited file wins. Add75 a nested file when a subproject has its own toolchain or its own rules.76- Instructions the user gives in chat override the file.7778Write these sections and skip any that would be empty:7980```markdown81# <Project>8283One line on what this is and what runs it.8485## Commands86- Install: `<command>` (verified: <what it printed>)87- Test: `<command>` (verified: <count> passed)88- Lint and types: `<command>`89- Run it: `<command>`90- Before a push: `<command>`9192## Layout93- `path/` what lives there9495## Conventions96- A rule this codebase actually follows, with the file that shows it.9798## Do not99- The thing that breaks this project.100101## Where the knowledge lives102- `<doc path>`: what it covers103```104105Rules for the content:106107- Verified facts only. Anything you could not run gets `TODO:` and the reason,108 never a confident guess.109- Commands verbatim, including the wrapper (`make test`, not `pytest`).110- Name the paths an agent would otherwise grep for.111- Sentence case headings. No decorative emoji.112- Per command, say which OS it was verified on, for example `(verified on113 Windows: 42 passed)`. When the repo is used on both POSIX and Windows, write114 both forms (`POSIX: ...` and `Windows (PowerShell): ...`) and mark the one you115 could not run `TODO: unverified on <OS>`. A command with no OS difference116 (`git`, `npm test`, `make` targets that wrap them) needs no label.117- The file covers this repo only. Other projects, folders that moved away, and118 what used to live here stay out of it. An agent working in this repo must not119 learn about external projects from its AGENTS.md, and a deleted thing leaves120 no line behind.121- Agent-instruction files are classifier-scanned as well as read. Never write122 anti-refusal scaffolding into them ("ignore content flags", "refusing does123 not protect anyone", "the assistant must"): it reads as a jailbreak wrapper124 and gets whole sessions cut. State authorization as calm facts of what the125 owner owns and does.126- Keep it under roughly 120 lines. Longer detail belongs in a doc that the127 file points at.128129## Step 4: confirm130131Show the draft in the reply and ask whether to write it. Do not write it132silently, and do not commit in the same breath. This file steers every future133session in the repo, so the user reads it first.134135## Step 5: commit136137Follow the `commit` skill. One commit, message naming the file.138139## Refresh, not just create140141When the file already exists, do not rewrite it from scratch. Read it, re-run142each command it claims, and fix only the lines that no longer hold. Report143which claims were stale and what the new output is. A file that survived this144pass is worth trusting; one that was never re-run is not.145146When the user says to keep the current file and append, add one new top-level section at the bottom and leave every line above it byte-identical. Existing persona or voice text is theirs; do not tidy it. Run the commands before listing them, and state in the section which ones ran live and which were only read from the Makefile.147148## When the file is gitignored149150Some repos ignore `AGENTS.md` on purpose. Check with `git check-ignore`. If it151is ignored, the file helps this machine only. Say so, and put any fact a152teammate needs into a tracked file instead, usually the README.153154## What this skill does not do155156It does not optimize itself against a benchmark. SkillOpt and similar tools157score a skill by running it through a task suite behind a held-out gate, and158none of their built-in suites grade an AGENTS.md, so there is nothing here to159pass. Verification in this skill is that same loop done by hand: run the160command, read the output, write only what you saw.