Next.js Development Guide

Note: CLAUDE.md is a symlink to AGENTS.md. They are the same file.

Codebase structure

Monorepo Overview

This is a pnpm monorepo containing the Next.js framework and related packages.

next.js/
├── packages/           # Published npm packages
├── turbopack/          # Turbopack bundler (Rust) - git subtree
├── crates/             # Rust crates for Next.js SWC bindings
├── test/               # All test suites
├── examples/           # Example Next.js applications
├── docs/               # Documentation
└── scripts/            # Build and maintenance scripts

Core Package: packages/next

The main Next.js framework lives in packages/next/. This is what gets published as the next npm package.

Source code is in packages/next/src/.

Key entry points:

• Dev server: src/cli/next-dev.ts → src/server/dev/next-dev-server.ts
• Production server: src/cli/next-start.ts → src/server/next-server.ts
• Build: src/cli/next-build.ts → src/build/index.ts

Compiled output goes to packages/next/dist/ (mirrors src/ structure).

Other Important Packages

• packages/create-next-app/ - The create-next-app CLI tool
• packages/next-swc/ - Native Rust bindings (SWC transforms)
• packages/eslint-plugin-next/ - ESLint rules for Next.js
• packages/font/ - next/font implementation
• packages/third-parties/ - Third-party script integrations

README files

