agents-skills
AGENTS.md11 starsChanged 6 days agoMITView on GitHub
Shared instructions for AI coding tools (Cursor, GitHub Copilot, OpenAI Codex, and any tool honoring AGENTS.md). Claude Code uses CLAUDE.md, which carries the same guidance — keep the two in sync; this file is the tool-neutral mirror. A public, shareable collection of AI toolchains — Skills and Agents — meant to be consumed by others across multiple AI coding tools (Claude Code, GitHub Copilot, Cursor). It is a content/config repo: no application code, no build step, no test runner. "Correctness"…
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 repository34 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- browser-diagnosisSkill
- cavemanSkill
- ci-flake-huntingSkill
- ci-speed-huntingSkill
- deploy-watchingSkill
- dispatching-subagentsSkill
- doc-coauthoringSkill
- docxSkill
- driving-prs-to-mergeSkill
- fast-forwarding-branchesSkill
- figmaSkill
- figma-specsSkill
- gh-issue-filingSkill
- gh-issue-labelsSkill
- gh-issue-lockingSkill
- grooming-issuesSkill
- humanizerSkill
- jira-issue-fieldsSkill
- jira-issue-filingSkill
- jira-issue-lockingSkill
- mcp-builderSkill
- orchestrating-slotsSkill
- pdfSkill
- pptxSkill
- pr-checksSkill
- pr-cleanupSkill
- pr-commentsSkill
- skill-creatorSkill
- spelunking-specsSkill
- technical-reconSkill
- token-bleed-huntingSkill
- xlsxSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Treat a skill/agent name as a public API: renaming breaks consumers who invoke it by name.
- Very specific: line 41
Slash commands: don't share a home or format, so the canonical .claude/commands/*.md are mirrored per tool by scripts/sync-commands.py …
- Distinctive: line 60
Write artifact bodies in plain, tool-neutral language.
- Very specific: line 61
Keep frontmatter description action-oriented and specific — tools use it to decide when to trigger.
≈ “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
AGENTS.md
Shared instructions for AI coding tools (Cursor, GitHub Copilot, OpenAI Codex, and any tool honoring AGENTS.md). Claude Code uses CLAUDE.md, which carries the same guidance — keep the two in sync; this file is the tool-neutral mirror.
What this repository is
A public, shareable collection of AI toolchains — Skills and Agents — meant to be consumed by others across multiple AI coding tools (Claude Code, GitHub Copilot, Cursor). It is a content/config repo: no application code, no build step, no test runner. "Correctness" means each artifact is valid for its target tool and works when dropped into a consumer's environment.
Because it is public and reusable, every artifact must be clean of personal and prior-project data: no employer names, internal URLs, ticket IDs, secrets, private file paths, or learnings that only make sense inside one codebase. Keep learnings isolated — phrased generically so they apply anywhere.
Primary goal: extreme token savings at the highest practical accuracy. Every authored skill operates in caveman mode, and model spend is tiered (cheapest capable model per task, mechanical work offloaded to a cheap-tier subagent, premium reserved for operator-gated hard reasoning) — see MODEL-DEFAULTS.md.
Repository layout
.claude/skills/<skill-name>/SKILL.md— one directory per skill; YAML frontmatter (name,description) + body. Supporting files (references/, scripts) alongside..claude/agents/<agent-name>.md— one file per agent; frontmatter (name,description,tools, optionalmodel) + system prompt. Ships 18 tiered worker agents (scoutcheap;builder/reviewer/implementer/pr-rescuer/diagnostician/verifier/spelunker/design-mapperworkhorse — these the commands dispatch — plus thepr-dispatcher/pr-comments/pr-checks/pr-cleanupsingle-lane PR watchers, thedeploy-watcherdeploy-health lane, and theci-speed-hunter/ci-flake-huntercontinuous CI lanes, thetoken-bleed-huntertoken-efficiency lane and thebranch-fffast-forward lane, all run via/loop). Mirrored to Cursor (.cursor/agents/), Copilot (.github/agents/*.agent.md), Kiro (.kiro/agents/), OpenCode (.opencode/agents/) and Codex (.codex/agents/*.toml) viamake sync-agents; never hand-edit the mirrors (.codex/config.tomlis hand-maintained). Skills are exposed to Kiro, OpenCode and Codex (same Agent Skills format) as symlinks.kiro/skills/.opencode/skills/.agents/skills→.claude/skillsviamake sync-skills..claude-plugin/marketplace.json+plugins/agents-skills/(Claude Code) and.cursor-plugin/marketplace.json+plugins/agents-skills-cursor/(Cursor) and.agents/plugins/marketplace.json+plugins/agents-skills-codex/(Codex/ChatGPT, skills only) — this repo is its own plugin marketplace for all three ecosystems. The plugin payload is generated from.claude/{skills,agents,commands}viamake build-plugin; never hand-edit it. Released by.github/workflows/release-plugin.ymlas CalVerYYYY.M.D.N, taggedv<version>, with one zip per plugin + per-skill zips..claude/settings.json— Claude Code config (model: opus,includeCoAuthoredBy: false).CLAUDE.md— Claude Code's copy of this guidance.README.md— human entry point.GLOSSARY.md— the repo's vocabulary (slot, dispatcher, watcher, hunting, ci-speed, flake, token bleed). The distinctions are load-bearing.
Two kinds of skill
- Self-contained skills — full instructions live here.
- Pointer skills — a thin
SKILL.mdpointing to an upstream project's skill so the latest version is always used. The name defined here is the contract — keep it stable even when the upstream target moves. Don't inline upstream content.
Treat a skill/agent name as a public API: renaming breaks consumers who invoke it by name.
Cross-tool consumability
Author content once (canonically under .claude/) and expose it to the other tools rather than forking copies:
- Claude Code — reads
CLAUDE.md,.claude/skills/,.claude/agents/. - GitHub Copilot — reads
.github/copilot-instructions.md(points here) and thisAGENTS.md; agents in.github/agents/. - Cursor — reads this
AGENTS.md(and.cursor/rules/*.mdcif you add project rules); agents in.cursor/agents/. - Kiro — agents in
.kiro/agents/, skills in.kiro/skills/(Anthropic Agent Skills format). - OpenCode — agents in
.opencode/agents/, skills in.opencode/skills/(same Agent Skills format). - OpenAI Codex (CLI, IDE extension, ChatGPT desktop app) — reads this
AGENTS.md; skills in.agents/skills/; custom agents in.codex/agents/*.toml; custom prompts from~/.codex/prompts/only. The project.codex/layer loads only once the project is trusted. ChatGPT web/mobile runs skills only (Codex plugin or per-skill upload).
Slash commands don't share a home or format, so the canonical .claude/commands/*.md are mirrored per tool by scripts/sync-commands.py (make sync-commands; make check-commands for CI). Never hand-edit the mirrors — regenerate them. Filename = command name across all four:
- Claude Code —
.claude/commands/<name>.md(frontmatterdescription/argument-hint/allowed-tools;$ARGUMENTS). - Cursor —
.cursor/commands/<name>.md(plain markdown, no frontmatter; args = text after the command). - GitHub Copilot (VS Code) —
.github/prompts/<name>.prompt.md(frontmatterdescription/argument-hint/agent;${input:args}). Copilot CLI does not support custom commands yet. - Codex —
.codex/prompts/<name>.md(frontmatterdescription/argument-hint;$ARGUMENTS). Copied to~/.codex/prompts/, run as/prompts:<name>. Deprecated upstream in favour of skills.
Model selection policy
Model spend is tiered and Anthropic-first for reasoning — full task→tier matrix + per-platform model IDs in MODEL-DEFAULTS.md:
- Cheap / mechanical (
ls/grep/git status, lookups, listing, fixed-command runs) — Haiku 4.5 or each platform's cheapest native model (Copilot Raptor Mini, Cursor free Auto), always offloaded to a cheap-tier subagent returning a distilled caveman answer — never the main session. - Workhorse (default) — orchestration loop, verification, dev work, filing/grooming/recon: Sonnet 4.6.
- Premium (operator-gated) — hard cross-cutting reasoning only, never self-escalated: Opus 4.8.
Substitutes are acceptable only if they match context window (≈200K+, or 1M-class where needed) and reasoning tier — except the mechanical tier, which uses each platform's cheapest native model. State the substitution and why in the artifact.
Conventions
- Write artifact bodies in plain, tool-neutral language; don't assume a specific local environment.
- Keep frontmatter
descriptionaction-oriented and specific — tools use it to decide when to trigger. - Validate by structure (valid frontmatter, required keys, unique name); there is no test suite.
- Token discipline for the orchestration family (
dispatch,rescue,gh-issue-*/jira-issue-*commands and their skills): operate in caveman mode to conserve tokens across the high-volume loop, but write the durable prose a human reads — issue/ticket bodies and PR descriptions — through humanizer so it doesn't read AI-generated. Under both, machine-precise content (labels/fields, JQL,gh/MCP commands, lock markers, theRECON OK/RECON-ERRORcontract,file:linerefs, code blocks, acceptance-criteria checklists) stays byte-exact.
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.

