Init Agent Docs

init-agent-docs

> Initialize a project with structured documentation for AI coding agents (Claude Code, Cursor, Copilot, etc.).

Overview

This skill scaffolds agent-friendly documentation for any project. It creates:

• CLAUDE.md — Manifest file that references all agent guides (loaded by Claude Code on startup)
• AGENTS.md — Main entry point with project overview, setup commands, and links to detailed guides
• .agents/*.md — Detailed guides covering structure, architecture, testing, and conventions
• .agents/references/ (optional) — One Markdown file per external project the codebase cross-references; only create when conventions.md keeps its References section
• .agents/plans/ (optional) — Phased plan files for ongoing modernization or migration work; only create when AGENTS.md keeps its Plans section

When to Use

• Setting up a new repository for AI-assisted development
• Adding agent documentation to an existing project
• When the user asks to "init agent docs", "create Claude docs", "set up for AI coding", or similar

Process

1. Analyze the target project — Read package.json (or equivalent), explore the directory structure, understand the tech stack, build system, test setup, and architecture. For monorepos, identify all apps and packages plus their dependency relationships.
2. Determine which guides apply — Not every project needs all guides. Select from the available templates based on what the project actually has:

• structure.md — Always applicable (every project has a file layout)
• architecture.md — Include when the project has meaningful design patterns, layered architecture, or notable data flow
• testing.md — Include only if the project has tests
• conventions.md — Include when there are linting, commit conventions, validation patterns, CI/CD, or build tooling

1. Adapt templates for project type — Templates contain sections for both monorepos and single packages. Use only the relevant sections:

• Monorepos: Use Applications/Packages tables, Dependency Layers, workspace-specific test commands
• Single packages: Use Directory Layout, Module Responsibilities, Key Dependencies

1. Generate from templates — Use the templates in [templates/](templates/) as starting points. Replace all {{placeholders}} with project-specific information. Remove HTML comments and unused sections. Add project-specific sections as needed (e.g., design patterns with code examples).
2. Write the files — Create CLAUDE.md, AGENTS.md, and the selected .agents/*.md files in the project root. If conventions.md keeps its References section, create .agents/references/ (and seed one file per external project). If AGENTS.md keeps its Plans section, create .agents/plans/ (and add the phased plan files it links to).

Available Templates

| Template | Purpose | When to include | |-------------------------------------------------------------|-----------------------------------|------------------------------| | [CLAUDE.md](templates/CLAUDE.md) | Manifest/index file | Always | | [AGENTS.md](templates/AGENTS.md) | Main agent guide | Always | | [.agents/structure.md](templates/.agents/structure.md) | Project structure & modules | Always | | [.agents/architecture.md](templates/.agents/architecture.md)| Design patterns & data flow | When architecture is notable | | [.agents/testing.md](templates/.agents/testing.md) | Test setup & conventions | When tests exist | | [.agents/conventions.md](templates/.agents/conventions.md) | Code style, tooling, CI/CD | When conventions are defined |

Guidelines

• Do not copy templates verbatim. Every section must be filled with real, project-specific content. Empty or placeholder sections are worse than no documentation.
• Be concise. Agents work best with dense, factual content. Avoid filler text.
• Use tables and code blocks for structured information — they parse well for agents.
• Keep AGENTS.md under 200 lines. Move details into .agents/*.md files.
• Omit guides that don't apply. A project without tests should not have a testing.md.
• Update CLAUDE.md to only reference the guides that were actually created (uncomment the relevant @ lines).
• Include code examples in architecture.md when documenting design patterns. Show actual interfaces and implementations so agents can follow the patterns when writing new code.
• Document dependency layers for monorepos. This is critical for agents to understand build order and impact of changes.
• Add the NOTE comment at the top of AGENTS.md reminding to keep docs updated as the project evolves.
• Document per-application layouts for monorepos in structure.md. Show the internal directory tree of each service/app, especially when they follow a specific architecture pattern (hexagonal, MVC, etc.).
• Prefer fakes over mocks in testing.md when the project uses hexagonal architecture or dependency inversion. Guide agents toward fake implementations of port interfaces rather than vi.fn()/vi.mock().
• Include a References section in conventions.md when the project depends on external projects that agents may need to cross-reference. Use .agents/references/ to build cumulative code mappings.
• Add Plans and Commits sections to AGENTS.md when the project has ongoing modernization work or commit rules that override default agent behavior.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tada5hi
• Source: tada5hi/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.