agentleFS
Sign inStart free
ShmalexMShmalexM/agent-skills/AGENTS.md

agent-skills

AGENTS.md0 starsChanged 20 days agoMITView on GitHub

Every skill in this repo must load and work in Claude Code, Codex, OpenCode and the DeepSeek harness, for any user. (npm run check runs the same thing.) For a change to bin/ or lib/ that affects how a harness is called, also run subagent doctor --probe, which sends one short task per harness.

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

5 rules. About 0 are common, 1 is distinctive, and 4 are 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.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every skill in this repo must load and work in Claude Code, Codex, OpenCode and the DeepSeek harness, for any user.

    line 3
  2. Very specific:

    Write the body for any harness.

    line 17
  3. Very specific:

    Write for any user. Personal context (names, projects, internal tools, private paths, report folders) belongs in …

    line 18
  4. Very specific:

    Write prose in plain style: follow skills/explain-style/SKILL.md.

    line 22
  5. Very specific:

    No secrets, customer data or private content.

    line 23

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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

Working on agent-skills

Every skill in this repo must load and work in Claude Code, Codex, OpenCode and the DeepSeek harness, for any user.

Layout

  • skills/<name>/SKILL.md is a skill. Bundled files sit next to it in references/ and scripts/.
  • bin/subagent and lib/subagent/ are the dispatch CLI. No dependencies; Node 20+.
  • config/tiers.json holds the default model per harness and tier. config/profile.example.md is the template for a user's profile.
  • install.sh links skills into ~/.claude/skills and ~/.agents/skills.
  • scripts/validate.mjs and test/ are the checks.

Rules for a skill

  • Frontmatter has only name (kebab-case, equal to the folder name) and description (1024 characters or fewer). Other fields are not read by every harness.
  • The description says what the skill does and when to use it, with the trigger phrases (for example "Use when the user types /name or asks ...").
  • Write the body for any harness. When a step needs a harness-specific tool, name the tool for each harness, or give a fallback that works from a shell. skills/state-of-the-world/SKILL.md (diagram routes) shows the pattern.
  • Write for any user. Personal context (names, projects, internal tools, private paths, report folders) belongs in ~/.config/agent-skills/profile.md. A skill that needs it says "read the user profile if it exists" and works without it.
  • Skills that change things outside the machine (repos, cloud, messages) audit first, show a plan, and act only after the user says yes.
  • Refer to bundled files by relative path (references/x.md, scripts/y.mjs). The validator checks they exist.
  • Scripts in skills use Node or Python with no dependencies. Keep the logic that decides pass or fail in pure functions, and test them with fixtures in test/.
  • Write prose in plain style: follow skills/explain-style/SKILL.md.
  • No secrets, customer data or private content. Keep your own private-terms list in ~/.config/agent-skills/private-terms.txt so the validator can catch slips.

Before you commit

node scripts/validate.mjs && node --test test/*.test.mjs

(npm run check runs the same thing.) For a change to bin/ or lib/ that affects how a harness is called, also run subagent doctor --probe, which sends one short task per harness.

Download now (ZIP)

  • 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 28,693 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 repository11 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

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