Rust/codex-rs

In the codex-rs folder where the rust code lives:

• Crate names are prefixed with codex-. For example, the core folder's crate is named codex-core
• When using format! and you can inline variables into {}, always do that.
• Install any commands the repo relies on (for example just, rg, or cargo-insta) if they aren't already available before running instructions here.
• Never add or modify any code related to CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR or CODEX_SANDBOX_ENV_VAR.
  • You operate in a sandbox where CODEX_SANDBOX_NETWORK_DISABLED=1 will be set whenever you use the shell tool. Any existing code that uses CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR was authored with this fact in mind. It is often used to early exit out of tests that the author knew you would not be able to run given your sandbox limitations.
  • Similarly, when you spawn a process using Seatbelt (/usr/bin/sandbox-exec), CODEX_SANDBOX=seatbelt will be set on the child process. Integration tests that want to run Seatbelt themselves cannot be run under Seatbelt, so checks for CODEX_SANDBOX=seatbelt are also often used to early exit out of tests, as appropriate.
• Always collapse if statements per https://rust-lang.github.io/rust-clippy/master/index.html#collapsible_if
• Always inline format! args when possible per https://rust-lang.github.io/rust-clippy/master/index.html#uninlined_format_args
• Use method references over closures when possible per https://rust-lang.github.io/rust-clippy/master/index.html#redundant_closure_for_method_calls
• Avoid bool or ambiguous Option parameters that force callers to write hard-to-read code such as foo(false) or bar(None). Prefer enums, named methods, newtypes, or other idiomatic Rust API shapes when they keep the callsite self-documenting.
• When you cannot make that API change and still need a small positional-literal callsite in Rust, follow the argument_comment_lint convention:
  • Use an exact /*param_name*/ comment before opaque literal arguments such as None, booleans, and numeric literals when passing them by position.
  • A method's sole non-self argument is exempt when the method and parameter names match, such as .enabled(false) for fn enabled(&self, enabled: bool).
  • Do not add these comments for string or char literals unless the comment adds real clarity; those literals are intentionally exempt from the lint.
  • The parameter name in the comment must exactly match the callee signature.
  • You can run just argument-comment-lint to run the lint check locally. This is powered by Bazel, so running it the first time can be slow if Bazel is not warmed up, though incremental invocations should take <15s. Most of the time, it is best to update the PR and let CI take responsibility for checking this (or run it asynchronously in the background after submitting the PR). Note CI checks all three platforms, which the local run does not.
• When possible, make match statements exhaustive and avoid wildcard arms.
• Newly added traits should include doc comments that explain their role and how implementations are expected to use them.
• Discourage both #[async_trait] and #[allow(async_fn_in_trait)] in Rust traits.
  • Prefer native RPITIT trait methods with explicit Send bounds on the returned future, as in 3c7f013f9735 / #16630.
  • Preferred trait shape: fn foo(&self, ...) -> impl std::future::Future<Output = T> + Send;
  • Implementations may still use async fn foo(&self, ...) -> T when they satisfy that contract.
  • Do not use #[allow(async_fn_in_trait)] as a shortcut around spelling the future contract explicitly.
