PBandDevPBandDev/skills/AGENTS.md

skills

AGENTS.md0 starsChanged 37 days agoMITView on GitHub

This repository publishes reusable agent skills through GitHub and skills.sh. Keep changes small, public-facing, and easy to validate. Run local discovery before pushing: When skills/tracker-board changed, also run its tests (Node 22.18+): skills.sh indexes public GitHub skills through skills CLI installs. After pushing to GitHub, run installs from a temporary directory so the local repo stays untouched: Issues and specs live as gitignored markdown files under .scratch/<feature-slug>/. See docs/agents/issue-tracker.md. Default five-role vocabulary, recorded as a Status: line in each issue…

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 repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anima-promptingSkill
- artcraftSkill
- electrobunSkill
- lanraragiSkill
- photocraftSkill
- pixi-vnSkill
- spitballingSkill
- tolariaSkill
- tracker-boardSkill

The file

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

11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.

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

Common
Distinctive
Very specific

Distinctive:
Use lowercase kebab-case folder names.
line 14
Distinctive:
Keep each skill focused on one reusable workflow or domain.
line 15
Very specific:
Avoid local paths, private notes, research artifacts, or dated claims in public SKILL.md files.
line 17
Distinctive:
Write for an agent in any harness (Claude Code, Codex, Cursor) that has only this skill and its own tools.
line 18
Distinctive:
If a skill targets a specific library version, state the version it was written for.
line 19
Distinctive:
Run local discovery before pushing:
line 23
Very specific:
When skills/tracker-board changed, also run its tests (Node 22.18+):
line 29
Distinctive:
Check git status --short before editing and before finishing.
line 45
Distinctive:
Do not revert unrelated user changes.
line 47
Distinctive:
Commit only the files relevant to the requested change.
line 48
Very specific:
Default five-role vocabulary, recorded as a Status: line in each issue file.
line 58

≈ “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 publishes reusable agent skills through GitHub and skills.sh. Keep changes small, public-facing, and easy to validate.

Repository Layout

Skills live in skills/<skill-name>/.
Each skill needs SKILL.md with name and description frontmatter.
agents/openai.yaml is optional UI metadata for Codex-compatible surfaces.
README.md this is a user-facing README for the repository as a whole. Should not contain development-specific notes.

Skill Authoring

Use lowercase kebab-case folder names.
Keep each skill focused on one reusable workflow or domain.
Optimize description for trigger conditions, not workflow summaries.
Avoid local paths, private notes, research artifacts, or dated claims in public SKILL.md files.
Write for an agent in any harness (Claude Code, Codex, Cursor) that has only this skill and its own tools. A step that relies on a host app's system prompt, bundled docs, or MCP server also gives the path for an agent without it.
If a skill targets a specific library version, state the version it was written for.

Validation

Run local discovery before pushing:

npx skills add . --list

When skills/tracker-board changed, also run its tests (Node 22.18+):

cd skills/tracker-board && node --test

skills.sh Indexing

skills.sh indexes public GitHub skills through skills CLI installs. After pushing to GitHub, run installs from a temporary directory so the local repo stays untouched:

tmp="$(mktemp -d)" && cd "$tmp" && npx skills add PBandDev/skills --skill <skill-name> --yes

Git Hygiene

Check git status --short before editing and before finishing.
.changeset/ is ignored on purpose; never stage, force-add, or commit its contents.
Do not revert unrelated user changes.
Commit only the files relevant to the requested change.

Agent skills

Issue tracker

Issues and specs live as gitignored markdown files under .scratch/<feature-slug>/. See docs/agents/issue-tracker.md.

Triage labels

Default five-role vocabulary, recorded as a Status: line in each issue file. See docs/agents/triage-labels.md.

Domain docs

Single-context — GLOSSARY.md + docs/adr/ at the repo root. See docs/agents/domain.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