Before editing or creating files in any subdirectory (e.g., packages/*, crates/*), read all README.md files in the directory path from the repo root up to and including the target file's directory. This helps identify any local patterns, conventions, and documentation.

Example: Before editing turbopack/crates/turbopack-ecmascript-runtime/js/src/nodejs/runtime/runtime-base.ts, read:

• turbopack/README.md (if exists)
• turbopack/crates/README.md (if exists)
• turbopack/crates/turbopack-ecmascript-runtime/README.md (if exists)
• turbopack/crates/turbopack-ecmascript-runtime/js/README.md (if exists - closest to target file)

Build Commands

# Build the Next.js package
pnpm --filter=next build

# Build all JS code
pnpm build

# Build all JS and Rust code
pnpm build-all

# Run specific task
pnpm --filter=next exec taskr <task>

Fast Local Development

For iterative development, default to watch mode plus the explicit test script that matches the mode and bundler being verified.

Default agent rule: If you are changing Next.js source or integration tests, start pnpm --filter=next dev in a separate terminal session before making edits (unless it is already running). If you skip this, explicitly state why (for example: docs-only, read-only investigation, or CI-only analysis).

1. Start watch build in background:

# Auto-rebuilds on file changes (~1-2s per change vs ~60s full build)
# Keep this running while you iterate on code
pnpm --filter=next dev

2. Run focused tests with the matching mode script:

# Development mode with Turbopack
pnpm test-dev-turbo test/path/to/test.ts

# Development mode with Webpack
pnpm test-dev-webpack test/path/to/test.ts

# Production build+start with Turbopack
pnpm test-start-turbo test/path/to/test.ts

# Production build+start with Webpack
pnpm test-start-webpack test/path/to/test.ts

3. When done, kill the background watch process (if you started it).

For type errors only: Use pnpm --filter=next types (~10s) instead of pnpm --filter=next build (~60s).

After the workspace is bootstrapped, prefer pnpm --filter=next build when edits are limited to core Next.js files. Use full pnpm build-all for branch switches/bootstrap, before CI push, or when changes span multiple packages.

Always run a full bootstrap build after switching branches:

git checkout <branch>
pnpm build-all   # Sets up outputs for dependent packages (Turborepo dedupes if unchanged)

Bundler Selection

Turbopack is the default bundler for both next dev and next build. To force webpack:

next build --webpack        # Production build with webpack
next dev --webpack          # Dev server with webpack

There is no --no-turbopack flag.

Testing

# Run specific test file (development mode with Turbopack)
pnpm test-dev-turbo test/path/to/test.test.ts

# Run tests matching pattern
pnpm test-dev-turbo -t "pattern"

# Run development tests
pnpm test-dev-turbo test/development/

Test commands by mode:

• pnpm test-dev-turbo - Development mode with Turbopack (default)
• pnpm test-dev-webpack - Development mode with Webpack
• pnpm test-start-turbo - Production build+start with Turbopack
• pnpm test-start-webpack - Production build+start with Webpack

Other test commands:

• pnpm test-unit - Run unit tests only (fast, no browser)
• pnpm new-test - Generate a new test file from template (interactive)

Generate tests non-interactively (for AI agents):

Generating tests using pnpm new-test is mandatory.

# Use --args for non-interactive mode (forward args to the script using `--`)
# Format: pnpm new-test -- --args <appDir> <name> <type>
# appDir: true/false (is this for app directory?)
# name: test name (e.g. "my-feature")
# type: e2e | production | development | unit

pnpm new-test -- --args true my-feature e2e

Analyzing test output efficiently:

Never re-run the same test suite with different grep filters. Capture output once to a file, then read from it:

# Run once, save everything
HEADLESS=true pnpm test-dev-turbo test/path/to/test.ts > /tmp/test-output.log 2>&1

# Then analyze without re-running
grep "●" /tmp/test-output.log            # Failed test names
grep -A5 "Error:" /tmp/test-output.log   # Error details
tail -5 /tmp/test-output.log             # Summary

Writing Tests

Test writing expectations:

• Use pnpm new-test to generate new test suites - it creates proper structure with fixture files

• Use retry() from next-test-utils instead of setTimeout for waiting

  // Good - use retry() for polling/waiting
  import { retry } from 'next-test-utils'
  await retry(async () => {
    const text = await browser.elementByCss('p').text()
    expect(text).toBe('expected value')
  })
  
  // Bad - don't use setTimeout for waiting
  await new Promise((resolve) => setTimeout(resolve, 1000))
  

• Do NOT use check() - it is deprecated. Use retry() + expect() instead

  // Deprecated - don't use check()
  await check(() => browser.elementByCss('p').text(), /expected/)
  
  // Good - use retry() with expect()
  await retry(async () => {
    const text = await browser.elementByCss('p').text()
    expect(text).toMatch(/expected/)
  })
  

• Prefer real fixture directories over inline files objects

  // Good - use a real directory with fixture files
  const { next } = nextTestSetup({
    files: __dirname, // points to directory containing test fixtures
  })
  
  // Avoid - inline file definitions are harder to maintain
  const { next } = nextTestSetup({
    files: {
      'app/page.tsx': `export default function Page() { ... }`,
    },
  })
  

Linting and Types

pnpm lint              # Full lint (types, prettier, eslint, ast-grep)
pnpm lint-fix          # Auto-fix lint issues
pnpm prettier-fix      # Fix formatting only
pnpm types             # TypeScript type checking

PR Status (CI Failures and Reviews)

When the user asks about CI failures, PR reviews, or the status of a PR, run the pr-status script:

node scripts/pr-status.js           # Auto-detects PR from current branch
node scripts/pr-status.js <number>  # Analyze specific PR by number

This generates analysis files in scripts/pr-status/.

General triage rules (always apply; $pr-status-triage skill expands on these):

• Prioritize blocking failures first: build, lint, types, then tests.
• Assume failures are real until disproven; use "Known Flaky Tests" as context, not auto-dismissal.
• Reproduce with the same CI mode/env vars (especially IS_WEBPACK_TEST=1 when present).
• For module-resolution/build-graph fixes, use the normal mode-specific test command so package resolution is exercised.

For full triage workflow (failure prioritization, mode selection, CI env reproduction, and common failure patterns), use the $pr-status-triage skill:

• Skill file: .agents/skills/pr-status-triage/SKILL.md

Use $pr-status-triage for automated analysis - see .agents/skills/pr-status-triage/SKILL.md for the full step-by-step workflow.

CI Analysis Tips:

• Prioritize CI failures over review comments
• Prioritize blocking jobs first: build, lint, types, then test jobs
• Common fast checks:
  • rust check / build → Run cargo fmt -- --check, then cargo fmt
  • lint / build → Run pnpm prettier --write <file> for prettier errors
  • test failures → Run the specific failing test path locally

Run tests in the right mode:

# Dev mode (Turbopack)
pnpm test-dev-turbo test/path/to/test.ts

# Prod mode
pnpm test-start-turbo test/path/to/test.ts

PR Descriptions

When writing PR descriptions, you MUST include the following HTML comment at the bottom of the description:

<!-- NEXT_JS_LLM_PR -->

Key Directories (Quick Reference)

See Codebase structure above for detailed explanations.

• packages/next/src/ - Main Next.js source code
• packages/next/src/server/ - Server runtime (most changes happen here)
• packages/next/src/client/ - Client-side runtime
• packages/next/src/build/ - Build tooling
• test/e2e/ - End-to-end tests
• test/development/ - Dev server tests
• test/production/ - Production build tests
• test/unit/ - Unit tests (fast, no browser)

Development Tips

• The dev server entry point is packages/next/src/cli/next-dev.ts
• Router server: packages/next/src/server/lib/router-server.ts
• Use DEBUG=next:* for debug logging
• Use NEXT_TELEMETRY_DISABLED=1 when testing locally

NODE_ENV vs __NEXT_DEV_SERVER

Both next dev and next build --debug-prerender produce bundles with NODE_ENV=development. Use process.env.__NEXT_DEV_SERVER to distinguish between them:

• process.env.NODE_ENV !== 'production' — code that should exist in dev bundles but be eliminated from prod bundles. This is a build-time check.
• process.env.__NEXT_DEV_SERVER — code that should only run with the dev server (next dev), not during next build --debug-prerender or next start.

Secrets and Env Safety

Always treat environment variable values as sensitive unless they are known test-mode flags.

• Never print or paste secret values (tokens, API keys, cookies) in chat responses, commits, or shared logs.
• Mirror CI env names and modes exactly, but do not inline literal secret values in commands.
• If a required secret is missing locally, stop and ask the user rather than inventing placeholder credentials.
• Never commit local secret files; if documenting env setup, use placeholder-only examples.
• When sharing command output, summarize and redact sensitive-looking values.

GitHub SSH Authentication

GitHub SSH authentication may depend on a user-configured SSH agent or key provider, such as a password manager or hardware-backed key.

If a Git fetch, push, or partial-clone hydration fails or hangs with an SSH signing error such as:

• sign_and_send_pubkey: signing failed
• communication with agent failed
• Permission denied (publickey)

stop immediately and ask the user to ensure their SSH agent or key provider is available and unlocked. Do not switch remotes to HTTPS, mutate remote URLs, retry repeatedly, or attempt another authentication workaround unless the user explicitly requests it.

Before a force-push or stack rebase that may hydrate partial-clone objects, prefer a lightweight SSH preflight. If it fails due to the SSH agent or key provider, ask the user to make it available or unlock it before continuing.

Specialized Skills

Use skills for conditional, deep workflows. Keep baseline iteration/build/test policy in this file.

• $pr-status-triage - CI failure and PR review triage with scripts/pr-status.js
• $create-pr - branch, commit, push, and draft PR creation workflow
• $backport-pr - cherry-pick merged PRs from canary to release branches
• $flags - feature-flag wiring across config/schema/define-env/runtime env
• $dce-edge - DCE-safe require() patterns and edge/runtime constraints
• $react-vendoring - entry-base.ts boundaries and vendored React type/runtime rules
• $runtime-debug - runtime-bundle/module-resolution regression reproduction and verification
• $next-rspack - @next/rspack-core and @next/rspack-binding maintenance (rspack/ directory)
• $authoring-skills - how to create and maintain skills in .agents/skills/

Context-Efficient Workflows

Reading large files (>500 lines, e.g. app-render.tsx):

• Grep first to find relevant line numbers, then read targeted ranges with offset/limit
• Never re-read the same section of a file without code changes in between
• For generated files (dist/, node_modules/, .next/): search only, don't read

Build & test output:

• Capture to file once, then analyze: e.g. pnpm build 2>&1 | tee /tmp/build.log
• Don't re-run the same test command without code changes; re-analyze saved output instead

Batch edits before building:

• Group related edits across files, then run one build, not build-per-edit
• Use pnpm --filter=next types (~10s) to check type errors without full rebuild

External API calls (gh, curl):

• Save response to variable or file: JOBS=$(gh api ...) && echo "$JOBS" | jq '...'
• Don't re-fetch the same API data to analyze from different angles

Commit and PR Style

• Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs
• Keep commit messages concise and descriptive
• PR descriptions should focus on what changed and why
• Do NOT mark PRs as "ready for review" (gh pr ready) - leave PRs in draft mode and let the user decide when to mark them ready

Task Decomposition and Verification

• Split work into smaller, individually verifiable tasks. Before starting, break the overall goal into incremental steps where each step produces a result that can be checked independently.
• Verify each task before moving on to the next. After completing a step, confirm it works correctly (e.g., run relevant tests, check types, build, or manually inspect output). Do not proceed to the next task until the current one is verified.
• Choose the right verification method for each change. This may include running unit tests, integration tests, type checking, linting, building the project, or inspecting runtime behavior depending on what was changed.
• When unclear how to verify a change, ask the user. If there is no obvious test or verification method for a particular change, ask the user how they would like it verified before moving on.

Pre-validate before committing to avoid slow lint-staged failures (~2 min each):

# Run exactly what the pre-commit hook runs on your changed files:
pnpm prettier --with-node-modules --ignore-path .prettierignore --write <files>
npx eslint --config eslint.config.mjs --fix <files>

Rebuilding Before Running Tests

When running Next.js integration tests, you must rebuild if source files have changed:

• First run after branch switch/bootstrap (or if unsure)? → pnpm build-all
• Edited only core Next.js files (packages/next/**) after bootstrap? → pnpm --filter=next build
• Edited Next.js code or Turbopack (Rust)? → pnpm build-all

Development Anti-Patterns

For runtime internals, use focused skills:

• Feature-flag plumbing and runtime bundle wiring: $flags (.agents/skills/flags/SKILL.md)
• DCE and edge/runtime constraints: $dce-edge (.agents/skills/dce-edge/SKILL.md)
• React vendoring and entry-base.ts boundaries: $react-vendoring (.agents/skills/react-vendoring/SKILL.md)
• Debugging and verification workflow: $runtime-debug (.agents/skills/runtime-debug/SKILL.md)

Keep these high-frequency guardrails in mind:

• Reproduce module resolution and bundling issues with the normal mode-specific test command so package resolution is exercised.
• Validate edge bundling regressions with pnpm test-start-webpack test/e2e/app-dir/app/standalone.test.ts
• Use __NEXT_SHOW_IGNORE_LISTED=true when you need full internal stack traces

Core runtime/bundling rules (always apply; skills above expand on these with verification steps and examples):

• New flags: add type in config-shared.ts, schema in config-schema.ts, and define-env.ts when used in user-bundled code.
• If a flag is consumed in pre-compiled runtime internals, also wire runtime env values (next-server.ts/export/worker.ts as needed).
• define-env.ts affects user bundling; it does not control pre-compiled runtime bundle internals.
• Keep require() behind compile-time if/else branches for DCE (avoid early-return/throw patterns).
• In edge builds, force feature flags that gate Node-only imports to false in define-env.ts.
• react-server-dom-webpack/* imports must stay in entry-base.ts; consume via component module exports elsewhere.

Test Gotchas

• Cache components enables PPR by default: When __NEXT_CACHE_COMPONENTS=true, most app-dir pages use PPR implicitly. Dedicated ppr-full/ and ppr/ test suites are mostly describe.skip (migrating to cache components). To test PPR codepaths, run normal app-dir e2e tests with __NEXT_CACHE_COMPONENTS=true rather than looking for explicit PPR test suites. -- Quick smoke testing with toy apps: For fast feedback, generate a minimal test fixture with pnpm new-test -- --args true <name> e2e, then run the dev server directly with node packages/next/dist/bin/next dev --port <port> and curl --max-time 10. This avoids the overhead of the full test harness and gives immediate feedback on hangs/crashes.
• Mode-specific tests need skipStart: true + manual next.start() in beforeAll after mode check
• Don't rely on exact log messages - filter by content patterns, find sequences not positions
• Snapshot tests vary by env flags: Tests with inline snapshots can produce different output depending on env flags. When updating snapshots, always run the test with the exact env flags the CI job uses (check .github/workflows/build_and_test.yml afterBuild: sections). Turbopack resolves react-dom/server.edge (no Node APIs like renderToPipeableStream), while webpack resolves the .node build (has them).
• app-page.ts is a build template compiled by the user's bundler: Any require() in this file is traced by webpack/turbopack at next build time. You cannot require internal modules with relative paths because they won't be resolvable from the user's project. Instead, export new helpers from entry-base.ts and access them via entryBase.* in the template.
• Reproducing CI failures locally: Always match the exact CI env vars (check pr-status output for "Job Environment Variables"). Key differences such as IS_WEBPACK_TEST=1 can change bundler selection and snapshot output, so use the CI command and mode when verifying module resolution fixes.
• Showing full stack traces: Set __NEXT_SHOW_IGNORE_LISTED=true to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to at ignore-listed frames, which hides useful context when debugging framework internals. Defined in packages/next/src/server/patch-error-inspect.ts.
• Router act tests must use LinkAccordion to control prefetches: Always use LinkAccordion to control when prefetches happen inside act scopes. Never use browser.back() to return to a page where accordion links are already visible — BFCache restores state and triggers uncontrolled re-prefetches. See $router-act for full patterns.

Rust/Cargo

• cargo fmt uses ASCII order (uppercase before lowercase) - just run cargo fmt
• Internal compiler error (ICE)? Delete incremental compilation artifacts and retry. Remove */incremental directories from your cargo target directory (default target/, or check CARGO_TARGET_DIR env var)
• Avoid adding new super:: imports except in inline mod blocks (e.g. mod tests { ... }) — prefer crate::-rooted paths. This makes imports consistent and easier to grep for.

Node.js Source Maps

• findSourceMap() needs --enable-source-maps flag or returns undefined
• Source map paths vary (webpack: ./src/, tsc: src/) - try multiple formats
• process.cwd() in stack trace formatting produces different paths in tests vs production

Stale Native Binary

If Turbopack produces unexpected errors after switching branches or pulling, check if packages/next-swc/native/*.node is stale. Delete it and run pnpm install to get the npm-published binary instead of a locally-built one.

Documentation Code Blocks

• When adding highlight={...} attributes to code blocks, carefully count the actual line numbers within the code block
• Account for empty lines, import statements, and type imports that shift line numbers
• Highlights should point to the actual relevant code, not unrelated lines like return ( or framework boilerplate
• Double-check highlights by counting lines from 1 within each code block

Server Security: Internal Header Filtering

Next.js strips internal headers from incoming requests via filterInternalHeaders() in packages/next/src/server/lib/server-ipc/utils.ts. This runs at the entry point in packages/next/src/server/lib/router-server.ts before any server code executes. Only headers listed in the INTERNAL_HEADERS array are stripped.

When reviewing PRs: if new code reads a request header that is not a standard HTTP header (like content-type, accept, user-agent, host, authorization, cookie, etc.), flag it for security review. The header may be forgeable by an external attacker if it is not in the INTERNAL_HEADERS filter list in packages/next/src/server/lib/server-ipc/utils.ts.

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.