• When writing tests, prefer comparing the equality of entire objects over fields one by one.
• Do not add tests for values that are statically defined.
• Do not add negative tests for logic that was removed.
• Do not add general product or user-facing documentation to the docs/ folder. The official Codex documentation lives elsewhere. The exception is app-server API documentation, which is covered by the app-server guidance below.
• Prefer private modules and explicitly exported public crate API.
• If you change ConfigToml or nested config types, run just write-config-schema to update codex-rs/core/config.schema.json.
• When working with MCP tool calls, prefer using codex-rs/codex-mcp/src/mcp_connection_manager.rs to handle mutation of tools and tool calls. Aim to minimize the footprint of changes and leverage existing abstractions rather than plumbing code through multiple levels of function calls.
• Do not call reset_client_session unnecessarily; let the incremental check logic decide whether to reuse the previous request.
• If you change Rust dependencies (Cargo.toml or Cargo.lock), run just bazel-lock-update from the repo root to refresh MODULE.bazel.lock, and include that lockfile update in the same change. CI verifies lockfile drift.
• Bazel does not automatically make source-tree files available to compile-time Rust file access. If you add include_str!, include_bytes!, sqlx::migrate!, or similar build-time file or directory reads, update the crate's BUILD.bazel (compile_data, build_script_data, or test data) or Bazel may fail even when Cargo passes.
• Do not create small helper methods that are referenced only once.
• For tracing async work, instrument the function or method definition with #[tracing::instrument(...)] instead of attaching spans to futures with .instrument(...) at call sites. Before adding instrumentation, check whether the callee—or the implementation method it immediately delegates to—is already instrumented.
• Avoid large modules:
  • Prefer adding new modules instead of growing existing ones.
  • Target Rust modules under 500 LoC, excluding tests.
  • If a file exceeds roughly 800 LoC, add new functionality in a new module instead of extending the existing file unless there is a strong documented reason not to.
  • This rule applies especially to high-touch files that already attract unrelated changes, such as codex-rs/tui/src/app.rs, codex-rs/tui/src/bottom_pane/chat_composer.rs, codex-rs/tui/src/bottom_pane/footer.rs, codex-rs/tui/src/chatwidget.rs, codex-rs/tui/src/bottom_pane/mod.rs, and similarly central orchestration modules.
  • When extracting code from a large module, move the related tests and module/type docs toward the new implementation so the invariants stay close to the code that owns them.
  • Avoid adding new standalone methods to codex-rs/tui/src/chatwidget.rs unless the change is trivial; prefer new modules/files and keep chatwidget.rs focused on orchestration.
• When running Rust commands (e.g. just fix or just test) be patient with the command and never try to kill them using the PID. Rust lock can make the execution slow, this is expected.

Run just fmt (in the codex-rs directory) automatically after you have finished making code changes anywhere in this repository; do not ask for approval to run it. Additionally, run the tests:

1. Do not run cargo test directly. Use just test so test execution follows the repo defaults.
2. Run the test for the specific project that was changed. For example, if changes were made in codex-rs/tui, run just test -p codex-tui.
3. Once those pass, if any changes were made in common, core, or protocol, run the complete test suite with just test. Avoid --all-features for routine local runs because it expands the build matrix and can significantly increase target/ disk usage; use it only when you specifically need full feature coverage. project-specific or individual tests can be run without asking the user, but do ask the user before running the complete test suite.

Before finalizing a large change to codex-rs, run just fix -p <project> (in codex-rs directory) to fix any linter issues in the code. Prefer scoping with -p to avoid slow workspace‑wide Clippy builds; only run just fix without -p if you changed shared crates. Do not re-run tests after running fix or fmt.

The codex-core crate

Over time, the codex-core crate (defined in codex-rs/core/) has become bloated because it is the largest crate, so it is often easier to add something new to codex-core rather than refactor out the library code you need so your new code neither takes a dependency on, nor contributes to the size of, codex-core.

To that end: resist adding code to codex-core!

Particularly when introducing a new concept/feature/API, before adding to codex-core, consider whether:

• There is an existing crate other than codex-core that is an appropriate place for your new code to live.
• It is time to introduce a new crate to the Cargo workspace for your new functionality. Refactor existing code as necessary to make this happen.

Likewise, when reviewing code, do not hesitate to push back on PRs that would unnecessarily add code to codex-core.

Code Review Rules

Crate API surface

Keep crate API surfaces as small as possible. Avoid proliferating test-only helpers.

Model visible context

Codex maintains a context (history of messages) that is sent to the model in inference requests.

1. No history rewrite - the context must be built up incrementally.
2. Avoid frequent changes to context that cause cache misses.
3. No unbounded items - everything injected in the model context must have a bounded size and a hard cap.
4. No items larger than 10K tokens.
5. Highlight new individual items that can cross >1k tokens as P0. These need an additional manual review.
6. All injected fragments must be defined as structs in core/context and implement ContextualUserFragment trait

