mgratzermgratzer/forge/AGENTS.md

forge

AGENTS.md86 starsChanged 8 days agoMITView on GitHub

Forge is a collection of agent skills that define a structured development workflow with pluggable issue tracking, following the Agent Skills standard. The skills are Markdown prompts with no build system. The repository root is also a Claude Code plugin that adds the lens (lens/), an optional TypeScript view over the text the skills print; see Lens. The skills never depend on the lens, and launchers and worktree setup stay the user's. This is the only project guidance file; there…

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 repository10 other files it gives its agents.
- forge-address-pr-feedbackSkill
- forge-batchSkill
- forge-create-issueSkill
- forge-guardSkill
- forge-implementSkill
- forge-landSkill
- forge-reflectSkill
- forge-setup-projectSkill
- forge-shapeSkill
- forge-shipSkill

The file

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

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

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

Common
Distinctive
Very specific

Distinctive:
Update docs when you change skill conventions or add new skills.
line 34
Very specific:
Never invent content: Use  markers rather than generic boilerplate.
line 39
Distinctive:
Standards first: Prefer AGENTS.md and Agent Skills conventions.
line 40

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

Forge

Forge is a collection of agent skills that define a structured development workflow with pluggable issue tracking, following the Agent Skills standard. The skills are Markdown prompts with no build system. The repository root is also a Claude Code plugin that adds the lens (lens/), an optional TypeScript view over the text the skills print; see Lens. The skills never depend on the lens, and launchers and worktree setup stay the user's.

This is the only project guidance file; there is no CLAUDE.md (Claude Code reads AGENTS.md natively).

Commands

scripts/check-skills.sh                            # skill structure and the lens contract (Node 22.6+); prints nothing when healthy
npx @biomejs/biome@2.6.2 check --write .           # lint and format the lens (the version in biome.json)
claude plugin validate . && claude plugin test .   # plugin manifests and lens tests

CI runs all three on every pull request; see Testing.

Shared modules are edited only in skills/_shared/. scripts/sync-shared.sh copies them into each skill, and scripts/check-skills.sh fails when a copy drifts.

Skill prompts are forge's runtime, so a change under skills/ is exercised, not reported as no runtime change: run the changed skill (or forge-land's judge, for a rubric change) from a snapshot of the branch in a sandbox repository, with a snapshot of the branch's base as the control. The commands are in Testing: Exercise a Skill Change.

Documentation

Document	Purpose
Context	Shared vocabulary used across forge skills
Architecture	Workflow, context limits, design decisions
Development	Adding and modifying skills
Coding Guidelines	Skill and role file format, authoring conventions
Testing	Automated checks, exercising a skill change, per-skill scenarios
PR Workflow	Commits, branch naming, review
Unattended Shipping	Guard loop, Waves, launchers, project setup
Lens	The lens's views and the text formats it reads

Update docs when you change skill conventions or add new skills.

Principles

Explore first, ask second. Skills analyze the codebase before asking the user questions.
Never invent content. Use  markers rather than generic boilerplate.
Standards first. Prefer AGENTS.md and Agent Skills conventions; keep vendor-specific compatibility light.
Plan before code. For complex work, research the codebase objectively and align on architecture first, with research delegated to sub-agents.
Mind the instruction budget. Keep skills under ~35 instructions.

Commits

Format: <type>(<scope>): <description>. Types: feat, fix, docs, refactor, test, chore, perf. See PR Workflow.

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