andeeplusandeeplus/aplus/AGENTS.md

aplus

AGENTS.md2 starsChanged 38 days agoMITView on GitHub

This repository is the aplus plugin: generic agent skills, plus a thin manifest for each tool that loads them. Inside a skill, progressive disclosure keeps what an agent loads small: An agent reads top to bottom and acts early, so a skill puts each part before the step that needs it. Every skill uses this order and omits the sections it does not need. Vendored skills keep their source's shape. pnpm check enfo

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,843 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 repository18 other files it gives its agents.
- atlassianSkill
- auditSkill
- code-qualitySkill
- commit-expertSkill
- create-issueSkill
- create-prSkill
- debugSkill
- defineSkill
- deliverSkill
- final-reviewSkill
- gherkinSkill
- githubSkill
- handoffSkill
- plainSkill
- second-opinionSkill
- senior-technical-writerSkill
- testingSkill
- triageSkill

The file

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

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

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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

Very specific:
Script it: If two agents could do a step differently, write a script and make SKILL.md say to run it.
line 26
Distinctive:
Attribute third-party material: Keep the license beside the skill, with its source revision and a short note of local modifications.
line 31

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

Agent instructions

This repository is the aplus plugin: generic agent skills, plus a thin manifest for each tool that loads them.

Layout

Path	Holds
`skills/<name>/`	One folder per skill. Every tool reads this folder.
`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `.github/plugin/`, `.agents/plugins/`	Manifests and marketplaces. They only point at `skills/`; keep them thin.
`.opencode/plugins/index.js` (the `main` of `package.json`), the `pi` key in `package.json`	The OpenCode plugin and the Pi package. They only register `skills/`.

Inside a skill, progressive disclosure keeps what an agent loads small:

Path	Holds	Loaded
`SKILL.md`	When to use the skill, its hard rules, and a table mapping each task to a reference or script. Keep it short.	When the skill triggers
`references/*.md`	Detail for one task: formats, procedures, patterns	When the routing table points at it
`scripts/*`	Deterministic steps: validation, creation, anything that must come out the same every time	Run, not read
`assets/*`	Files to copy and fill in	When producing that file

Rules for skills

Concise. Say each thing once, in as few words as it needs. Keep SKILL.md to the core flow and a routing table, with detail in references, where that split helps. Be pragmatic about size: a longer skill that reads best as one file stays one file.
Generic. A skill names no project, command, branch or path. For those it follows project instructions and resolves missing details from configuration, scripts, CI and nearby code. A workflow skill names no host or tracker either: it defers to the platform skill, such as github.
Script it. If two agents could do a step differently, write a script and make SKILL.md say to run it. Never reimplement a script's job by hand.
Schemas live in the project. Issue forms, labels and the pull request template are in the project's .github/. Skills read them; they do not restate them.
Current only. Skills, docs and commit messages describe what is supported now. Leave out what was renamed, replaced, deprecated or removed, and its old names.
Say what to do. Describe the supported path. Do not describe an action a skill does not support, even to forbid it: naming it suggests it.
Link, don't copy. Skills link to each other with relative paths, such as ../final-review/SKILL.md.
Attribute third-party material. Keep the license beside the skill, with its source revision and a short note of local modifications.
Mark imported entry points. An imported entry point sets metadata.vendored: "true" in frontmatter to retain its source's shape. An aplus entry point follows the local skill shape.

Shape of a `SKILL.md`

An agent reads top to bottom and acts early, so a skill puts each part before the step that needs it. Every skill uses this order and omits the sections it does not need. Vendored skills keep their source's shape. pnpm check enforces the description and the heading order.

description: what the skill does, then a sentence starting Use that lists the words a user types for it. It is all a harness reads to decide whether to load the skill: keep the trigger words.
# Title, then one line: the contract, or the stance the skill takes. A skill with a long flow adds it as one line, such as clarify → audit → ship.
Project context, when needed, is a rule or a flow step: name the instructions, configuration or conventions the task reads.
## Rules: bullets that start with a bold imperative.
## References: a Task | Read table, one row per reference.
Domain sections, named by noun, such as Format or Posture: the knowledge the skill applies.
## Script: the command, run as written, and what it does.
## Flow: numbered steps, one action each, led by a verb. A skill with several flows names each by its verb, such as Pause and Pick up, and puts no ## Flow heading.
## Output: the exact shape of what the skill returns.

Vocabulary

One word per concept, in every skill and reference. Skills ship without this file, so a skill still says what a term means where it first uses it, such as "scratch files outside the tree".

Word	Means
publish	Any action others see: push, open or edit a PR or issue, comment, transition, merge.
host, tracker	Where code and PRs live; where issues live.
integration branch	The branch PRs target.
gate, verdict	A check that must pass; its one-line result.
finding	A review result, classed `easy`, `nit` or `rework`.
track	A group of a program's issues shipped as one branch and one PR, each issue as its own commits.
track gate, issue gates	A track's gate run once over the track (the default); run after each issue's commits instead.
draft	An issue as a file, before it is created.
scratch file	A file outside the tree, never committed.
loop	The one command that reproduces a symptom.

Versions and changelog

Changesets owns the version. Every change a user notices adds a changeset in .changeset/, written by hand as the commit-expert skill describes. Every changeset is a patch for now. Its summary starts with the skill's name, such as triage: ask for a reproduction before labelling.
The release workflow (.github/workflows/release.yml) runs on every push to main:
1. It runs pnpm check first; a failure stops the release.
2. While changesets are pending, it opens or updates the chore: release v<version> PR. On the PR's branch it runs pnpm changeset:version, which bumps package.json, writes CHANGELOG.md, and copies the version into each tool's plugin manifest. pnpm check fails when a manifest's version differs from package.json.
3. Merging that PR tags the commit v<version> and creates the GitHub release.
The workflow opens the release PR with its own token, so CI does not run on the PR; step 1 checks it once it merges. The repository's Actions settings must allow GitHub Actions to create pull requests.
An installed copy stays on its version until the version changes. To try unreleased changes in Claude Code, load this folder for one session: claude --plugin-dir <path to this repository>.

Commits

Conventional commits, type(skill): outcome, as the commit-expert skill describes. Prettier formats the repository (.prettierrc.json).

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