gh-xjgh-xj/agent-repo-kit/AGENTS.md

agent-repo-kit

AGENTS.md0 starsChanged 6 months agoMITView on GitHub

You are inside agent-repo-kit. This repo publishes a convention for other repos to adopt, and it also adopts that same convention on itself (see the ## Conventions block below) — so task verify runs here. Before changing conventions, persistent state models, agent workflows, or repo-wide architecture, read docs/core-belief.md. It is the philosophical north star for this repo; this file is the operational map. - skills/ — canonical, harness-free skill sources. One directory per skill: - skills/convention-engineering/ — content describing repo…

Installs packages

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,774 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 repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- attack-architectureSkill
- convention-engineeringSkill
- go-scriptingSkill
- harness-routerSkill
- paper-vettingSkill
- skill-builderSkill
- skill-cli-authoringSkill
- slock-epic-protocolSkill
- taskfile-authoringSkill
- work-cliSkill

The file

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

2 rules. About 0 are common, 0 are distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Before changing conventions, persistent state models, agent workflows, or repo-wide architecture, read docs/core-belief.md.
line 9
Very specific:
Do not: add harness-specific frontmatter (e.g.
line 49

≈ “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

AGENTS.md — agent-repo-kit

You are inside agent-repo-kit. This repo publishes a convention for other repos to adopt, and it also adopts that same convention on itself (see the ## Conventions block below) — so task verify runs here.

Core belief

Before changing conventions, persistent state models, agent workflows, or repo-wide architecture, read docs/core-belief.md. It is the philosophical north star for this repo; this file is the operational map.

Entry points

skills/ — canonical, harness-free skill sources. One directory per skill:
- skills/convention-engineering/ — content describing repo conventions (.conventions.yaml, agent docs, docs taxonomy, verification gates, work tracking, optional wiki). Canonical source. Includes the evaluation rubric for skeptical scoring under references/meta/.
- skills/skill-builder/ — skill for authoring and auditing agent skills (trigger wording, portable structure, reference extraction, runtime placement).
- skills/taskfile-authoring/ — skill for writing canonical Taskfiles (structure, composition, anti-patterns).
- skills/attack-architecture/ — adversarial architecture-review skill.
- skills/harness-router/ — proposal-only router for deciding where session learnings, user corrections, and harness improvements should persist across instructions, skills, docs, work records, memory, and verification surfaces.
- skills/work-cli/ — operating the .work/ tracker.
- skills/slock-epic-protocol/ — maintain Slock agent ↔ epic repo ↔ leaf repo protocol: registry mapping, pointer-only memory, generated symlinks, per-leaf work, skill mirrors, and handoffs.
- skills/paper-vetting/ — vet a research paper through three independent lenses (team / citation context / claim-level evidence) before reading it; outputs a calibrated trust band and falsifier.
The work CLI and its feature-development skill live in the external work-cli repo.
adapters/<harness>/ — generated full copies that expose every skill under skills/ to a specific harness. claude-code/ and codex/ are shipped install targets; cursor/ is placeholder docs.
adapters/manifest.json — registered harness discovery roots.
adapters/generated-files.json — generated-file ownership and hashes; the live canonical skill directories determine the skill set.

Rules for editing this repo

Do not add harness-specific frontmatter (e.g. Claude skill YAML) to files under skills/convention-engineering/. That belongs in adapters/claude-code/SKILL.md and equivalents. skills/skill-builder/SKILL.md is the exception: its portable frontmatter (name + description only) is the skill's interface.
Do not reference absolute user paths like /Users/... or ~/.claude/ inside any skill surface. Those are environment specifics. skills/convention-engineering/ must also avoid the harness names "Claude", "Skill tool", and "Codex" — but skills/skill-builder/ and skills/attack-architecture/ may name them since the runtimes (and their agent/tool APIs) are the subject matter of those skills.
Adapters re-export, they don't own. An adapter file should be a generated full copy of a skill under skills/; edit canonical sources, then run task sync:adapters. Ownership is recorded in adapters/generated-files.json.

Testing

task verify   # asserts declared opt-ins via scripts/verify.sh

CI runs task verify on every push and PR (see .github/workflows/ci.yml). The job installs the external work binary and yq before running.

Conventions

Docs — tracked repo docs live under docs/ using the requests/, planning/, plans/, implementation/, and taxonomy/ folders.
Work — local-first work tracker at .work/. The CLI is the external work-cli binary; ARK no longer ships a copy. Install it (go install github.com/gh-xj/work-cli/cmd/work@latest or via the release tarball), then drive it through task work -- .... Local state lives in the ignored .work/config.yaml and .work/items/*.yaml. Daily commands: task work -- inbox, task work -- inbox add "title", task work -- triage accept IN-0001, task work -- view ready, and task work -- show W-0001.
Conventions descriptor — .conventions.yaml at the repo root declares which conventions this repo opts into, including min_work_version for the external work CLI. Read by the convention-engineering skill for bootstrap and audit; enforced by scripts/verify.sh.

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