agentleFS
TheodoreADTheodoreAD/agent-skills/AGENTS.md

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…

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
  1. Very specific:

    Check the name is free before adopting it — skill-authoring-taudelta's names.py — because a duplicate is dropped silently and a rename …

    line 46
  2. Very specific:

    Keep the body to what an agent must follow.

    line 71
  3. Distinctive:

    When a rule is observed being missed in practice, strengthen its language rather than lengthen its explanation.

    line 76
  4. Distinctive:

    Every skill has to work for someone who has only this repo.

    line 145
  5. Very specific:

    Write about that work by its shape instead: "a work root with a <project>/<repo> hierarchy", "a client repo under review pressure", "work …

    line 161

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.setup once after cloning — creates .venv and wires direnv to it.
  • inv quality.precommit before considering a change done. Markdown is not exempt: dprint reflows prose, and a SKILL.md reflow is the most common CI failure in this repo family.
  • pytest — tests/unit/test_skill_layout.py validates 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.

  • description is 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.
  • name keeps 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 — so plan- and research- stay put, and -conveyor is where character goes. A slightly fantasy or sci-fi register is the house preference, admissible exactly while the word still denotes: manifold was rejected for telling a stranger nothing, and so were research-octopus and research-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's names.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. -docs never described what plan-conveyor became, so replacing it bought real information. -library already describes what research-library is, 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-taudelta and skill-authoring-taudelta are rulings and clash by nature, while plan-conveyor, research-library, skill-fitness and session-harvest do 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-standards is published by 17 repos, python-guidelines by 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 -conventions survived and the -defaults harmonisation was closed rather than decided. It also disclaims authority by fact rather than by connotation — python-canon reads 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 in skills/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 uses license almost everywhere. What that gate was right about is the sub-key: metadata: family: was a local invention five of fourteen skills carried, nothing read, and family already meant something else here. A half-covered taxonomy is worse than none, so a key under metadata: is still a decision recorded here and in KNOWN_METADATA_KEYS first; test_only_known_frontmatter_keys and test_metadata_keys_are_decided_not_added gate 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, and test_a_skill_that_touches_the_machine_discloses_it gates 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, and skill-authoring-taudelta says how to scrutinise one.
  • A skill directory may hold README.md, references/, scripts/ and evals/, and nothing else. evals/ was added 2026-08-31 for trigger cases — JSON files of prompts with the skill each should select, run by skills/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.md is the skill's page for a person deciding whether to adopt it, and is optional. Added 2026-09-30 because GitHub renders a directory's README.md and renders nothing for SKILL.md, so a catalogue link opened onto a bare file listing. It ships with every install (the skills CLI copies the whole directory) but no agent loads it, so it never carries instructions. It says what the skill is for and why, and links SKILL.md for how. Every claim in it has to hold against SKILL.md and the scripts, and any command output it shows is real output, trimmed. Its opening line passes repo-pitch's check. When a change alters what the README describes, update it in the same commit. The reasoning and the template are in plans/2026-09-10-repo-presentation-and-pitch-skill.md.
  • This repo's own test data lives in tests/fixtures/, never inside a skill. Everything under skills/ is shipped to strangers by skills add, so a file put there is published whether or not anyone meant to publish it. The derivable gate's baseline sat in skills/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 was tests/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 --compare at.
  • 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-taudelta carries the rule and what legitimately stays in prose, and fitness.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 against tests/fixtures/derivable-*.json fails tests/unit/test_derivable.py, so the gate reports it rather than the next reader.
  • An install command in a fenced block must carry --global when its source is an owner/repo. Without the flag the CLI picks scope from the reader's cwd and silently writes .agents/skills/, a .claude/skills symlink and a skills-lock.json into 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 tree

It 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.

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.