12 free Agent Skills for coding agents

---
name: agents-md-audit
description: Audit an AGENTS.md, CLAUDE.md, Cursor rule or Copilot instructions file for stale commands, broken paths, vague rules, secrets and contradictions. Use when asked to review, trim or check agent instructions.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Audit an agent instruction file

Goal: find lines in an instruction file that are wrong, stale, vague or risky, and propose a shorter, accurate version. Never "fix" a command you have not run or a path you have not checked.

## Steps

1. **Find the files.** Look for `AGENTS.md`, `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.cursorrules`, `.github/copilot-instructions.md` and `.github/instructions/*.md`. List what you found and who reads each file.
2. **Run the checker** from the repository root to get mechanical findings first:
   `python3 scripts/audit_instructions.py <file> [<file> ...]`
   (The path is relative to this skill's folder; use the full path to the installed skill.) It reports length, broken file paths, commands that name a script or make target that does not exist, vague phrases, left-over `[BRACKET]` placeholders, duplicate lines and secret-looking strings. If Python is not available, do the same checks by hand.
3. **Check each command yourself.** For every command in the file, confirm it exists (script in `package.json`, target in `Makefile`, entry in `pyproject.toml`). Run the cheap, safe ones (lint, unit tests, type check). Do not run deploy, migrate or delete commands; list them as "not verified".
4. **Check the judgment calls** the script cannot make:
   - Rules a linter or formatter already enforces (candidates to delete).
   - Rules that contradict each other, or contradict another instruction file.
   - Facts the agent can read from the repo in seconds (framework name, folder listing).
   - Rules with no testable meaning ("write clean code").
   - Anything that belongs in a path-scoped rule instead of the root file.
5. **Report**, then wait for approval before editing.

## Report format

```
## Instruction file audit: <file>
Length: <n> lines (<verdict>)

### Must fix (wrong or unsafe)
- line <n>: <what is wrong>, <evidence: command output or missing path>

### Should trim (low value)
- line <n>: <why it can go>

### Contradictions
- <file A line n> vs <file B line m>: <the conflict>

### Not verified
- <command>: <why you did not run it>

### Proposed version
<the shorter file, or a diff>
```

## Rules

- Evidence over opinion: every "must fix" cites output or a missing file.
- Keep the owner's voice and any rule that encodes a real incident or a hard constraint.
- Do not add new rules during an audit. Suggest them separately at the end, at most three.
- Treat a secret-looking string as real: tell the user to rotate it, and do not repeat the value in your report.

---
name: brag-doc-from-git
description: Build an evidence-based brag document or self-review draft from your merged pull requests and commits, leaving visible gaps where results are unknown. Use for review season, promotion cases or resume updates.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Brag document from git history

Goal: turn what you actually shipped into a draft you can edit, without inventing impact. A brag document lists work and results; this skill collects the work and marks every missing result as a gap for you to fill.

## Step 1: collect the evidence

Ask for the time window (default: the last 6 months) and the repositories. Then, with the GitHub CLI signed in:

```
gh search prs --author @me --merged --merged-at ">=YYYY-MM-DD" --json title,url,closedAt,repository --limit 200
```

For code not on GitHub, use `git log --author="<name or email>" --since="YYYY-MM-DD" --no-merges --pretty="%h %ad %s" --date=short` in each repository. Also ask the user to paste anything git cannot show: incidents handled, mentoring, reviews done, talks, docs, on-call, design decisions, kind words from colleagues.

Do not read private repositories the user did not name. Do not guess names, teams or numbers.

## Step 2: group, do not summarize yet

Group the items into themes (for example: reliability, new features, performance, tooling, mentoring, cross-team work). List each item under its theme with date and link. Merge duplicates (a feature PR plus its follow-up fixes).

## Step 3: draft each theme

For every theme write:

- **What I did**: one or two sentences in plain verbs, using only what the titles, diffs and user notes support.
- **Result**: only if a number, quote or outcome was provided. Otherwise write `[GAP: what changed for users or the team? any metric before/after?]`.
- **Evidence**: links.
- **Scope signal** (if supported): led it, did it alone, worked across teams, was on call, reviewed others.

## Step 4: finish with gaps and questions

End with a list of every `[GAP]`, ranked by how much it would strengthen the case, and the three questions whose answers would add the most. Offer to turn the final version into a self-review, a promotion packet outline or resume bullets.

## Rules

- Never invent metrics, percentages, customer names, titles or scope. A visible gap is better than a made-up number.
- Do not inflate: "contributed to" stays "contributed to". Match verbs to the evidence.
- Keep the user's credit honest: if a PR was a team effort, say what part was theirs.
- Keep private or confidential details out unless the user says the document is internal.
- Output Markdown the user can paste into their notes.

---
name: dependency-upgrade
description: Upgrade one dependency at a time by reading its changelog, planning for breaking changes, updating code and proving the project still builds and passes. Use when asked to bump, update or migrate a package or framework.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Upgrade a dependency safely

Goal: move one dependency (or one tightly coupled group) to a newer version with the breakage understood in advance, not discovered afterwards.

## Plan

1. **Pin down the current state.** Find the installed version (lockfile, not just the manifest) and the target version. If the user said "latest", look it up with the package manager (`npm view <pkg> version`, `pip index versions <pkg>`, `cargo search`, etc.) and state the number.
2. **Record a baseline** on a clean working tree: install, build, tests, lint, type check. Note any pre-existing failures so you do not blame the upgrade for them.
3. **Read the real release notes.** Open the changelog, release notes or migration guide for every version between current and target. Extract: breaking changes, removed or renamed APIs, new minimum runtime versions, changed defaults, deprecations. Quote the source link for each item. If you cannot find release notes, say so and treat the upgrade as higher risk.
4. **Map the impact.** `rg` the codebase for each removed, renamed or changed API. List affected files before editing.

## Execute

- Upgrade only this dependency (and required peers). Do not run a blanket "update all".
- Update the manifest and lockfile with the project's package manager, not by hand.
- Make the code changes the notes require, smallest first. Replace deprecated usages when the new form is equivalent.
- Run install, build, tests, lint and type check again. Compare with the baseline.
- For major versions, also run the app or the main example path if feasible, and check bundle size, startup warnings and deprecation warnings.
- If the upgrade needs a minimum runtime or peer version bump, stop and ask before changing it.

## Report

```
Upgrade: <pkg> <from> -> <to>
Sources: <changelog links>
Breaking changes that applied: <list with file refs>
Changes made: <summary>
Verification: <commands, baseline vs after>
Warnings or follow-ups: <deprecations, skipped items, risks>
Rollback: revert <files>, or `git revert <commit>`
```

## Rules

- Never upgrade and refactor in the same change.
- Never skip a failing test or loosen a version range to hide a problem.
- Security fixes: say which advisory the upgrade addresses only if you saw it in an official advisory or the release notes.
- If a transitive dependency forces a conflict, show the conflict output and propose options rather than overriding blindly.

---
name: explain-codebase
description: Build an onboarding map of an unfamiliar repository covering purpose, entry points, how to run it, main modules, data flow and risky areas, with file references. Use when asked to explain, map or onboard onto a codebase.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Explain an unfamiliar codebase

Goal: give a newcomer a map they can trust, with file references, in a few pages. Every claim must point to a file you read.

## Explore in this order

1. **Purpose and users**: README, package description, docs index. What problem does this solve and for whom?
2. **Run it**: install, run, test commands from manifests, Makefile and CI config. Run the cheap ones (tests, lint) to confirm they work; say which you did not run.
3. **Shape**: directory tree two levels deep (ignore `node_modules`, build output, `.git`). Note language(s), framework(s), monorepo layout.
4. **Entry points**: `main`, server start file, CLI entry, route definitions, scheduled jobs, event handlers, `bin` and `scripts` entries.
5. **Trace one real flow end to end**: pick the most central request, command or event and follow it from entry to storage or output, listing each file and function in order.
6. **Data**: schemas, models, migrations, config files, environment variables the code reads (names only, never values).
7. **External touchpoints**: databases, queues, third-party APIs, auth providers.
8. **Quality signals**: where tests live and what they cover, CI checks, lint rules, areas with TODOs, very large files, recent churn (`git log --since="3 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head`).

## Output

```
# <repo> in one page
Purpose: ...
How to run: <commands, verified or not>
Map: <directory -> responsibility, one line each>
One flow, step by step: <file:function ...>
Data and config: ...
External services: ...
Where to start reading: <3 files in order, with why>
Risky or confusing areas: <file, reason>
Open questions: <what you could not determine>
```

## Rules

- Cite `path:line` or at least `path` for each claim. If you inferred something, label it "inferred".
- Do not describe code you did not open. Do not guess at business context; put it under open questions.
- Never print secret values from `.env` files or config; list variable names only.
- Keep it short: a map, not a tour of every file.

---
name: pr-description
description: Write a pull request title and description from the actual diff and commits, with what changed, why, how it was tested and what to review. Use when asked to write or improve a PR description.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Write a PR description a reviewer can use

Goal: let a reviewer decide in two minutes what to look at, and let a future reader understand why the change exists.

## Gather

1. Find the base branch and run `git log --oneline <base>..HEAD` and `git diff --stat <base>...HEAD`, then read the diff.
2. Look for the reason: linked issue or ticket number in commits or branch name, the user's request, comments added in the diff. If the reason is not in any of these, ask the user; do not invent a motivation.
3. Check what was tested: test files in the diff, and commands the user ran. If tests were not run, say so plainly.
4. Look for a `.github/pull_request_template.md` or `PULL_REQUEST_TEMPLATE`. If one exists, fill it in instead of using the structure below.

## Structure

```
<Title: imperative, under 70 characters, names the behavior change, not the files>

## Why
<The problem or request, in 1 to 3 sentences. Link the issue if there is one.>

## What changed
- <Behavior-level bullets grouped by area, not a file list.>

## How to review
- Start with <file or area>; the rest follows from it.
- Risky part: <the part most likely to be wrong, and why>.
- Not changed on purpose: <anything a reviewer may expect and will not find>.

## Testing
- <Exact commands run and results.>
- <Manual steps and what was seen. "Not tested: ..." if applicable.>

## Rollout / risk
<Migrations, config, feature flags, compatibility, how to roll back. "None" only if true.>
```

## Rules

- Describe what the diff does, not what you wish it did. Re-read the diff after drafting and delete any claim it does not support.
- Do not list every file. Do list behavior changes, new config, new dependencies and deleted code.
- No filler ("This PR aims to..."). No emojis unless the repo uses them.
- Screenshots or output examples: say where one would help; never describe a screenshot you did not see.
- Output the title and body in a code block so it can be copied. Do not run `gh pr create` unless asked.

---
name: prove-it-ran
description: Verify that tests, builds and checks actually ran and exercised the changed code, before claiming a task is done. Use before reporting completion, or when asked to prove tests ran or verify a fix.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Prove it ran

Goal: never say "done" or "tests pass" on the strength of belief. Show evidence that the checks ran, covered the change, and would have caught a failure.

## Procedure

1. **List the claims** you are about to make ("the bug is fixed", "all tests pass", "the build succeeds", "no lint errors").
2. **For each claim, run the command now**, from a clean state of your edits, and capture the output. Do not rely on output from earlier in the session if you edited files since.
3. **Confirm the check really ran:**
   - Test runners: the output shows a test count above zero, and the new or changed tests appear by name or file. "0 tests", "no tests found" or "skipped" is not a pass.
   - Check the exit code, not just the wording (`echo $?` right after the command, or the runner's summary line).
   - Make sure the runner picked up your files: right directory, right config, test file matches the naming pattern.
4. **Confirm it covers the change.** For a bug fix, the test must fail without the fix: temporarily revert the fix (`git stash` the source change only, or comment it out), run the test, see it fail, restore, see it pass. If you cannot do this, say so.
5. **Check for silent skips.** Search output for `skipped`, `xfail`, `pending`, `todo`, and your own `.only`/`.skip`/`pytest.mark.skip` leftovers (`rg "\.only\(|\.skip\(|xit\(|fdescribe|pytest.mark.skip"`).
6. **Run the wider checks** the project defines (lint, type check, build). Report exact commands.
7. **Report in a table** and be explicit about anything you did not or could not run.

## Report

```
| Claim | Command | Evidence (count / exit code / key line) | Verified |
|---|---|---|---|
| Fix works | <cmd> | 1 failing before, passes after | yes |
| Suite passes | <cmd> | 212 passed, 0 failed, exit 0 | yes |
| Lint clean | <cmd> | not run: no lint script | no |
```

## Rules

- "Should work" and "looks right" are not evidence. Replace them with a command and its output or say you did not verify.
- Never edit a test, snapshot or threshold only to turn a check green. If a test is wrong, say why and ask.
- Report failures in full, including ones that look unrelated. Mark pre-existing failures as such only if you confirmed them on a clean checkout.
- If something cannot be run here (needs credentials, a device, production), list it under "Not verified" with how the user can check.

---
name: repro-first-debugging
description: Debug by reproducing the failure first, then forming and testing hypotheses before editing code. Use when asked to fix a bug, a failing test, a crash or unexpected behavior.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Reproduce first, then fix

Goal: fix the cause, prove the fix, and avoid editing on a guess.

## Process

1. **Restate the failure** in one line: expected behavior, actual behavior, where it was seen. Ask for the error text, steps or input if they are missing. Do not start from a vague description.
2. **Reproduce it.** Run the failing test or the smallest command that triggers it. Capture the exact output. If you cannot reproduce it, stop and report what you tried; do not "fix" something you cannot see fail.
3. **Shrink it.** Reduce to the smallest input or test that still fails. Prefer turning the reproduction into an automated failing test in the project's test framework.
4. **List hypotheses.** Write two or three plausible causes, each with the evidence that would confirm or kill it. Rank by likelihood and cost to check.
5. **Test the hypotheses, cheapest first.** Read the code path, add temporary logging or assertions, bisect (`git bisect` or by reverting suspects), check recent changes (`git log -p -- <path>`). Record what each check showed. Remove temporary logging afterwards.
6. **Fix the cause, not the symptom.** Make the smallest change that explains the evidence. If the fix needs a workaround, say so and why.
7. **Prove it.** The failing test now passes; run the nearby tests and the full suite if fast. Show the before and after output.
8. **Look for siblings.** Search for the same pattern elsewhere (`rg`) and report, but do not change unrelated code without asking.

## Report

```
Failure: <expected vs actual>
Reproduction: <command> -> <output summary>
Root cause: <what and why, with file:line>
Evidence: <the checks that confirmed it, and the hypotheses ruled out>
Fix: <summary of the change>
Verification: <failing test now passes; commands and results>
Related risks: <similar code found, not changed>
```

## Rules

- No code edits before step 2 succeeds, unless the user explicitly asks for a blind fix.
- Never delete or weaken a test to make it pass.
- Never claim success without showing a command that failed before and passes now.
- If three hypotheses fail, stop and report what you know and what you need.

---
name: review-my-diff
description: Self-review your uncommitted or branch changes before opening a PR, with findings ranked by severity and backed by file and line evidence. Use when asked to review my changes, check my diff or get ready for review.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Review my diff before a human does

Goal: catch the problems a reviewer would catch, in order of how much they matter. You are reviewing, not rewriting: do not edit files unless asked.

## Steps

1. **Get the change.** Run `git status --short`, then `git diff` (unstaged) and `git diff --staged`. For a branch, find the base (`git merge-base HEAD origin/main` or the default branch) and run `git diff <base>...HEAD`. If the diff is huge, review it by directory and say so.
2. **State the intent** in one sentence, inferred from commit messages, branch name or the user's request. If you cannot tell, ask once.
3. **Read the whole diff, then the code around risky hunks** (callers, tests, config). A diff hides what it did not touch.
4. **Check in this order:**
   1. Correctness: wrong conditions, off-by-one, null/empty cases, error paths, concurrency, resource cleanup.
   2. Safety: input validation, auth checks, secrets, injection, destructive operations, migrations that lock or lose data.
   3. Tests: does a test fail without this change? Are the new branches covered? Any test that asserts nothing?
   4. Compatibility: public API, config, database, file formats, callers outside this repo.
   5. Maintainability: dead code, copy-paste, unclear names, debug leftovers (`console.log`, `print`, `TODO`, commented code).
   6. Scope: unrelated edits that should be a separate PR.
5. **Run what exists**: the project's tests, lint and type check, if they are quick. Report the exact commands and results. If you did not run something, say so.

## Output format

```
Intent: <one sentence>
Checks run: <commands and results, or "none">

BLOCKER (fix before merging)
- <file>:<line> <problem>. Why it matters: <consequence>. Suggested fix: <short>

SHOULD FIX
- <file>:<line> ...

NITS (optional)
- ...

Looks good
- <specific things that are right, so the author knows what to keep>

Questions for the author
- <things you could not determine from the code>
```

## Rules

- Every finding names a file and line, and says what breaks. No "consider improving readability" without a specific line.
- If you find nothing in a category, say "nothing found" rather than inventing a nit.
- Distinguish "I verified this" from "this looks suspicious". Do not claim a bug you did not trace.
- Never approve. End with a recommendation (ready, ready after fixes, or needs rework) and the reason.

---
name: safe-refactor
description: Refactor in small, verified steps, with behavior locked by tests before any change. Use when asked to refactor, clean up, rename, extract or restructure code without changing behavior.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Refactor without changing behavior

Goal: improve structure while behavior stays identical, proven after every step.

## Before touching code

1. **State the goal and the boundary** in two lines: what gets better (readability, duplication, testability) and what must not change (public API, output format, performance envelope). Confirm with the user if the boundary is unclear.
2. **Find the safety net.** Locate the tests that cover the code. Run them and record the baseline (pass count, any pre-existing failures). Pre-existing failures are not yours to fix silently; list them.
3. **Close gaps.** If the code to change has no tests, write characterization tests first: run the code with realistic inputs, record what it currently does (even if odd), and assert exactly that. Commit or save these before refactoring.
4. **Check the blast radius.** Search for callers and dependents (`rg`), including tests, scripts, docs and config that mention the names you will change. Public or exported symbols need a deprecation path or an explicit go-ahead.

## During

- **One kind of change per step**: rename, or extract, or move, or inline. Never mix a refactor with a bug fix or a feature.
- **After every step** run the relevant tests plus type check or lint. If red, undo the step (`git restore` or revert your last edit) and try a smaller step. Do not debug forward through a broken refactor.
- **Keep diffs reviewable.** Aim for steps a person can review in minutes. Prefer several small commits if the user wants commits.
- **Do not "improve" while you are here**: unrelated formatting, dependency bumps and style changes go in a separate list at the end.
- Preserve behavior including error messages, ordering, logging and edge cases, unless the user says otherwise.

## Finish

Report: the steps taken, tests run and results, what you deliberately did not change, bugs or smells you noticed but left alone, and any behavior you are not sure is preserved (for example, code with no coverage that you could not exercise).

## Stop and ask when

- Tests cannot be run, or the baseline is red for reasons you cannot explain.
- The change needs a public API break.
- You find a real bug in the code being moved. Report it; fix it as its own change.

---
name: security-quick-review
description: Quick security pass over a change or module covering secrets, injection, auth and access checks, unsafe deserialization, dependency and config risks, with evidence. Use before merging code that handles input, auth, files or money.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Quick security review

This is a fast triage by an AI assistant, not a security audit or penetration test. Say so in the report. Goal: find the likely problems in the code in scope and show evidence for each.

## Scope

State what you reviewed (a diff, a directory, an endpoint) and what you did not. Review the diff plus the code it calls into; a change in one place often breaks assumptions elsewhere.

## Checklist (look at each, report "nothing found" if clean)

1. **Secrets**: keys, tokens, passwords, private keys, connection strings in code, config, tests, fixtures, logs, CI files. Check `git diff` and `git log -p` for the scope too. Never repeat a secret value in the report; give file and line only.
2. **Untrusted input**: every place data comes from a user, a request, a file, a webhook, an environment, a database field that a user can write.
3. **Injection**: SQL built by string concatenation, shell commands with interpolated input, template or HTML output without escaping, path joins with user input (path traversal), regex built from input, SSRF through user-supplied URLs.
4. **Authentication and authorization**: is every new route or action checked for who may call it? Can a user reach another user's data by changing an ID? Are admin paths separate and checked server-side?
5. **Data exposure**: logs or errors that include tokens or personal data, overly broad API responses, debug flags, permissive CORS.
6. **Unsafe operations**: deserialization of untrusted data, `eval`/`exec`, disabled TLS verification, weak randomness for tokens, home-made crypto, unbounded file uploads or request sizes.
7. **Dependencies and config**: new packages (do they exist, are they maintained, is the name suspiciously close to a popular one), pinned versions, lockfile changes, new permissions in CI or cloud config.
8. **Failure behavior**: what happens on error, timeout or malformed input? Does it fail closed?

## Report

```
Scope: <reviewed / not reviewed>
HIGH: <file:line> <issue>. Exploit sketch: <how it could be abused, one or two sentences>. Fix: <specific>
MEDIUM: ...
LOW / hardening: ...
Checked, nothing found: <categories>
Could not verify: <things needing runtime, infra or secrets access>
Limits: automated triage; not an audit; get a human review for anything handling money, health or identity data.
```

## Rules

- Every finding needs file, line and a concrete explanation. No generic OWASP lists.
- Do not attempt to exploit anything against live systems. Reading code and running local tests is fine.
- Rate by realistic impact, not by how scary the category sounds.
- If you find a real secret, tell the user to rotate it; removing it from the code does not remove it from git history.

---
name: session-handoff
description: Write a HANDOFF.md that lets a fresh agent session continue the work, with goal, state, decisions, next steps and traps. Use when ending a long session, hitting context limits or switching agents.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Hand off the session

Goal: a new session (or a different agent, or you tomorrow) can resume in minutes without re-discovering anything. Write facts you verified, not impressions.

## Steps

1. **Check the real state.** Run `git status --short`, `git branch --show-current` and `git log --oneline -10`. Run the project's quick tests or build if you can, so the handoff says whether the tree is green or red.
2. **Write `HANDOFF.md`** in the repository root (or the path the user names) with the sections below. Keep it under about 80 lines.
3. **Do not commit it** unless asked. Mention that it is untracked and should not be committed to a shared branch by accident.
4. **Tell the user** how to resume: for example "start a new session and say: read HANDOFF.md and continue".

## HANDOFF.md template

```
# Handoff: <short task name>
Written: <date and time>  Branch: <branch>  Last commit: <hash subject>

## Goal
<What done looks like, in 2 to 4 lines. Include the user's own wording where it matters.>

## Current state
- Working tree: <clean | uncommitted changes in ...>
- Tests/build: <command> -> <pass | fail with the key error>
- Done: <bullets, each verifiable>
- In progress: <what is half-finished, which files>

## Decisions and why
- <Decision>: <reason>. Rejected: <alternative and why>.

## Next steps (in order)
1. <Specific action with the file or command>
2. ...

## Traps and facts learned
- <Things that wasted time: flaky test, misleading error, env quirk, file that must not be edited>
- <Commands that work / do not work>

## Open questions for the user
- <Anything blocked on a human decision>

## Not verified
- <Claims you did not check>
```

## Rules

- Separate verified facts from guesses. If you did not run it, list it under "Not verified".
- No secrets, tokens or personal data in the file.
- Next steps must be actionable by someone with no memory of this session.
- Include the exact failing command and error text for anything red; a paraphrase is not enough.

---
name: write-agents-md
description: Draft a short, accurate AGENTS.md (and a CLAUDE.md bridge) for a repository from evidence in the repo. Use when a project has no agent instructions, or when asked to create or rewrite AGENTS.md.
license: MIT
metadata:
  author: AgentKit Co
  version: "1.0"
---

# Write an AGENTS.md from evidence

Goal: a file under about 100 lines that tells a coding agent how to run, test and change this repo, using only facts you verified. Unknown beats invented.

## Gather evidence first (read, do not guess)

1. `README*`, `CONTRIBUTING*`, any `docs/` index.
2. Manifests and task runners: `package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `project.godot`.
3. CI config (`.github/workflows/*`, `.gitlab-ci.yml`): the commands CI runs are the commands that must pass.
4. Lint, format and type-check config (`.eslintrc*`, `ruff.toml`, `.editorconfig`, `tsconfig.json`).
5. Directory layout, two levels deep, ignoring `node_modules`, `.git`, build output.
6. Existing instruction files (`CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`). Merge, do not duplicate.

## Write the file

Use [references/template.md](references/template.md) as the skeleton. Rules:

- **Commands first.** Exact commands to install, run, test one file, run the full suite, lint, build. Copy them from the manifests; run the safe ones to confirm.
- **Only what the agent cannot infer.** Skip "this is a Next.js app" if `package.json` says so. Keep: unusual conventions, forbidden areas, generated files, required env setup.
- **Make each rule testable.** "Run `npm run lint` before finishing" not "keep code clean".
- **Boundaries section.** Files and directories never to edit by hand (generated code, lockfiles, vendored code), and actions that need approval (migrations, deploys, deleting data, force-push).
- **Unknowns.** Where evidence is missing, write `TODO(owner): <question>` instead of guessing, and list the TODOs in your final message.
- **No secrets, no personal paths, no links you did not open.**

## Bridge for other tools

- Claude Code reads `CLAUDE.md`, not `AGENTS.md`. If no `CLAUDE.md` exists, create one containing only `@AGENTS.md` so both stay in sync (Claude Code supports `@path` imports). If one exists, add that import line at the top and remove duplicated content.
- Cursor, GitHub Copilot, Codex and others read `AGENTS.md` directly or via their own files; do not copy the content into several places.

## Verify before finishing

1. Run each command you documented (skip destructive ones, say so).
2. Check every path exists.
3. Count lines. If over about 100, move scoped rules to nested `AGENTS.md` files or tool-specific rule files.
4. Show the user the file and the TODO list. Do not commit unless asked.