[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C43G53G5769SCHR6TME7E0":3,"skill-same:01M6C43G53G5769SCHR6TME7E0":85},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":50,"install":51,"resources":64},"01M6C43G53G5769SCHR6TME7E0","ai-first-documentation",null,"Research-backed standards for documentation in AI-first codebases: context-file architecture (CLAUDE.md, skills, subagents, rules), multi-agent interop, and project-doc organization, with a tiered audit rubric. Use when authoring or auditing CLAUDE.md\u002FAGENTS.md, deciding where guidance belongs, or running a documentation gap analysis. DO NOT USE FOR: post-implementation doc updates (use documentation-finalization) or reference sidecar setup (use project-references).","Grimblaz\u002Fagent-orchestra","Grimblaz","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F74755849?v=4","01M6C430M9XZDHGHPWQVTQ3KMA","01M6C430RJY3MMX0QAZ3X8DR3Y",3,"MIT","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"documentation","first","ai first documentation","research","architecture","setup","file","audit","doc","analysis","multi-agent","Rules","context","rubric","subagents","use","2026-11-10 10:12:30",false,"---\nname: ai-first-documentation\ndescription: \"Research-backed standards for documentation in AI-first codebases: context-file architecture (CLAUDE.md, skills, subagents, rules), multi-agent interop, and project-doc organization, with a tiered audit rubric. Use when authoring or auditing CLAUDE.md\u002FAGENTS.md, deciding where guidance belongs, or running a documentation gap analysis. DO NOT USE FOR: post-implementation doc updates (use documentation-finalization) or reference sidecar setup (use project-references).\"\n---\n\n\u003C!-- platform-assumptions: markdown skill guidance for Claude Code and compatible agents; rubric evidence verified against live vendor docs on 2026-06-10\u002F11 — re-verify concrete numbers before hard enforcement. -->\n\u003C!-- markdownlint-disable-file MD041 MD003 -->\n\n# AI-First Documentation Standards\n\nStandards for structuring a repository's documentation when coding agents are primary readers and operators. Every practice here is backed by two adversarially-verified research passes (June 2026) across Anthropic official guidance (Tier 1), major vendor guidance (Tier 2), and evidenced practitioner sources (Tier 3). The testable rubric lives in [rubric.md](.\u002Frubric.md); citations, verification dates, refuted claims, and open gaps live in [sources.md](.\u002Fsources.md).\n\n- [When to Use](#when-to-use)\n- [Core Principle](#core-principle)\n- [The Placement Model](#the-placement-model)\n- [Audit Workflow](#audit-workflow)\n- [Consumer-Mode Audits](#consumer-mode-audits)\n- [Recording Documentation Decisions](#recording-documentation-decisions)\n- [Multi-Agent Repositories](#multi-agent-repositories)\n- [Known Industry Open Gaps](#known-industry-open-gaps)\n- [Quick Reference — Verified Numbers](#quick-reference--verified-numbers)\n- [See Also](#see-also)\n- [Gotchas](#gotchas)\n\n## When to Use\n\n- Authoring or auditing a CLAUDE.md, AGENTS.md, or other always-loaded context file\n- Deciding where a piece of guidance belongs (always-loaded vs. path-scoped vs. skill vs. plain doc)\n- Designing or reviewing skills, subagent definitions, or rules files\n- Running a documentation gap analysis of a repository against industry best practice\n- Configuring a repo that must serve multiple agent toolchains (Claude Code, Copilot, Cursor, Codex)\n\n## Core Principle\n\nThe context window is the scarce resource. Performance degrades as it fills, so always-loaded files must be ruthlessly minimal — every line survives the deletion test (\"Would removing this cause the agent to make mistakes?\") — while everything else moves to on-demand mechanisms: skills with progressive disclosure, path-scoped rules, child-directory context files, and just-in-time retrieval via glob\u002Fgrep rather than pre-built indexes. (Tier 1; corroborated by all surveyed vendors and an academic taxonomy of 13 open-source agents.)\n\nMinimal does not mean short for its own sake: the criterion is signal density plus behavioral sufficiency, not raw line count.\n\nFor the model-generation dimension of this principle — separating load-bearing contracts from Claude-4-era behavioral coaching when auditing imperative-guardrail density — see `Documents\u002FDesign\u002Fcontext-engineering-claude-5.md`.\n\n## The Placement Model\n\nRoute each piece of guidance to its cheapest sufficient home:\n\n| Content kind | Home | Loading cost |\n| --- | --- | --- |\n| Broadly-applicable facts: non-guessable commands, non-default conventions, testing instructions, repo etiquette, gotchas, \"always do X\" rules | Root CLAUDE.md \u002F AGENTS.md | Every session |\n| Area-specific instructions tied to file paths | Path-scoped rules (`paths:`\u002Fglob frontmatter) or child-directory CLAUDE.md | Only when matching files are touched |\n| Multi-step procedures, domain workflows, methodology | Skill (SKILL.md) | Metadata always (~100 tokens); body on demand |\n| Deep reference material, schemas, long examples | Skill reference files or plain docs, pointed to one level deep | Zero until accessed |\n| Side-effectful workflows that must not auto-trigger | Skill with `disable-model-invocation: true` | Manual invocation only |\n| High-volume exploration or review output | Subagent with isolated context | Never enters main context |\n| Anything derivable by reading the code, standard language conventions, frequently-changing facts, file-by-file codebase tours | Nowhere — delete it | — |\n\nTwo traps in this model: `@import`s in CLAUDE.md load at launch and save **no** context (only child-directory files and skills defer cost), and rules files **without** a path scope load unconditionally every session.\n\n## Audit Workflow\n\nTo run a gap analysis of a repository:\n\n1. **Inventory** the documentation surface: root and nested context files (`CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`), `.claude\u002Frules\u002F`, `skills\u002F*\u002FSKILL.md`, agent definitions, and the plain-doc tree (design docs, ADRs, runbooks, plans).\n2. **Classify** each artifact against the Placement Model: is anything always-loaded that could be on-demand? Is anything on-demand that the agent needs every session?\n3. **Test** each applicable practice in [rubric.md](.\u002Frubric.md), section by section (A: always-loaded context, B: skills, C: subagents, D: writing style, E: multi-agent interop, F: project docs).\n4. **Weight findings by tier and confidence** from the rubric: a Tier 1 high-confidence violation is a defect; a Tier 2 conflict is a trade-off to decide consciously; a Tier 3 divergence is informational.\n5. **Label house conventions in open-gap areas.** Where the rubric marks a topic as a confirmed industry open gap (Section F), a repo's own conventions are not violations — record them as house practice filling a documented gap, and consider them candidates for promotion if external standards later emerge.\n\nThe mechanical checks (A2, B2, B3, B5, A9) are deterministic and can be run headlessly via [scripts\u002Faudit-docs-mechanical.ps1](.\u002Fscripts\u002Faudit-docs-mechanical.ps1) with an explicit `-Root` parameter. For the interactive audit experience (applying judgment, browsing findings, running init), use `\u002Faudit-docs` — it runs the script and applies rubric judgment passes on top.\n\n## Consumer-Mode Audits\n\nThe mechanical-check script (`scripts\u002Faudit-docs-mechanical.ps1`) is designed to run against any consumer repository root, not just the hub. When run from a consumer's CI or shell:\n\n- **Own-surface scoping rule (D3)**: the script inventories only files in the consumer tree — root `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `.claude\u002Frules\u002F`, local `skills\u002F`, `.claude\u002Fagents\u002F`, and the project doc tree. Plugin-cache paths (`.claude\u002Fplugins\u002F`) are never inventoried.\n- **Entry-point precedence (D7)**: for interactive audits, `\u002Faudit-docs` is the deterministic entry point — it runs the script and applies rubric judgment. For headless\u002FCI use, invoke the script directly:\n  ```powershell\n  pwsh skills\u002Fai-first-documentation\u002Fscripts\u002Faudit-docs-mechanical.ps1 -Root . -FailOn fail\n  ```\n  Acquire the script via vendor-copy or pinned raw fetch; do not depend on a git submodule or npm package.\n- **CI snippet** (acquire + run):\n  ```powershell\n  # After vendoring the script to your repo (e.g., scripts\u002Faudit-docs-mechanical.ps1):\n  pwsh scripts\u002Faudit-docs-mechanical.ps1 -Root $env:GITHUB_WORKSPACE -FailOn fail\n  ```\n  Always pass a non-empty `-Root` — an empty string produces a PowerShell parameter-binding error rather than JSON output, since the binding check runs before the script body. The command layer's root-resolution step (CWD fallback) prevents this in interactive use.\n\n## Recording Documentation Decisions\n\nWhen a check fires and the deviation is intentional (e.g., CLAUDE.md is temporarily over 200 lines during a migration), record the decision in `.claude\u002Fdocumentation-decisions.md` at the consumer's root. The script reads this file and emits `status: waived` instead of `fail` for matched entries, so the decision is not re-litigated on re-runs or in CI.\n\n**Format (named decision `d-decision-record-format`)** — H3-per-record markdown:\n\n```markdown\n### {check-id}: {relative-path}\n- rationale: [CUSTOMIZE: why this deviation is intentional and temporary]\n- date: YYYY-MM-DD\n```\n\n**Example**:\n\n```markdown\n### A2: CLAUDE.md\n- rationale: CLAUDE.md is intentionally long during the Q3 migration; pruning tracked in issue #42.\n- date: 2026-06-12\n```\n\nThe match key is (check_id, normalized relative path from root). The `waiver_ref` in the JSON output is the raw heading text (`A2: CLAUDE.md`). Keep the H3 heading to the two-token `{check-id}: {relative-path}` form — any trailing annotation (e.g., `### A2: CLAUDE.md — migration note`) will appear verbatim in `waiver_ref`. Matching is case-insensitive: `### a2: claude.md` matches the same entry as `### A2: CLAUDE.md`.\n\n**Relocation**: the default location is `.claude\u002Fdocumentation-decisions.md`. Override with `-DecisionRecordPath \u003Cabsolute-or-repo-relative-path>` when your repo layout differs.\n\n## Multi-Agent Repositories\n\nWhen one repo serves several agent toolchains, consult rubric Section E before restructuring. Key verified facts: AGENTS.md is the cross-vendor de facto standard, but Claude Code does not read it natively (use a CLAUDE.md containing `@AGENTS.md`); Copilot's cloud agent reads CLAUDE.md natively but only as a single flat root file; Copilot code review reads only the first 4,000 characters of any instruction file; Cursor silently ignores plain `.md` files in `.cursor\u002Frules` (frontmatter `.mdc` or AGENTS.md only); Codex concatenates AGENTS.md files root-down with the closest file winning positionally.\n\nOne genuine unresolved conflict exists: GitHub recommends embedding repo structure and dependency versions and warns that pointer references to other docs may be ineffective in large repos — the opposite of Anthropic's deletion-test minimalism and progressive disclosure. Neither side has measured evidence. Default to the Anthropic model for Claude-primary repos; consciously revisit if Copilot adherence problems appear.\n\n## Known Industry Open Gaps\n\nNo credible verified guidance exists (as of June 2026) for: authoring ADRs\u002Fdesign docs differently for AI readers; whether llms.txt-style index files help or hurt vs. pure just-in-time search; wrapping general project docs as skills; doc-to-code linking that breaks loudly on drift; or doc-tree naming conventions optimized for agent navigation. The only verified adjacent practices are staleness automation (review-time flagging of doc drift — \"a stale context file can be worse than no file at all\") and the split-and-reference pattern (concise root file pointing to task-specific docs). Treat conventions in these areas as labeled house judgment, not settled standards. Details in [sources.md](.\u002Fsources.md).\n\n## Quick Reference — Verified Numbers\n\n| Number | What it bounds | Tier |\n| --- | --- | --- |\n| \u003C 200 lines | CLAUDE.md adherence target (not a truncation limit) | 1 |\n| \u003C 500 lines | SKILL.md body; also Cursor's per-rule-file ceiling | 1 \u002F 2 |\n| 64 \u002F 1024 chars | Skill frontmatter `name` \u002F `description` hard limits | 1 |\n| 1 level | Skill reference-file depth from SKILL.md (never nested chains) | 1 |\n| > 100 lines | Reference file size that requires a leading table of contents | 1 |\n| Depth 4 | Maximum recursive `@import` depth in CLAUDE.md | 1 |\n| 4,000 chars | Copilot code review reads only this much of any instruction file | 2 |\n| 32 KiB | Codex default combined instruction-file budget (`project_doc_max_bytes`) | 2 |\n\nAll numbers live-verified 2026-06-10\u002F11; vendor docs churn, so re-verify before hard enforcement (see [sources.md](.\u002Fsources.md)).\n\n## See Also\n\n- [rubric.md](.\u002Frubric.md) — the practice-by-practice testable audit rubric\n- [sources.md](.\u002Fsources.md) — citations, verification dates, refuted claims, open questions\n- [scripts\u002Faudit-docs-mechanical.ps1](.\u002Fscripts\u002Faudit-docs-mechanical.ps1) — mechanical-check script for A2, B2, B3, B5, A9; headless\u002FCI mode\n- [templates\u002FCLAUDE.md-starter.md](.\u002Ftemplates\u002FCLAUDE.md-starter.md) — minimal CLAUDE.md seed template\n- `documentation-finalization` — updating implementation-facing docs after code changes\n- `project-references` — Agent Orchestra reference sidecars and index conventions (a house convention in open-gap territory)\n- `skill-creator` — repo-specific skill frontmatter and structure conventions\n\n## Gotchas\n\n| Trigger | Gotcha | Fix |\n| --- | --- | --- |\n| Moving CLAUDE.md overflow into `@import` files \"to save context\" | Imports load in full at launch — zero context savings, same adherence cost | Move content to a skill or child-directory CLAUDE.md, which load on demand |\n| Adding a rules file without a path scope | It loads every session, silently becoming always-loaded context | Add a `paths:`\u002Fglob scope, or move the content to a skill |\n| Writing a skill description in first person or omitting \"when to use\" | Description is the sole selection signal injected into the system prompt; the skill is never picked | Third person, state what it does AND when to use it, within 1024 chars |\n| Chaining reference files (SKILL.md → ref-a.md → ref-b.md) | Agents may partially read nested references (e.g., head-100 previews) and miss content | Link every reference file directly from SKILL.md, one level deep |\n| Assuming Copilot honors nested CLAUDE.md or `@`-imports | Copilot's cloud agent reads only a single flat root CLAUDE.md | Keep the root file self-sufficient for Copilot, or maintain AGENTS.md |\n| Padding CLAUDE.md with folder structure and dependency versions | JIT-discoverable, staleness-prone content that fails the deletion test (GitHub recommends it; Anthropic canon excludes it — known conflict) | Default to omitting; the agent can glob\u002Fgrep it fresh |\n","\u003C!-- platform-assumptions: markdown skill guidance for Claude Code and compatible agents; rubric evidence verified against live vendor docs on 2026-06-10\u002F11 — re-verify concrete numbers before hard enforcement. -->\n\u003C!-- markdownlint-disable-file MD041 MD003 -->\n\n# AI-First Documentation Standards\n\nStandards for structuring a repository's documentation when coding agents are primary readers and operators. Every practice here is backed by two adversarially-verified research passes (June 2026) across Anthropic official guidance (Tier 1), major vendor guidance (Tier 2), and evidenced practitioner sources (Tier 3). The testable rubric lives in [rubric.md](.\u002Frubric.md); citations, verification dates, refuted claims, and open gaps live in [sources.md](.\u002Fsources.md).\n\n- [When to Use](#when-to-use)\n- [Core Principle](#core-principle)\n- [The Placement Model](#the-placement-model)\n- [Audit Workflow](#audit-workflow)\n- [Consumer-Mode Audits](#consumer-mode-audits)\n- [Recording Documentation Decisions](#recording-documentation-decisions)\n- [Multi-Agent Repositories](#multi-agent-repositories)\n- [Known Industry Open Gaps](#known-industry-open-gaps)\n- [Quick Reference — Verified Numbers](#quick-reference--verified-numbers)\n- [See Also](#see-also)\n- [Gotchas](#gotchas)\n\n## When to Use\n\n- Authoring or auditing a CLAUDE.md, AGENTS.md, or other always-loaded context file\n- Deciding where a piece of guidance belongs (always-loaded vs. path-scoped vs. skill vs. plain doc)\n- Designing or reviewing skills, subagent definitions, or rules files\n- Running a documentation gap analysis of a repository against industry best practice\n- Configuring a repo that must serve multiple agent toolchains (Claude Code, Copilot, Cursor, Codex)\n\n## Core Principle\n\nThe context window is the scarce resource. Performance degrades as it fills, so always-loaded files must be ruthlessly minimal — every line survives the deletion test (\"Would removing this cause the agent to make mistakes?\") — while everything else moves to on-demand mechanisms: skills with progressive disclosure, path-scoped rules, child-directory context files, and just-in-time retrieval via glob\u002Fgrep rather than pre-built indexes. (Tier 1; corroborated by all surveyed vendors and an academic taxonomy of 13 open-source agents.)\n\nMinimal does not mean short for its own sake: the criterion is signal density plus behavioral sufficiency, not raw line count.\n\nFor the model-generation dimension of this principle — separating load-bearing contracts from Claude-4-era behavioral coaching when auditing imperative-guardrail density — see `Documents\u002FDesign\u002Fcontext-engineering-claude-5.md`.\n\n## The Placement Model\n\nRoute each piece of guidance to its cheapest sufficient home:\n\n| Content kind | Home | Loading cost |\n| --- | --- | --- |\n| Broadly-applicable facts: non-guessable commands, non-default conventions, testing instructions, repo etiquette, gotchas, \"always do X\" rules | Root CLAUDE.md \u002F AGENTS.md | Every session |\n| Area-specific instructions tied to file paths | Path-scoped rules (`paths:`\u002Fglob frontmatter) or child-directory CLAUDE.md | Only when matching files are touched |\n| Multi-step procedures, domain workflows, methodology | Skill (SKILL.md) | Metadata always (~100 tokens); body on demand |\n| Deep reference material, schemas, long examples | Skill reference files or plain docs, pointed to one level deep | Zero until accessed |\n| Side-effectful workflows that must not auto-trigger | Skill with `disable-model-invocation: true` | Manual invocation only |\n| High-volume exploration or review output | Subagent with isolated context | Never enters main context |\n| Anything derivable by reading the code, standard language conventions, frequently-changing facts, file-by-file codebase tours | Nowhere — delete it | — |\n\nTwo traps in this model: `@import`s in CLAUDE.md load at launch and save **no** context (only child-directory files and skills defer cost), and rules files **without** a path scope load unconditionally every session.\n\n## Audit Workflow\n\nTo run a gap analysis of a repository:\n\n1. **Inventory** the documentation surface: root and nested context files (`CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`), `.claude\u002Frules\u002F`, `skills\u002F*\u002FSKILL.md`, agent definitions, and the plain-doc tree (design docs, ADRs, runbooks, plans).\n2. **Classify** each artifact against the Placement Model: is anything always-loaded that could be on-demand? Is anything on-demand that the agent needs every session?\n3. **Test** each applicable practice in [rubric.md](.\u002Frubric.md), section by section (A: always-loaded context, B: skills, C: subagents, D: writing style, E: multi-agent interop, F: project docs).\n4. **Weight findings by tier and confidence** from the rubric: a Tier 1 high-confidence violation is a defect; a Tier 2 conflict is a trade-off to decide consciously; a Tier 3 divergence is informational.\n5. **Label house conventions in open-gap areas.** Where the rubric marks a topic as a confirmed industry open gap (Section F), a repo's own conventions are not violations — record them as house practice filling a documented gap, and consider them candidates for promotion if external standards later emerge.\n\nThe mechanical checks (A2, B2, B3, B5, A9) are deterministic and can be run headlessly via [scripts\u002Faudit-docs-mechanical.ps1](.\u002Fscripts\u002Faudit-docs-mechanical.ps1) with an explicit `-Root` parameter. For the interactive audit experience (applying judgment, browsing findings, running init), use `\u002Faudit-docs` — it runs the script and applies rubric judgment passes on top.\n\n## Consumer-Mode Audits\n\nThe mechanical-check script (`scripts\u002Faudit-docs-mechanical.ps1`) is designed to run against any consumer repository root, not just the hub. When run from a consumer's CI or shell:\n\n- **Own-surface scoping rule (D3)**: the script inventories only files in the consumer tree — root `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `.claude\u002Frules\u002F`, local `skills\u002F`, `.claude\u002Fagents\u002F`, and the project doc tree. Plugin-cache paths (`.claude\u002Fplugins\u002F`) are never inventoried.\n- **Entry-point precedence (D7)**: for interactive audits, `\u002Faudit-docs` is the deterministic entry point — it runs the script and applies rubric judgment. For headless\u002FCI use, invoke the script directly:\n  ```powershell\n  pwsh skills\u002Fai-first-documentation\u002Fscripts\u002Faudit-docs-mechanical.ps1 -Root . -FailOn fail\n  ```\n  Acquire the script via vendor-copy or pinned raw fetch; do not depend on a git submodule or npm package.\n- **CI snippet** (acquire + run):\n  ```powershell\n  # After vendoring the script to your repo (e.g., scripts\u002Faudit-docs-mechanical.ps1):\n  pwsh scripts\u002Faudit-docs-mechanical.ps1 -Root $env:GITHUB_WORKSPACE -FailOn fail\n  ```\n  Always pass a non-empty `-Root` — an empty string produces a PowerShell parameter-binding error rather than JSON output, since the binding check runs before the script body. The command layer's root-resolution step (CWD fallback) prevents this in interactive use.\n\n## Recording Documentation Decisions\n\nWhen a check fires and the deviation is intentional (e.g., CLAUDE.md is temporarily over 200 lines during a migration), record the decision in `.claude\u002Fdocumentation-decisions.md` at the consumer's root. The script reads this file and emits `status: waived` instead of `fail` for matched entries, so the decision is not re-litigated on re-runs or in CI.\n\n**Format (named decision `d-decision-record-format`)** — H3-per-record markdown:\n\n```markdown\n### {check-id}: {relative-path}\n- rationale: [CUSTOMIZE: why this deviation is intentional and temporary]\n- date: YYYY-MM-DD\n```\n\n**Example**:\n\n```markdown\n### A2: CLAUDE.md\n- rationale: CLAUDE.md is intentionally long during the Q3 migration; pruning tracked in issue #42.\n- date: 2026-06-12\n```\n\nThe match key is (check_id, normalized relative path from root). The `waiver_ref` in the JSON output is the raw heading text (`A2: CLAUDE.md`). Keep the H3 heading to the two-token `{check-id}: {relative-path}` form — any trailing annotation (e.g., `### A2: CLAUDE.md — migration note`) will appear verbatim in `waiver_ref`. Matching is case-insensitive: `### a2: claude.md` matches the same entry as `### A2: CLAUDE.md`.\n\n**Relocation**: the default location is `.claude\u002Fdocumentation-decisions.md`. Override with `-DecisionRecordPath \u003Cabsolute-or-repo-relative-path>` when your repo layout differs.\n\n## Multi-Agent Repositories\n\nWhen one repo serves several agent toolchains, consult rubric Section E before restructuring. Key verified facts: AGENTS.md is the cross-vendor de facto standard, but Claude Code does not read it natively (use a CLAUDE.md containing `@AGENTS.md`); Copilot's cloud agent reads CLAUDE.md natively but only as a single flat root file; Copilot code review reads only the first 4,000 characters of any instruction file; Cursor silently ignores plain `.md` files in `.cursor\u002Frules` (frontmatter `.mdc` or AGENTS.md only); Codex concatenates AGENTS.md files root-down with the closest file winning positionally.\n\nOne genuine unresolved conflict exists: GitHub recommends embedding repo structure and dependency versions and warns that pointer references to other docs may be ineffective in large repos — the opposite of Anthropic's deletion-test minimalism and progressive disclosure. Neither side has measured evidence. Default to the Anthropic model for Claude-primary repos; consciously revisit if Copilot adherence problems appear.\n\n## Known Industry Open Gaps\n\nNo credible verified guidance exists (as of June 2026) for: authoring ADRs\u002Fdesign docs differently for AI readers; whether llms.txt-style index files help or hurt vs. pure just-in-time search; wrapping general project docs as skills; doc-to-code linking that breaks loudly on drift; or doc-tree naming conventions optimized for agent navigation. The only verified adjacent practices are staleness automation (review-time flagging of doc drift — \"a stale context file can be worse than no file at all\") and the split-and-reference pattern (concise root file pointing to task-specific docs). Treat conventions in these areas as labeled house judgment, not settled standards. Details in [sources.md](.\u002Fsources.md).\n\n## Quick Reference — Verified Numbers\n\n| Number | What it bounds | Tier |\n| --- | --- | --- |\n| \u003C 200 lines | CLAUDE.md adherence target (not a truncation limit) | 1 |\n| \u003C 500 lines | SKILL.md body; also Cursor's per-rule-file ceiling | 1 \u002F 2 |\n| 64 \u002F 1024 chars | Skill frontmatter `name` \u002F `description` hard limits | 1 |\n| 1 level | Skill reference-file depth from SKILL.md (never nested chains) | 1 |\n| > 100 lines | Reference file size that requires a leading table of contents | 1 |\n| Depth 4 | Maximum recursive `@import` depth in CLAUDE.md | 1 |\n| 4,000 chars | Copilot code review reads only this much of any instruction file | 2 |\n| 32 KiB | Codex default combined instruction-file budget (`project_doc_max_bytes`) | 2 |\n\nAll numbers live-verified 2026-06-10\u002F11; vendor docs churn, so re-verify before hard enforcement (see [sources.md](.\u002Fsources.md)).\n\n## See Also\n\n- [rubric.md](.\u002Frubric.md) — the practice-by-practice testable audit rubric\n- [sources.md](.\u002Fsources.md) — citations, verification dates, refuted claims, open questions\n- [scripts\u002Faudit-docs-mechanical.ps1](.\u002Fscripts\u002Faudit-docs-mechanical.ps1) — mechanical-check script for A2, B2, B3, B5, A9; headless\u002FCI mode\n- [templates\u002FCLAUDE.md-starter.md](.\u002Ftemplates\u002FCLAUDE.md-starter.md) — minimal CLAUDE.md seed template\n- `documentation-finalization` — updating implementation-facing docs after code changes\n- `project-references` — Agent Orchestra reference sidecars and index conventions (a house convention in open-gap territory)\n- `skill-creator` — repo-specific skill frontmatter and structure conventions\n\n## Gotchas\n\n| Trigger | Gotcha | Fix |\n| --- | --- | --- |\n| Moving CLAUDE.md overflow into `@import` files \"to save context\" | Imports load in full at launch — zero context savings, same adherence cost | Move content to a skill or child-directory CLAUDE.md, which load on demand |\n| Adding a rules file without a path scope | It loads every session, silently becoming always-loaded context | Add a `paths:`\u002Fglob scope, or move the content to a skill |\n| Writing a skill description in first person or omitting \"when to use\" | Description is the sole selection signal injected into the system prompt; the skill is never picked | Third person, state what it does AND when to use it, within 1024 chars |\n| Chaining reference files (SKILL.md → ref-a.md → ref-b.md) | Agents may partially read nested references (e.g., head-100 previews) and miss content | Link every reference file directly from SKILL.md, one level deep |\n| Assuming Copilot honors nested CLAUDE.md or `@`-imports | Copilot's cloud agent reads only a single flat root CLAUDE.md | Keep the root file self-sufficient for Copilot, or maintain AGENTS.md |\n| Padding CLAUDE.md with folder structure and dependency versions | JIT-discoverable, staleness-prone content that fails the deletion test (GitHub recommends it; Anthropic canon excludes it — known conflict) | Default to omitting; the agent can glob\u002Fgrep it fresh |\n",{"name":5,"description":7},"main","d5486aacc32c9ca1b07173cfd530f8fe75c29e58","skills\u002Fai-first-documentation",0,"https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra","https:\u002F\u002Fgithub.com\u002FGrimblaz","2026-08-16 01:12:46",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add Grimblaz\u002Fagent-orchestra --skill ai-first-documentation",{"tool":57,"command":58},"bunx","bunx skills add Grimblaz\u002Fagent-orchestra --skill ai-first-documentation",{"tool":60,"command":61},"pnpm","pnpm dlx skills add Grimblaz\u002Fagent-orchestra --skill ai-first-documentation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002FSKILL.md",true,[65,71,77,81],{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"rubric.md","REFERENCE","参考文档",12075,"https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002Frubric.md",{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"scripts\u002Faudit-docs-mechanical.ps1","SCRIPT","脚本",22227,"https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002Fscripts\u002Faudit-docs-mechanical.ps1",{"path":78,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":79,"sourceHtmlUrl":80},"sources.md",6838,"https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002Fsources.md",{"path":82,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":83,"sourceHtmlUrl":84},"templates\u002FCLAUDE.md-starter.md",1391,"https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fai-first-documentation\u002Ftemplates\u002FCLAUDE.md-starter.md",[86,118,143,158,183,204],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":98,"publishedAt":39},"01M6C48YMJVFHM7DVGG1WWW5RJ","webapp-testing","Playwright end-to-end testing guidance for web apps, with practical patterns and setup steps. Use when creating or improving browser-based E2E coverage, test stability, and CI execution. DO NOT USE FOR: React component tests (use ui-testing), canvas game interaction (use browser-canvas-testing), TDD workflow (use test-driven-development), debugging failures (use systematic-debugging), or randomized property tests (use property-based-testing).","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fwebapp-testing\u002FSKILL.md",[92,95],{"categoryNo":93,"categoryName":94,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":96,"categoryName":97,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",[99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,38],"testing","webapp testing","webapp","canvas","tdd","workflow","playwright","test","web","react","component","debugging","development","browser","ci","execution","e2e","game","coverage",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":39},"01M6C48TNNP2KCSQXV8YK7SK49","verification-before-completion","Evidence-based verification checklist before marking work complete. Use before PRs, releases, marking tickets done, or any \"I'm finished\" declaration; also when naming a baseline commit for a differential suite claim, when designing a mutation campaign or red-run evidence, when making an absence claim, a universal claim, or a one-time demonstration offered as a standing guarantee, when attributing a measurement or claiming a sweep or verification loop is complete, and when stating what a check or a CI suite will do about a change. DO NOT USE FOR: post-merge cleanup or archival (use post-pr-review) or processing GitHub review comments (use code-review-intake).","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fverification-before-completion\u002FSKILL.md",[],[125,126,127,128,129,130,131,132,133,134,135,136,113,137,138,139,140,38,141,142],"verification","verification before completion","review","change","commit","merge","pr","cleanup","run","code","code-review","intake","loop","verification loop","work","check","evidence","campaign",{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":149,"publishedAt":39},"01M6C48QZWNTP7JGKD32QZAKKX","validation-methodology","Reusable validation and review methodology for staged validation, failure triage, and prosecution-depth setup. Use when running validation ladders, triaging failures, or executing adversarial review passes. DO NOT USE FOR: CE Gate orchestration, specialist dispatch ownership, or step execution flow (keep those in Code-Conductor).","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fvalidation-methodology\u002FSKILL.md",[],[150,151,152,127,153,154,28,155,134,156,114,38,157],"validation","methodology","validation methodology","triage","orchestration","adversarial review","flow","dispatch",{"skillNo":159,"name":160,"nameZh":6,"description":161,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":162,"categories":163,"keywords":170,"publishedAt":39},"01M6C48MCAHG5Z79BJ369CRYRZ","upstream-onboarding","Shared opening-phase protocol for upstream agents (Experience-Owner, Solution-Designer, Issue-Planner) and Code-Conductor when invoked on an existing GitHub issue. Renders a scaled context brief and runs a standards check on inherited work at each phase boundary. Use when a user-invocable agent receives a request referencing an existing GitHub issue and must load solution-authoring and upstream-onboarding at the opening phase. DO NOT USE FOR: subagent dispatches (which already operate within an assessed session context); post-merge review (use post-pr-review); research or non-tree subagents.","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fupstream-onboarding\u002FSKILL.md",[164,165],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":166,"categoryName":167,"taxonomyType":168,"taxonomyTypeDesc":169},"01JBSEEDCAT000000000000038","人力资源","PROFESSION","适用职业",[171,172,127,173,26,130,174,131,134,175,176,177,178,179,180,139,140,181,182,38],"onboarding","upstream onboarding","github","standards check","protocol","brief","boundary","designer","subagent","planner","user","session",{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":197,"publishedAt":39},"01M6C48GPVE120TGPMD1CS365H","ui-testing","Resilient React component testing strategies focusing on user behavior. Use when writing or reviewing component-level React tests, fixing flaky component tests, or establishing React testing patterns. DO NOT USE FOR: Playwright E2E tests (use webapp-testing), canvas game interaction (use browser-canvas-testing), TDD workflow (use test-driven-development), debugging failures (use systematic-debugging), UI component design (use frontend-design), or randomized property tests (use property-based-testing).","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fui-testing\u002FSKILL.md",[189,190,191,194],{"categoryNo":93,"categoryName":94,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":96,"categoryName":97,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":192,"categoryName":193,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":195,"categoryName":196,"taxonomyType":168,"taxonomyTypeDesc":169},"01JBSEEDCAT000000000000032","设计师",[99,198,199,200,201,202,102,104,105,106,108,109,110,111,112,203,115,116,38,101],"ui","ui testing","frontend","design","writing","testing patterns",{"skillNo":205,"name":206,"nameZh":6,"description":207,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":208,"categories":209,"keywords":212,"publishedAt":39},"01M6C48DRJ9XBDR2FW0W37DY53","ui-iteration","Reusable screenshot-driven UI polish workflow for iterative visual refinement. Use when improving layout, hierarchy, spacing, feedback, or Tailwind-based presentation through repeated review-and-adjust passes. DO NOT USE FOR: functional bug fixing, accessibility-only audits, or major redesign strategy work (use Code-Smith or frontend-design).","https:\u002F\u002Fgithub.com\u002FGrimblaz\u002Fagent-orchestra\u002Fblob\u002Fmain\u002Fskills\u002Fui-iteration\u002FSKILL.md",[210,211],{"categoryNo":96,"categoryName":97,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":195,"categoryName":196,"taxonomyType":168,"taxonomyTypeDesc":169},[198,213,200,201,127,104,214,134,215,216,217,218,219,139,220,221,38,222],"ui iteration","accessibility","screenshot","Tailwind","polish","ui polish","feedback","redesign","strategy","only"]