skills / skills
AGENTS.md6 starsChanged 20 days agoApache-2.0View on GitHub
skills/ contains the published packages. Before changing one, read ../docs/skills/skill-standard.md and the effective repository instructions. - Keep one public Skill per stable user intent and authority boundary. - Keep project task state in the target repository. to-task owns the reusable transformation and reconciliation workflow, not a catalog-side copy of any project's ledger. - Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output. - Keep SKILL.md as a concise entrypoint map using Entry…
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 32,671 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 repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- api-specSkill
- ask-aiSkill
- dev-frontendSkill
- dev-javaSkill
- dev-rustSkill
- dev-testsSkill
- dev-typescriptSkill
- domain-modelingSkill
- human-writingSkill
- ops-browserSkill
- ops-clientSkill
- ops-deviceSkill
- product-specSkill
- repo-auditSkill
- repo-deliverySkill
- repo-mapSkill
- repo-reviewSkill
- to-taskSkill
- ui-specSkill
- work-retroSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Keep one public Skill per stable user intent and authority boundary.
- Very specific: line 10
Keep project task state in the target repository.
- Distinctive: line 11
Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output.
- Very specific: line 13
Keep SKILL.md as a concise entrypoint map using Entry Gate, Route Map, Invariants, Output Map, and Reference Map.
- Distinctive: line 17
Keep those five non-empty sections unique and in that order.
- Very specific: line 22
Keep provider-specific metadata in its provider surface.
- Very specific: line 24
Keep host orchestration, receipt/storage lifecycles, adapter names, and host schema namespaces outside portable packages.
- Distinctive: line 26
Do not invent parallel per-provider files.
- Distinctive: line 28
Do not put installation, update, changelog, or repository-maintenance guidance in published packages.
- Very specific: line 35
When adding, renaming, or removing a package, update README.md, INSTALL.md, skills.sh.json, and skills-index.json in the same change.
- Very specific: line 42
Use risk-tiered validation during development.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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.
Files
Skills
skills/ contains the published packages. Before changing one, read
../docs/skills/skill-standard.md and the
effective repository instructions.
Design Rules
- Keep one public Skill per stable user intent and authority boundary.
- Keep project task state in the target repository.
to-taskowns the reusable transformation and reconciliation workflow, not a catalog-side copy of any project's ledger. - Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output.
- Keep
SKILL.mdas a concise entrypoint map using Entry Gate, Route Map, Invariants, Output Map, and Reference Map. Keep it at or below 8,000 Unicode characters; move route procedures, checklists, examples, and variants to directly linked one-level references loaded only for their named condition. - Keep those five non-empty sections unique and in that order. Only an optional non-empty Purpose H2 may precede them; local Markdown file and fragment links must resolve.
- Packages must be self-contained. They may use their own
scripts/,references/, andassets/, but must not depend on repository-root maintenance files at runtime. - Keep provider-specific metadata in its provider surface. This catalog includes
agents/openai.yamlfor OpenAI without treating it as portable frontmatter. - Keep host orchestration, receipt/storage lifecycles, adapter names, and host schema namespaces outside portable packages; Skills expose provider-neutral contracts.
- Do not invent parallel per-provider files. Add another provider surface only when that provider documents a real machine-readable contract that this catalog ships.
- Do not put installation, update, changelog, or repository-maintenance guidance in published packages.
- Preserve unrelated changes and keep Git mutation in
repo-delivery.
Shared package protocols are authored under protocols/ and synchronized with
python3 scripts/sync-shared-protocols.py; do not hand-edit generated copies.
When adding, renaming, or removing a package, update README.md, INSTALL.md,
skills.sh.json, and skills-index.json in the same change. When routing meaning,
nearest neighbors, or capability keywords change, update the semantic index even when
the package set stays the same.
Validation
Use risk-tiered validation during development. The canonical full gate remains
bash scripts/check-skills.sh; on macOS it resolves and verifies Homebrew Python,
refuses /usr/bin/python3, and uses uv with the pinned
requirements-dev.txt when available. Other platforms use their configured
PYTHON_BIN or python3.
For a bounded prose correction in one package, run exact-path whitespace/link checks and the smallest directly affected validator or regression. Do not run the full gate after every prose edit.
git diff --check -- skills/<name>For a behavior, metadata, routing, schema, shared-protocol, or package-structure
change, run the focused scripts/test_*.py cases and validators that cover the
changed contract, plus shared-protocol sync checks when applicable. Expand to every
affected consumer, but do not substitute an unrelated full suite for missing focused
coverage.
For merge, release, catalog delivery, final fixed-basis acceptance, or an explicit full-regression request, run:
bash scripts/check-skills.shFor behavior changes, keep the repository routing matrix synchronized with the
affected Skill's normal use, nearest non-trigger or owner boundary, and critical stop.
The full gate runs the deterministic routing matrix, its committed no-new-regression
baseline, and a warning-only context report. Do not rerun it after an unchanged full
pass unless the basis or relevant gate inputs changed. Real host/model behavior still
requires representative live tasks when claimed. For a new or materially changed
behavior, a real-failure repair, or an improvement claim, run the actual Agent on a
fixed targeted prompt set and capture JSONL trace plus task artifacts. Cover explicit
and implicit/contextual use, the nearest non-trigger, an applicable valid no-op, and the
critical stop; score observable selection, process, outputs/effects, honest stop state,
and efficiency separately. Keep public cases synthetic and project-neutral, keep raw
business/project evidence ignored or private, and require human confirmation before
replacing the maintained basis. Static gate counts cannot substitute for this live
capability result. An explicitly requested independent provider/model remains a
required live case dimension: absent or mismatched provider evidence is Not verified,
not a waived pass. A formal cross-model benchmark remains optional.
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
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.

