awesome-agent-conventions

<!-- GENERATED by scripts/build_readme.py - do not hand-edit. --> <!-- Edit scripts/targets.json (or per-convention pages), then re-run the script. --> <p align="center"> <img src="assets/hero.png" alt="Awesome Agent Conventions - convention files for AI agents" width="100%"> </p> # Awesome Agent Conventions <p align="center"> <a href="https://awesome.re"><img src="https://awesome.re/badge.svg" alt="Awesome"></a> <a href="https://github.com/ItamarZand88/awesome-agent-conventions/actions/workflows/verify.yml"><img src="https://github.com/ItamarZand88/awesome-agent-conventions/actions/workflows/verify.yml/badge.svg" alt="verify"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a> </p> **A curated field guide to the convention files AI agents read, write, and act on.** **21 conventions across 11 categories.** From common project instruction files to newer agent-web discovery and trust formats. Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot. This repo keeps the map practical: - **Know what a file is for.** Each entry names the convention, usual filename, primary readers, and spec or source. - **Study real examples.** Examples are fetched from public repositories by script, with provenance kept at the top of each file. - **Separate practice from proposal.** Maturity labels show what is widely used, what is early, and what is still only proposed. ## Contents - [Instruction & context](#instruction--context) · [category page](categories/instruction-context.md) - 🟢 [AGENTS.md](conventions/agents-md/) - 🟢 [CLAUDE.md](conventions/claude-md/) - 🟢 [Tool-specific instruction files](conventions/tool-specific-instructions/) - [Memory & state](#memory--state) · [category page](categories/memory-state.md) - 🟢 [MEMORY.md](conventions/memory-md/) - 🟢 [Memory Bank](conventions/memory-bank/) - [Spec-driven development](#spec-driven-development) · [category page](categories/spec-driven-development.md) - 🟢 [Spec Kit](conventions/spec-kit/) - 🟢 [Kiro steering files](conventions/kiro-steering/) - [Skills & prompt assets](#skills--prompt-assets) · [category page](categories/skills-prompt-assets.md) - 🟢 [SKILL.md](conventions/skill-md/) - 🟢 [Prompt asset files](conventions/prompt-assets/) - 🟢 [Claude Code commands](conventions/claude-commands/) - 🟢 [Copilot prompt & instruction files](conventions/copilot-prompt-files/) - [Tooling & connections](#tooling--connections) · [category page](categories/tooling-connections.md) - 🟢 [MCP server config](conventions/mcp-config/) - [Rules & ignore files](#rules--ignore-files) · [category page](categories/rules-ignore-files.md) - 🟢 [Rules files](conventions/agent-rules/) - 🟢 [AI ignore files](conventions/ai-ignore-files/) - [Design](#design) · [category page](categories/design.md) - 🟢 [DESIGN.md](conventions/design-md/) - [Web & discoverability](#web--discoverability) · [category page](categories/web-discoverability.md) - 🟢 [llms.txt](conventions/llms-txt/) - 🟢 [pricing.md](conventions/pricing-md/) - [Agent-web trust](#agent-web-trust) · [category page](categories/agent-web-trust.md) - 🟠 [auth.md](conventions/auth-md/) - 🔵 [ai.txt](conventions/ai-txt/) - [Identity & protocols](#identity--protocols) · [category page](categories/identity-protocols.md) - 🟠 [Agent Cards (A2A)](conventions/agent-cards/) - [Proposed namespace](#proposed-namespace) · [category page](categories/proposed-namespace.md) - 🔵 [The protocols.md namespace](conventions/protocols-md/) ## What counts This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints. Any file type can qualify - `.md`, `.txt`, `.prompty`, `.json`, dotfiles, or a directory pattern. Human-first project docs such as `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `CHANGELOG.md` stay out unless the file has become an agent convention in its own right. ## Maturity tiers The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea. | Badge | Tier | Meaning | | --- | --- | --- | | 🟢 | **Adopted** | Used in production by multiple tools, projects, or teams. | | 🟠 | **Emerging** | Published by a real organization, but still early or limited in adoption. | | 🔵 | **Proposed** | Publicly described, but without clear adoption beyond the proposal. | ## Instruction & context Standalone page: [categories/instruction-context.md](categories/instruction-context.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [AGENTS.md](conventions/agents-md/) | `AGENTS.md` | Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others | [spec ↗](https://agents.md) | | 🟢 | [CLAUDE.md](conventions/claude-md/) | `CLAUDE.md` | Claude Code, and tools that read the Claude memory convention | [spec ↗](https://code.claude.com/docs/en/memory) | | 🟢 | [Tool-specific instruction files](conventions/tool-specific-instructions/) | `GEMINI.md` `AGENT.md` `QWEN.md` `WARP.md` `CONVENTIONS.md` `copilot-instructions.md` | Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md | [spec ↗](https://agents.md) | - **[AGENTS.md](conventions/agents-md/)** - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file. - **[CLAUDE.md](conventions/claude-md/)** - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns. - **[Tool-specific instruction files](conventions/tool-specific-instructions/)** - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories. ## Memory & state Standalone page: [categories/memory-state.md](categories/memory-state.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [MEMORY.md](conventions/memory-md/) | `MEMORY.md` | Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session | [spec ↗](https://code.claude.com/docs/en/memory) | | 🟢 | [Memory Bank](conventions/memory-bank/) | `projectbrief.md` `productContext.md` `activeContext.md` `systemPatterns.md` `techContext.md` `progress.md` | Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern) | [spec ↗](https://docs.cline.bot/best-practices/memory-bank) | - **[MEMORY.md](conventions/memory-md/)** - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time. - **[Memory Bank](conventions/memory-bank/)** - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant. ## Spec-driven development Standalone page: [categories/spec-driven-development.md](categories/spec-driven-development.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [Spec Kit](conventions/spec-kit/) | `constitution.md` `spec.md` `plan.md` `tasks.md` | GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more) | [spec ↗](https://github.com/github/spec-kit) | | 🟢 | [Kiro steering files](conventions/kiro-steering/) | `product.md` `structure.md` `tech.md` | AWS Kiro (steering files are largely Kiro-specific) | [spec ↗](https://kiro.dev/docs/steering) | - **[Spec Kit](conventions/spec-kit/)** - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation. - **[Kiro steering files](conventions/kiro-steering/)** - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec. ## Skills & prompt assets Standalone page: [categories/skills-prompt-assets.md](categories/skills-prompt-assets.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [SKILL.md](conventions/skill-md/) | `SKILL.md` | Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools | [spec ↗](https://agentskills.io/specification) | | 🟢 | [Prompt asset files](conventions/prompt-assets/) | `.prompty` `.prompt` `system_prompt.txt` | Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts | [spec ↗](https://prompty.ai) | | 🟢 | [Claude Code commands](conventions/claude-commands/) | `.md` | Claude Code - project .claude/commands/ and user ~/.claude/commands/ | [spec ↗](https://code.claude.com/docs/en/slash-commands) | | 🟢 | [Copilot prompt & instruction files](conventions/copilot-prompt-files/) | `.prompt.md` `.instructions.md` | GitHub Copilot in VS Code / Copilot CLI | [spec ↗](https://code.visualstudio.com/docs/agent-customization/prompt-files) | - **[SKILL.md](conventions/skill-md/)** - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it. - **[Prompt asset files](conventions/prompt-assets/)** - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames. - **[Claude Code commands](conventions/claude-commands/)** - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right. - **[Copilot prompt & instruction files](conventions/copilot-prompt-files/)** - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md. ## Tooling & connections Standalone page: [categories/tooling-connections.md](categories/tooling-connections.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [MCP server config](conventions/mcp-config/) | `.mcp.json` | Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool | [spec ↗](https://code.claude.com/docs/en/mcp) | - **[MCP server config](conventions/mcp-config/)** - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client. ## Rules & ignore files Standalone page: [categories/rules-ignore-files.md](categories/rules-ignore-files.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [Rules files](conventions/agent-rules/) | `.cursorrules` `.mdc` `.clinerules` `.clinerules/` _(pattern)_ `.windsurfrules` | Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules) | [spec ↗](https://docs.cline.bot/customization/cline-rules) | | 🟢 | [AI ignore files](conventions/ai-ignore-files/) | `.aiignore` `.cursorignore` `.codeiumignore` | JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore) | [spec ↗](https://cursor.com/docs/reference/ignore-file) | - **[Rules files](conventions/agent-rules/)** - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/*.mdc, .clinerules/, .windsurf/rules/*.md). - **[AI ignore files](conventions/ai-ignore-files/)** - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context. ## Design Standalone page: [categories/design.md](categories/design.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [DESIGN.md](conventions/design-md/) | `DESIGN.md` | Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context | [spec ↗](https://github.com/google-labs-code/design.md) | - **[DESIGN.md](conventions/design-md/)** - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec. ## Web & discoverability Standalone page: [categories/web-discoverability.md](categories/web-discoverability.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟢 | [llms.txt](conventions/llms-txt/) | `llms.txt` `llms-full.txt` _(pattern)_ | Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it | [spec ↗](https://llmstxt.org) | | 🟢 | [pricing.md](conventions/pricing-md/) | `pricing.md` | Agents and LLM browsers fetching a clean, parse-able pricing page | [spec ↗](https://resend.com/pricing.md) | - **[llms.txt](conventions/llms-txt/)** - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven. - **[pricing.md](conventions/pricing-md/)** - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern. ## Agent-web trust Standalone page: [categories/agent-web-trust.md](categories/agent-web-trust.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟠 | [auth.md](conventions/auth-md/) | `auth.md` | Agents discovering how to authenticate to a service (early adopters) | [spec ↗](https://workos.com/auth-md) | | 🔵 | [ai.txt](conventions/ai-txt/) | `ai.txt` | AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable | [spec ↗](https://datatracker.ietf.org/doc/draft-car-ai-txt-wellknown/) | - **[auth.md](conventions/auth-md/)** - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early. - **[ai.txt](conventions/ai-txt/)** - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵. ## Identity & protocols Standalone page: [categories/identity-protocols.md](categories/identity-protocols.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🟠 | [Agent Cards (A2A)](conventions/agent-cards/) | `agent-card.json` `agent.json` _(pattern)_ | A2A-compatible agents discovering another agent's capabilities | [spec ↗](https://a2a-protocol.org/latest/specification/) | - **[Agent Cards (A2A)](conventions/agent-cards/)** - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early. ## Proposed namespace Standalone page: [categories/proposed-namespace.md](categories/proposed-namespace.md) | | Convention | Files | Read by | Spec | | --- | --- | --- | --- | --- | | 🔵 | [The protocols.md namespace](conventions/protocols-md/) | `proof.md` | - (no demonstrated readers; aspirational) | [spec ↗](https://protocols.md) | - **[The protocols.md namespace](conventions/protocols-md/)** - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats. ## Maintaining examples Example files are fetched, not invented. The extractor pulls them from public sources, stores them under `conventions/<slug>/examples/<source>/<filename>`, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see [THIRD_PARTY_EXAMPLES.md](THIRD_PARTY_EXAMPLES.md) before reusing them. To refresh everything: ```bash pip install -r scripts/requirements.txt python scripts/extract.py # fetch real files + rebuild each convention's README python scripts/build_readme.py # rebuild this README from scripts/targets.json ``` Re-running is idempotent. A missing target prints a `miss` and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB `llms-full.txt`) is truncated with a marker pointing back to the full source. `scripts/targets.json` remains the source of truth for conventions that have not been migrated yet; the `skill-md` pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts. Shortcut targets are available in the [Makefile](Makefile): ```bash make verify # schema + generated files + example provenance + links make extract # refetch public examples and rebuild generated docs make license-report # summarize upstream licenses for vendored examples ``` CI keeps the generated files and links honest. The [verify workflow](.github/workflows/verify.yml) checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with `python scripts/check_links.py`. ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md). In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to `scripts/targets.json` for non-migrated conventions, run the scripts, and open a PR. The `skill-md` pilot uses local convention metadata instead. Do not hand-write example files. Before proposing adjacent standards, check [WATCHLIST.md](WATCHLIST.md). Project direction lives in [ROADMAP.md](ROADMAP.md). ## License The curation, scripts, and original prose in this repository are [MIT](LICENSE). Vendored example files remain under their upstream owners' licenses and terms; see [THIRD_PARTY_EXAMPLES.md](THIRD_PARTY_EXAMPLES.md).