agentleFS
Sign inStart free
aantoniadisaantoniadis/skills/AGENTS.md

skills

AGENTS.md0 starsChanged 33 days agoMITView on GitHub

Before creating or editing agent-facing instructions, invoke Matt's original writing-for-agents through the host, as package references say, and apply our technical-English guide. Check that edits preserve conditions, permissions, obligations, and evidence limits. Sourced from Anthropic's skill best practices, the Claude Code skills reference, the agentskills.io specification, and Matt's writing-for-agents. Check each before a skill change ships: - Description: third person; what the skill does and when to use it, in the words a user would type; what it is 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 31,542 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 repository8 other files it gives its agents.

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

    Before creating or editing agent-facing instructions, invoke Matt's original writing-for-agents through the host, as package references …

    line 3
  2. Distinctive:

    Check each before a skill change ships:

    line 12

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

Authoring skills

Before creating or editing agent-facing instructions, invoke Matt's original writing-for-agents through the host, as package references say, and apply our technical-English guide. Check that edits preserve conditions, permissions, obligations, and evidence limits.

Skill authoring checklist

Sourced from Anthropic's skill best practices, the Claude Code skills reference, the agentskills.io specification, and Matt's writing-for-agents. Check each before a skill change ships:

  • Description: third person; what the skill does and when to use it, in the words a user would type; what it is not for when a neighbor overlaps. No workflow summary, because an agent may follow the description instead of the body.
  • Order: the most important instructions near the top of SKILL.md. After compaction, Claude Code keeps only the first 5,000 tokens of each invoked skill, within 25,000 tokens for all of them, and can drop older skills entirely; invoking the skill again restores it.
  • Size: SKILL.md under 500 lines; reference files linked one level deep from SKILL.md; a contents list on a reference file over 100 lines.
  • Freedom: exact commands for fragile sequences such as baselines, checkers, and renderers; prose for judgment. A deterministic step is a script.
  • Claude Code does not re-read a skill after invocation. A rule that must hold on every turn is either a host hook or prose phrased for the whole task, as in "before every delivery"; this package uses prose.
  • One term per concept across all skill files; no dates or versions that go stale, except inside a marked example.
  • Validate: claude plugin validate . and claude plugin validate skills, the local test suite, and one realistic prompt per trigger branch when a description changes. For a behavior change, run the affected evals/ cases against the branch and a main worktree, three runs each, with python3 evals/run.py --plugin-dir <checkout> --out <new scratch dir>; --regrade re-judges saved outputs after a rubric edit. Use it rather than claude plugin eval, which runs shell commands read-only and without git, which these skills need for probes, worktrees, and reports.

Shipping

Bump the version in package.json, .claude-plugin/plugin.json, and .codex-plugin/plugin.json in the PR; the namespace test fails when they differ. Run python3 -m unittest discover -s tests -q and the two validate commands; the report fixture test renders a diagram, so run npm ci --prefix skills/diagram-renderer once in a fresh checkout. Every merge to main is a release: tag the merge commit v<version>.

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