agent-skills
AGENTS.md0 starsChanged 49 days agoMITView on GitHub
Cross-tool instructions for AI coding agents working in this repo. Universal conventions live in the home-level instructions file, ~/.agents/AGENTS.md — read natively by agents following the .agents/ convention, copied to each other agent's own path (~/.claude/CLAUDE.md for Claude Code) — and nothing there is repeated here, only what is specific to this repo. A skill that points its reader at the home file names ~/.agents/AGENTS.md; ~/AGENTS.md is read by no agent. CLAUDE.md is a plain symlink to this file, not…
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 repository16 other files it gives its agents.
- db-defaults-taudeltaSkill
- invoke-task-conventions-taudeltaSkill
- mcp-python-conventions-taudeltaSkill
- mcp-server-shippingSkill
- plan-conveyorSkill
- polite-mcp-conventions-taudeltaSkill
- python-conventions-taudeltaSkill
- python-refactor-auditSkill
- python-testing-conventions-taudeltaSkill
- release-heraldSkill
- repo-pitchSkill
- research-librarySkill
- session-bash-auditSkill
- session-harvestSkill
- skill-authoring-taudeltaSkill
- skill-fitnessSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 46
Check the name is free before adopting it — skill-authoring-taudelta's names.py — because a duplicate is dropped silently and a rename …
- Very specific: line 71
Keep the body to what an agent must follow.
- Distinctive: line 76
When a rule is observed being missed in practice, strengthen its language rather than lengthen its explanation.
- Distinctive: line 145
Every skill has to work for someone who has only this repo.
- Very specific: line 161
Write about that work by its shape instead: "a work root with a <project>/<repo> hierarchy", "a client repo under review pressure", "work …
≈ “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
Agent instructions for agent-skills
Cross-tool instructions for AI coding agents working in this repo. Universal conventions live in the
home-level instructions file, ~/.agents/AGENTS.md — read natively by agents following the
.agents/ convention, copied to each other agent's own path (~/.claude/CLAUDE.md for Claude Code)
— and nothing there is repeated here, only what is specific to this repo. A skill that points its
reader at the home file names ~/.agents/AGENTS.md; ~/AGENTS.md is read by no agent. CLAUDE.md
is a plain symlink to this file, not a wrapper that imports it, so every harness reads
byte-identical content.
What this repo is
A published set of Agent Skills, installed by consumers through the
skills CLI (npx skills add TheodoreAD/agent-skills). It
is not a machine setup, not a library, and not a Claude Code plugin. The only artifact formats
admitted here are the vendor-neutral ones: SKILL.md (plus its references/, scripts/,
evals/), AGENTS.md, and MCP. A vendor manifest — .claude-plugin/, a marketplace entry, a
harness-specific rules directory — does not belong in this repo even as a convenience.
Build & test
inv dev-env.setuponce after cloning — creates.venvand wires direnv to it.inv quality.precommitbefore considering a change done. Markdown is not exempt:dprintreflows prose, and aSKILL.mdreflow is the most common CI failure in this repo family.pytest—tests/unit/test_skill_layout.pyvalidates every skill's frontmatter and layout. It is the gate a new skill has to pass, so add the skill and run the suite rather than eyeballing the frontmatter.
Authoring a skill
Cut a skill by responsibility, and give it a trigger that cannot contend with another skill's.
Two skills whose description fields both plausibly match the same request is the failure mode to
design against — the agent picks one, and which one is not predictable. If a new skill's trigger
overlaps an existing one, the fix is redrawing the boundary between them, not wording the
description more carefully.
descriptionis the field agents actually match on. Write it as a list of concrete situations ("Use when …, …, or …"), not as a summary of the skill's contents. Everything a reader needs in order to decide whether to open the file goes here; everything else goes in the body.namekeeps the domain in the first token and may carry flavour in the second. The first token is what a reader scans when a listing is truncated to bare names, which happens — soplan-andresearch-stay put, and-conveyoris where character goes. A slightly fantasy or sci-fi register is the house preference, admissible exactly while the word still denotes:manifoldwas rejected for telling a stranger nothing, and so wereresearch-octopusandresearch-guild, because the register is dense in nouns for a doer where most of these skills name a thing. Check the name is free before adopting it —skill-authoring-taudelta'snames.py— because a duplicate is dropped silently and a rename later reads as a delete.- The flavour slot is only free where the current word is inaccurate.
-docsnever described whatplan-conveyorbecame, so replacing it bought real information.-libraryalready describes whatresearch-libraryis, which is why the 2026-09-12 proposal to rename it was abandoned on 2026-09-27: flavour there would have traded accuracy for register and got nothing back. A name that is already right is finished. - A skill that asserts how to work carries the author mark
-taudelta; a skill that does a job does not. Adopted 2026-09-27 over eight renames. The test is whether another author would plausibly assert differently:python-conventions-taudelta,db-defaults-taudeltaandskill-authoring-taudeltaare rulings and clash by nature, whileplan-conveyor,research-library,skill-fitnessandsession-harvestdo a job and are named for the job. Two reasons, and the second is the one that generalises. Mechanically, an opinion-set name is the most contested slot there is —python-standardsis published by 17 repos,python-guidelinesby 9 — and first-seen-wins by traversal order, so a generic one cannot be defended or even observed losing. Editorially, the mark is what lets the accurate category word stay: a distinctive synonym buys the same immunity by trading away the word that describes the content, which is why-conventionssurvived and the-defaultsharmonisation was closed rather than decided. It also disclaims authority by fact rather than by connotation —python-canonreads as Python's canon, where the mark cannot. The position is the suffix, against the corpus habit (0 of 24 repos mark by suffix, 4 by prefix) and for three reasons: the mark must strip back to the name that citations already spell, a mark is legible only where its position is fixed, and a trailing qualifier is what the ecosystem uses for a variant (libssl-dev,python:3.12-slim) while a leading one is for a namespace. Full reasoning, the rejected marks, and what a rename does to the public index are inskills/skill-authoring-taudelta/references/naming.md. - Keep the body to what an agent must follow. Reasoning, prior art, measurements and rejected
alternatives go in
references/— loaded only when the agent needs them. - Cite evidence with a date when a rule came from something that actually happened ("Confirmed live 2026-08-23: …"). A rule with a story attached survives review; a bare assertion gets softened by the next editor who disagrees with it.
- When a rule is observed being missed in practice, strengthen its language rather than lengthen its explanation.
- A skill's frontmatter uses the specification's keys and no others:
name,description,license,compatibility,metadata,allowed-tools. Re-read from the spec 2026-09-05, which reversed a 2026-09-04 gate that allowed only the first two on the claim that "the reference corpus defines no such key" — the spec defines all six, and the reference corpus useslicensealmost everywhere. What that gate was right about is the sub-key:metadata: family:was a local invention five of fourteen skills carried, nothing read, andfamilyalready meant something else here. A half-covered taxonomy is worse than none, so a key undermetadata:is still a decision recorded here and inKNOWN_METADATA_KEYSfirst;test_only_known_frontmatter_keysandtest_metadata_keys_are_decided_not_addedgate both halves. compatibility:is the spec's field for environment requirements, and every skill that ships a script or instructs a write outside the session's repo declares one — the product it is meant for, the tools it shells out to, whether it reaches the network. A pure convention skill carries none; the spec's own note is that most skills do not need it.- Every skill that touches the machine discloses what it reads, runs and writes, under the fixed
heading
## What this skill reads, runs and writes, with a**Writes**line even when the answer is nothing. Asked for by the user 2026-09-03 as total transparency; the heading is fixed so a reader or a scanner finds it in the same place in every skill, andtest_a_skill_that_touches_the_machine_discloses_itgates its presence. The gate cannot check that a disclosure is true — it is a statement for a reader checking the skill by hand against its code, never a manifest anything enforces, andskill-authoring-taudeltasays how to scrutinise one. - A skill directory may hold
README.md,references/,scripts/andevals/, and nothing else.evals/was added 2026-08-31 for trigger cases — JSON files of prompts with the skill each should select, run byskills/skill-fitness/scripts/trigger.py. Write them for a pair the fitness analyzer flagged rather than a fixed number per skill, and include should-not-trigger cases: a suite of positives alone passes for a description that fires on everything. README.mdis the skill's page for a person deciding whether to adopt it, and is optional. Added 2026-09-30 because GitHub renders a directory'sREADME.mdand renders nothing forSKILL.md, so a catalogue link opened onto a bare file listing. It ships with every install (theskillsCLI copies the whole directory) but no agent loads it, so it never carries instructions. It says what the skill is for and why, and linksSKILL.mdfor how. Every claim in it has to hold againstSKILL.mdand the scripts, and any command output it shows is real output, trimmed. Its opening line passesrepo-pitch'scheck. When a change alters what the README describes, update it in the same commit. The reasoning and the template are inplans/2026-09-10-repo-presentation-and-pitch-skill.md.- This repo's own test data lives in
tests/fixtures/, never inside a skill. Everything underskills/is shipped to strangers byskills add, so a file put there is published whether or not anyone meant to publish it. The derivable gate's baseline sat inskills/skill-fitness/references/baselines/until 2026-09-03 for no better reason than that it was written by a script living nearby: it named this corpus's fourteen skills and their counts, the skill body never cited it, and its only consumer wastests/unit/test_derivable.py. The test is where such a file belongs. What legitimately ships is a measurement offered as evidence and labelled as somebody else's —session-bash-audit's baseline says so in its own body — never one a reader would reasonably point--compareat. - Anything the skill can derive deterministically belongs in
scripts/, not in the body — a CLI's flags, an HTTP request shape, a SQL query, a JSON traversal, any multi-step sequence. Prose telling an agent how to spell a command has to be followed correctly on every run and fails silently when it is not; a script is followed once.skill-authoring-taudeltacarries the rule and what legitimately stays in prose, andfitness.py derivable --compare <baseline>measures the drift, which is the part that actually happens: a skill grows one harmless-looking command line at a time. A rise againsttests/fixtures/derivable-*.jsonfailstests/unit/test_derivable.py, so the gate reports it rather than the next reader. - An install command in a fenced block must carry
--globalwhen its source is anowner/repo. Without the flag the CLI picks scope from the reader's cwd and silently writes.agents/skills/, a.claude/skillssymlink and askills-lock.jsoninto whatever tree they are standing in. A local path (skills add ../my-skills) is the drafting form and is exempt; the gate enforces the distinction.
Don't reword a description on a hunch — measure it. skills/skill-fitness/ reports which skills
compete, which never fire, and what the skill listing costs; its trigger.py candidate mode scores
a proposed description against the real installed set before it is adopted. Published measurement
(SkillsBench, 47,150 skills) puts unmeasured model-authored skills below having no skill at all,
while curated ones are well above it — so drafting wording is fine and shipping it unmeasured is
not.
Skill scope, and what must not be here
Every skill has to work for someone who has only this repo. A rule that depends on one machine's
setup — a specific dotfile, a locally-installed task runner, a repo that exists on one box — belongs
in that machine's own AGENTS.md, not in a published skill. Where a skill genuinely needs an
environment assumption (a directory, an env var), it must say so in the skill itself rather than
failing mysteriously.
The README's Scope column records how portable each skill is. Keep it accurate when a skill changes; a skill that quietly grows a personal dependency is worse than one that declares it.
This repo is published: never name a client in it
No file here — skill, plan, commit message, test fixture — may name an employer, client, internal
project, work repo, work email address or ticket prefix. This repo is public on GitHub and
installed by strangers via npx skills add. Anything committed is published the moment it is
pushed, and a push cannot be taken back by an edit.
Write about that work by its shape instead: "a work root with a <project>/<repo> hierarchy", "a
client repo under review pressure", "work root A". Every measurement in this repo's plans is
expressible that way — the counts and the structure are the evidence, the names never were.
The check is mechanical, so run it rather than reading for it:
python3 skills/plan-conveyor/scripts/plans.py scan --mode staged # before every commit
python3 skills/plan-conveyor/scripts/plans.py scan # whole working treeIt derives the forbidden terms from the machine's own project roots, so nothing has to be listed
here — which is the point: a list of clients is itself the thing that must not be in a public repo.
Fixtures use invented names (client.com-bitbucket, github.com-acme) for the same reason.
Confirmed live 2026-08-28: a plan committed here listed six employer/client root directory names and one client's internal project path, and was pushed. The rule and the scanner both exist because that happened.
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.