Breaking changes

Search for breaking changes in external integration surfaces:

• app-server APIs
• raw response item events (rawResponseItem/*), even while experimental
• CLI parameters
• configuration loading
• resuming sessions from existing rollouts

Test authoring guidance

For agent changes prefer integration tests over unit tests. Integration tests are under core/suite and use test_codex to set up a test instance of codex.

Features that change the agent logic MUST add an integration test:

• Provide a list of major logic changes and user-facing behaviors that need to be tested.

If unit tests are needed, put them in a dedicated test file (*_tests.rs). Avoid test-only functions in the main implementation.

Check whether there are existing helpers to make tests more streamlined and readable.

Change size guidance (800 lines)

Unless the change is mechanical the total number of changed lines should not exceed 800 lines. For complex logic changes the size should be under 500 lines.

If the change is larger, explore whether it can be split into reviewable stages and identify the smallest coherent stage to land first. Base the staging suggestion on the actual diff, dependencies, and affected call sites.

TUI style conventions

See codex-rs/tui/styles.md.

TUI code conventions

• Use concise styling helpers from ratatui’s Stylize trait.
  • Basic spans: use "text".into()
  • Styled spans: use "text".red(), "text".green(), "text".magenta(), "text".dim(), etc.
  • Prefer these over constructing styles with Span::styled and Style directly.
  • Example: patch summary file lines
    • Desired: vec![" └ ".into(), "M".red(), " ".dim(), "tui/src/app.rs".dim()]

TUI Styling (ratatui)

• Prefer Stylize helpers: use "text".dim(), .bold(), .cyan(), .italic(), .underlined() instead of manual Style where possible.
• Prefer simple conversions: use "text".into() for spans and vec![…].into() for lines; when inference is ambiguous (e.g., Paragraph::new/Cell::from), use Line::from(spans) or Span::from(text).
• Computed styles: if the Style is computed at runtime, using Span::styled is OK (Span::from(text).set_style(style) is also acceptable).
• Avoid hardcoded white: do not use .white(); prefer the default foreground (no color).
• Chaining: combine helpers by chaining for readability (e.g., url.cyan().underlined()).
• Single items: prefer "text".into(); use Line::from(text) or Span::from(text) only when the target type isn’t obvious from context, or when using .into() would require extra type annotations.
• Building lines: use vec![…].into() to construct a Line when the target type is obvious and no extra type annotations are needed; otherwise use Line::from(vec![…]).
• Avoid churn: don’t refactor between equivalent forms (Span::styled ↔ set_style, Line::from ↔ .into()) without a clear readability or functional gain; follow file‑local conventions and do not introduce type annotations solely to satisfy .into().
• Compactness: prefer the form that stays on one line after rustfmt; if only one of Line::from(vec![…]) or vec![…].into() avoids wrapping, choose that. If both wrap, pick the one with fewer wrapped lines.

Text wrapping

• Always use textwrap::wrap to wrap plain strings.
• If you have a ratatui Line and you want to wrap it, use the helpers in tui/src/wrapping.rs, e.g. word_wrap_lines / word_wrap_line.
• If you need to indent wrapped lines, use the initial_indent / subsequent_indent options from RtOptions if you can, rather than writing custom logic.
• If you have a list of lines and you need to prefix them all with some prefix (optionally different on the first vs subsequent lines), use the prefix_lines helper from line_utils.

Tests

Test module organization

• When adding a new test module, define its contents in a separate sibling file rather than inline in the implementation file.

• Use an explicit #[path = "..._tests.rs"] attribute so the test filename is descriptive and easy to locate:

  #[cfg(test)]
  #[path = "parser_tests.rs"]
  mod tests;
  

• This applies only when introducing a new test module. Do not move or rewrite existing inline #[cfg(test)] mod tests { ... } modules solely to follow this convention.

Snapshot tests

This repo uses snapshot tests (via insta), especially in codex-rs/tui, to validate rendered output.

Requirement: any change that affects user-visible UI (including adding new UI) must include corresponding insta snapshot coverage (add a new snapshot test if one doesn't exist yet, or update the existing snapshot). Review and accept snapshot updates as part of the PR so UI impact is easy to review and future diffs stay visual.

When UI or text output changes intentionally, update the snapshots as follows:

• Run tests to generate any updated snapshots:
  • just test -p codex-tui
• Check what’s pending:
  • cargo insta pending-snapshots -p codex-tui
• Review changes by reading the generated *.snap.new files directly in the repo, or preview a specific file:
  • cargo insta show -p codex-tui path/to/file.snap.new
• Only if you intend to accept all new snapshots in this crate, run:
  • cargo insta accept -p codex-tui

If you don’t have the tool:

• cargo install --locked cargo-insta

Benchmarks

cargo benchmarks can be run with just bench, use the divan crate to write new ones.

Use just bench-smoke to dry-run the benchmark for a single iteration to ensure it works.

Test assertions

• Tests should use pretty_assertions::assert_eq for clearer diffs. Import this at the top of the test module if it isn't already.
• Prefer deep equals comparisons whenever possible. Perform assert_eq!() on entire objects, rather than individual fields.
• Avoid mutating process environment in tests; prefer passing environment-derived flags or dependencies from above.

Spawning workspace binaries in tests (Cargo vs Bazel)

• Prefer codex_utils_cargo_bin::cargo_bin("...") over assert_cmd::Command::cargo_bin(...) or escargot when tests need to spawn first-party binaries.
  • Under Bazel, binaries and resources may live under runfiles; use codex_utils_cargo_bin::cargo_bin to resolve absolute paths that remain stable after chdir.
• When locating fixture files or test resources under Bazel, avoid env!("CARGO_MANIFEST_DIR"). Prefer codex_utils_cargo_bin::find_resource! so paths resolve correctly under both Cargo and Bazel runfiles.

Integration tests

codex_core integration testing

• Prefer the utilities in core_test_support::responses when writing end-to-end Codex tests.

• Use TestCodexBuilder::build_with_auto_env() by default to ensure that new tests work with foreign app/exec OSes. See $remote-tests for details.

• All mount_sse* helpers return a ResponseMock; hold onto it so you can assert against outbound /responses POST bodies.

• Use ResponseMock::single_request() when a test should only issue one POST, or ResponseMock::requests() to inspect every captured ResponsesRequest.

• ResponsesRequest exposes helpers (body_json, input, function_call_output, custom_tool_call_output, call_output, header, path, query_param) so assertions can target structured payloads instead of manual JSON digging.

• Build SSE payloads with the provided ev_* constructors and the sse(...).

• Prefer wait_for_event over wait_for_event_with_timeout.

• Prefer mount_sse_once over mount_sse_once_match or mount_sse_sequence

• Typical pattern:

  let mock = responses::mount_sse_once(&server, responses::sse(vec![
      responses::ev_response_created("resp-1"),
      responses::ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
      responses::ev_completed("resp-1"),
  ])).await;
  
  codex.submit(Op::UserTurn { ... }).await?;
  
  // Assert request body if needed.
  let request = mock.single_request();
  // assert using request.function_call_output(call_id) or request.json_body() or other helpers.
  

app-server integration testing

• Tests should exercise app-server's public JSON-RPC API.
• Use similar server mocking as for core integration tests.
• Use TestAppServer::new_with_auto_env() and TestAppServer::send_thread_start_request_with_auto_env() by default to ensure that new tests work with foreign app/exec OSes. See $remote-tests for details.

App-server API Development Best Practices

These guidelines apply to app-server protocol work in codex-rs, especially:

• app-server-protocol/src/protocol/common.rs
• app-server-protocol/src/protocol/v2.rs
• app-server/README.md

Core Rules

• All active API development should happen in app-server v2. Do not add new API surface area to v1.
• Follow payload naming consistently: *Params for request payloads, *Response for responses, and *Notification for notifications.
• Expose RPC methods as <resource>/<method> and keep <resource> singular (for example, thread/read, app/list).
• Always expose fields as camelCase on the wire with #[serde(rename_all = "camelCase")] unless a tagged union or explicit compatibility requirement needs a targeted rename.
• Always expose string enum values as camelCase on the wire with matching serde and TS rename_all = "camelCase" annotations unless an explicit compatibility requirement needs targeted renames.
• Exception: config RPC payloads are expected to use snake_case to mirror config.toml keys (see the config read/write/list APIs in app-server-protocol/src/protocol/v2.rs).
• Always set #[ts(export_to = "v2/")] on v2 request/response/notification types so generated TypeScript lands in the correct namespace.
• Never use #[serde(skip_serializing_if = "Option::is_none")] for v2 API payload fields. Exception: client->server requests that intentionally have no params may use: params: #[ts(type = "undefined")] #[serde(skip_serializing_if = "Option::is_none")] Option<()>.
• Keep Rust and TS wire renames aligned. If a field or variant uses #[serde(rename = "...")], add matching #[ts(rename = "...")].
• For discriminated unions, use explicit tagging in both serializers: #[serde(tag = "type", ...)] and #[ts(tag = "type", ...)].
• Prefer plain String IDs at the API boundary (do UUID parsing/conversion internally if needed).
• Timestamps should be integer Unix seconds (i64) and named *_at (for example, created_at, updated_at, resets_at).
• For experimental API surface area: use #[experimental("method/or/field")], derive ExperimentalApi when field-level gating is needed, and use inspect_params: true in common.rs when only some fields of a method are experimental.

Client->server request payloads (*Params)

• Every optional field must be annotated with #[ts(optional = nullable)]. Do not use #[ts(optional = nullable)] outside client->server request payloads (*Params).
• Optional collection fields (for example Vec, HashMap) must use Option<...> + #[ts(optional = nullable)]. Do not use #[serde(default)] to model optional collections, and do not use skip_serializing_if on v2 payload fields.
• When you want omission to mean false for boolean fields, use #[serde(default, skip_serializing_if = "std::ops::Not::not")] pub field: bool over Option<bool>.
• For new list methods, implement cursor pagination by default: request fields pub cursor: Option<String> and pub limit: Option<u32>, response fields pub data: Vec<...> and pub next_cursor: Option<String>.

Development Workflow

• Update app-server docs/examples when API behavior changes (at minimum app-server/README.md).
• Regenerate schema fixtures when API shapes change: just write-app-server-schema (and just write-app-server-schema --experimental when experimental API fixtures are affected).
• Validate with just test -p codex-app-server-protocol.
• Avoid boilerplate tests that only assert experimental field markers for individual request fields in common.rs; rely on schema generation/tests and behavioral coverage instead.

Python Development Best Practices

Ignore Python 2 compatibility

This project uses Python 3+. You should not use the __future__ module.

If you need to worry about feature compatibility between different 3.xx point releases, check the closest pyproject.toml's requires-python field to see what minimum runtime version is supported.

Platform Support

Tests and features must support Linux, macOS and Windows unless feature is explicitly OS-specific.

Codex supports running connected app-server and exec-server on different operating systems. See the $remote-tests skill for details about integration testing these configurations.

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 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 · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

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

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	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 ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• 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 - 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 - 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.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	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 ↗

• 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 - 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

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• 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 - 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

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• 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 - 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 - 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 - 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

	Convention	Files	Read by	Spec
🟢	MCP server 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 ↗

• MCP server 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

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - 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 - 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

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• 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

	Convention	Files	Read by	Spec
🟢	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 ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• 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 - 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

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• 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 - 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

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - 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

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - 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 before reusing them.

To refresh everything:

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:

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 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. 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. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.