smarzbansmarzban/agent-skills/AGENTS.md

agent-skills

AGENTS.md1 starsChanged 3 days agoMITView on GitHub

A change to one of these paths is never merged by an agent alone. A note that a stranger who cloned this repo could use goes in this file. Local paths, personal workflow and private context go in AGENTS.local.md. Never put content in AGENTS.override.md. @AGENTS.local.md

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository15 other files it gives its agents.
- code-auditSkill
- comment-auditSkill
- coordinatorSkill
- correctSkill
- deliverSkill
- handoffSkill
- publishing-a-repoSkill
- releaseSkill
- repo-setupSkill
- shared-skillsSkill
- test-auditSkill
- triageSkill
- verification-skillSkill
- writing-docsSkill
- writing-readmesSkill

The file

We split this AGENTS.md into the rules it gives an agent

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

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Verify, the same command CI runs: scripts/verify
line 6
Very specific:
Check the skills only: skills/_shared/scripts/check-skills
line 7
Very specific:
If HANDOFF.md exists, read it before starting.
line 11
Very specific:
If AGENTS.local.md exists, read it.
line 12

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “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

AGENTS.md

Commands

Prepare a fresh worktree: scripts/worktree-setup
Verify, the same command CI runs: scripts/verify
Check the skills only: skills/_shared/scripts/check-skills

Before you start

If HANDOFF.md exists, read it before starting.
If AGENTS.local.md exists, read it. It holds private notes for this checkout and git ignores it.
A change to a user-facing surface updates its docs page in the same change. If the writing-docs skill is installed, run it in update mode.

Rules

Rule	Enforced by
Each skill passes the structural checks in `check-skills`: frontmatter that parses as YAML (needs `ruby` on PATH), its keys, `name` matching its folder, a description, some referenced paths, copies of `_shared` files that match the original, and script headers. It does not check every reference; read the script for the exact rules.	`skills/_shared/scripts/check-skills`
`bin/skills`, `.githooks/*`, `scripts/verify`, `scripts/worktree-setup` and the skills' shell scripts (named one by one in `scripts/verify`) pass shell lint (needs `shellcheck` on PATH)	`shellcheck -x`, in `scripts/verify`
Relative links and anchors in `README.md` and `AGENTS.md` resolve, and so do code-span paths whose first folder exists. `skills/` is not link-checked: skill docs name files in the repo a skill works on.	`skills/_shared/scripts/check-links`, in `scripts/verify`

Needs the owner

A change to one of these paths is never merged by an agent alone.

bin/skills
.githooks/

Where notes go

A note that a stranger who cloned this repo could use goes in this file. Local paths, personal workflow and private context go in AGENTS.local.md. Never put content in AGENTS.override.md.

@AGENTS.local.md

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.

Check your setup, free