init-context-docs

Files (6)

• SKILL.md
• agents-md-checklist.md · checklists/
• claude-md-checklist.md · checklists/
• guideline-checklist.md · checklists/
• readme-checklist.md · checklists/
• automated-checks.sh · scripts/

SKILL.md (first lines)

# Instructions

## Phase 1: Introduction

Output the following text verbatim to the user before taking any other action:

> This skill helps you build a layered documentation system for AI-assisted development. Each file has a distinct role:
>
> - **`docs/*-guidelines.md`** — Detailed, domain-specific playbooks (security, testing, database, etc.) with concrete rules agents follow, including how to verify compliance. Loaded on demand via the index in AGENTS.md or via Claude rules.
> - **`.claude/rules/*.md`** — Optional path-scoped loaders: each file imports a guideline and declares which file patterns trigger it, so the guideline only loads when relevant.
> - **`AGENTS.md`** — The open-standard onboarding doc for any AI agent (Claude, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf, etc.): cross-cutting conventions + an index pointing to the guideline files.
> - **`CLAUDE.md`** — A thin, Claude Code-specific layer that imports AGENTS.md and adds Claude-only behavior (build commands, etc.). Loaded unconditionally at the start of every session.
> - **`README.md` or `README.adoc`** — The front door: high-level project context for humans and agents alike.
>
> We'll check what's already in place, then walk through each file one phase at a time.
>
> **Note:** This is a demo skill. In a real-world project you might also want `CONTRIBUTING.md` (contribution conventions for both humans and agents) and `ARCHITECTURE.md` (high-level system design and key architectural decisions). This skill won't create those files.
>
> *This skill's design is grounded in first-party guidance from Anthropic and academic research (peer-reviewed papers marked ✅):*
> - [Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Anthropic
> - [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) — Anthropic
> - [AGENTS.md open standard](https://agents.md/) — Linux Foundation
> - [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/pdf/2602.11988) — Gloaguen et al. (ETH Zurich), arXiv preprint, 2026
> - ✅ [Lost in the Middle](https://arxiv.org/pdf/2307.03172) — Liu et al. (Stanford), TACL 2024
> - ✅ [Context Length Alone Hurts LLM Performance Despite Perfect Retrieval](https://arxiv.org/pdf/2510.05381) — Du et al., EMNLP Findings 2025
> - ✅ [On the Emergence of Position Bias in Transformers](https://arxiv.org/pdf/2502.01951) — Wu et al. (MIT), ICML 2025
> - [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/pdf/2601.20404) — Lulla et al. (Heidelberg, Bamberg, Singapore Management University), arXiv preprint, 2026
>
> **Key finding:** Two complementary studies point to the same conclusion: well-formed, minimal context files are associated with ~29% lower agent runtime and ~17% fewer output tokens (Lulla et al.), while files with unnecessary content actively reduce task success rates compared to no context at all (Gloaguen et al.). Every line added to these files should pass a strict necessity test: *"Would removing this cause an agent to make a mistake?"* If not, leave it out. The goal of this skill is the smallest set of high-signal content — not the most comprehensive documentation.

Use the AskUserQuestion tool to ask the user if they are ready to proceed.

## Phase 2: Assess (before)

Check whether each requirement is met, then present the results — do not modify any files:

```
| Requirement                                                            | Status |
|------------------------------------------------------------------------|--------|
| At least one `docs/*-guidelines.md` with domain-specific rules         |   ?    |
| `AGENTS.md` with cross-cutting conventions and a docs index            |   ?    |
| `CLAUDE.md` with `@AGENTS.md` import                                   |   ?    |
| `README.md` or `README.adoc` with project overview and getting-started |   ?    |
```

Replace each `?` with ✅ if met, ❌ if not. Then proceed to phase 3.

## Phase 3: Generate or update domain-specific guideline files

Output the following text verbatim to the user before taking any other action in this phase:

> Guideline files (`docs/*-guidelines.md`) are the deepest layer of the documentation system. They contain detailed, domain-specific rules — concrete conventions from your repo, not generic knowledge. Each guideline also tells agents how to verify their work: what commands to run, what output to check, what a passing state looks like.
>
> `AGENTS.md` will index these files. Optionally, each guideline can be paired with a `.claude/rules/<domain>.md` file that forces it into context whenever Claude works with matching files.
>
> **Each guideline file is capped at 200 lines** — context length alone degrades LLM performance regardless of content quality, so the most critical rules go first and verification commands go last.

Use the AskUserQuestion tool to ask the user if they want to generate or update guideline files. If they decline, skip to the next phase.

If they accept, follow this process:

### 3.1. Identify relevant domains

First, check if `AGENTS.md` exists and contains a docs index section. If it does, extract the domains already listed there — these were identified in a previous run and should be included in the suggested list.

Then, start from this curated list of domains:

| Domain | Includes |
|--------|----------|
| api-contracts | API design, REST conventions, versioning |
| async-and-messaging | async processing, message queues, event-driven architecture and background job conventions |
| code-organization | project structure conventions, module boundaries and import patterns |
| configuration | environment variables, feature flags and secrets handling |
| data-validation | serialization, deserialization and schema enforcement patterns |
| database | schema design, query patterns and migrations |
| dependency-management | version management, upgrade policies and supply chain conventions |
| deployment | deployment pipelines, infra-as-code conventions, environment management and release process |
| error-handling | error handling patterns and propagation |
| integration | integration patterns, external services and webhooks |
| logging-and-observability | logging standards, metrics, tracing and diagnostic conventions |
| performance | concurrency, thread safety, resource contention |
| security | security patterns, authentication and authorization |
| testing | test patterns and coverage |

Merge the curated list with any previously identified domains from AGENTS.md (including custom domains the user may have added in a prior run).

Use an Explore agent with the Sonnet model to scan the repository and determine:
1. Which domains from the merged list are relevant — a domain is relevant if the repo contains code, configuration, or patterns that fall within that domain (e.g., skip `database` if there is no database usage, skip `api-contracts` if there are no REST APIs)
2. Any additional domains not on the curated list that would benefit from a dedicated guideline — look for prominent frameworks, toolchains, workflows, or cross-cutting patterns in the repo that don't fit any curated category (e.g., `graphql`, `machine-learning`, `mobile-ios`, `data-pipeline`)

Present the combined list to the user. Use AskUserQuestion to confirm the final list, allowing the user to add, remove, or rename any entry.

### 3.2. Explore and generate guidance

Tell the user that background agents are now running for each confirmed domain and that this may take a few minutes depending on the size of the codebase.

For each confirmed domain, launch an Explore agent in the background using the Opus model. Each agent must:

1. Read `checklists/guideline-checklist.md` to understand the quality criteria the guideline must meet
2. Thoroughly explore the repository from its domain perspective — read source code, configuration files, existing documentation, test patterns, and any other relevant files
3. Identify the conventions, patterns, libraries, frameworks, and practices used in the repo for that domain
4. If `docs/<domain>-guidelines.md` already exists, read it first and incorporate its content — update with new findings while preserving still-accurate content
5. Return the complete guideline content as its result — do NOT write any files

The agent decides the structure of the guideline content based on what it finds. The checklist defines all quality criteria.

Once all exploration agents have completed, ensure the `docs/` directory exists and write each guideline to `docs/<domain>-guidelines.md`. Then proceed to verification.

### 3.3. Verify guideline accuracy

Tell the user that verification agents are now running for each guideline. This may take a moment.

For each domain, launch a verification agent in the background (subagent_type: Explore, Sonnet model). Each agent must:

1. Read `checklists/guideline-checklist.md` — this is the single source of truth for what the guideline must satisfy
2. Read `docs/<domain>-guidelines.md` for its assigned domain and all other `docs/*-guidelines.md` files
3. Validate the guideline against every item in the checklist — use Grep, Glob, and WebSearch as needed
4. Return the corrected version of the guideline as its result — do NOT write any files, do NOT add new domain content; only correct inaccuracies, reconcile contradictions, and add a Verification section if one is missing

From gwenneg/blog-ai-friction-loop, Apache-2.0.

More from gwenneg/blog-ai-friction-loop