write-docs

Files (16)

• README.md
• SKILL.md
• agents-md.md · instructions/
• architecture-md.md · instructions/
• ci-cd-md.md · instructions/
• conventions-md.md · instructions/
• domain-md.md · instructions/
• feature-readme-md.md · instructions/
• infrastructure-md.md · instructions/
• local-development-md.md · instructions/
• observability-md.md · instructions/
• product-md.md · instructions/
• release-md.md · instructions/
• review.md · instructions/
• security-md.md · instructions/
• testing-md.md · instructions/

SKILL.md (first lines)

# Write Project Docs

## Purpose

Create or update project-specific documentation that helps AI coding agents and human maintainers understand the repository accurately.

The goal is not to create a large documentation site. The goal is to create a small, reliable documentation set that captures stable project knowledge and points agents to the right places.

Use progressive disclosure:

- Keep `AGENTS.md` short.
- Put detailed project knowledge in focused files under `docs/`.
- Use one target document per documentation type.
- Do not mix generic engineering preferences into project docs.

## Trigger

See this skill's `description` for the authoritative invocation rules.

## Scope levels

Project documentation lives at three scopes. Each scope has a different file and different rules.

| Scope | File | Purpose |
|---|---|---|
| Root | `AGENTS.md` (+ `CLAUDE.md` referencing it) | Repo-wide orientation. Links to project docs. ≤ 50 lines. |
| Package or feature folder | `<folder>/README.md` | Conventions specific to that folder only. ≤ 40 lines. |
| Cross-repo container | None | When multiple sibling repos live under one opened folder, do not write a global root file. Treat each child repo independently. |

Per-folder rules use `README.md` because it is portable across Cursor, Claude Code, Copilot, and other tools, and because folders that already have a `README.md` can absorb the rules without adding a new file type.

Do not create nested `AGENTS.md` files inside packages or feature folders by default.

## Review mode

Review mode audits existing project documentation and proposes changes. It is a separate operating mode from writing new docs.

### When to enter Review mode

Enter Review mode when the user asks to:

- audit project docs
- review project docs
- refactor `AGENTS.md` or `CLAUDE.md`
- check if docs are bloated, stale, or contradictory
- clean up `docs/`

Also enter Review mode when, during normal inspection, you discover that the repo already has substantial project docs (for example: `AGENTS.md` over 50 lines, multiple files under `docs/`, an existing `CLAUDE.md` with project content, `.cursorrules`, or `.github/copilot-instructions.md`). In that case, ask the user before writing anything:

```markdown
This repo already has project docs:
- `<file>` (<N> lines)
- `<file>` (<N> lines)

How should I proceed?
1. Review and refactor under the standard structure.
2. Keep the current structure; only fix specific issues I find.
3. Leave existing docs alone; only add what is missing.
```

Do not refactor existing docs without explicit approval.

### Review mode flow

Use `instructions/review.md` as the writing specification for the audit. It defines the discovery sources, the audit checklist, and the report format.

The flow is:

1. **Discover** existing docs across all known locations.
2. **Audit** them against the checklist in `instructions/review.md`.
3. **Report** findings to the user grouped by severity.
4. **Wait** for the user's choice (refactor / fix-specific / leave as is).
5. **Act** only on what the user approved.

Do not modify any file during discovery or audit. Reports are read-only.

## Documentation set

Default project docs:

```text
AGENTS.md
docs/
  product.md
  domain.md
  local-development.md
  infrastructure.md
  ci-cd.md
```

Optional docs:

```text
docs/
  architecture.md
  testing.md
  release.md
  observability.md
  security.md
  <area>.md  (language, framework, or workflow conventions — see below)
```

### Conventions docs

When the *Inspect before writing* step finds language-, framework-, or workflow-specific rules in existing `AGENTS.md`, `CLAUDE.md`, linter config, or formatter config, propose one conventions doc per area instead of inlining rules in root `AGENTS.md`.

Common names: `docs/typescript.md`, `docs/python.md`, `docs/csharp.md`, `docs/api.md`, `docs/git.md`, `docs/sql.md`, `docs/styling.md`.

Use `instructions/conventions-md.md` when writing these files.

Do not create a conventions doc for an area with no project-specific rules.

### Per-package and per-feature `README.md`

When the *Inspect before writing* step detects a monorepo, workspaces, or a vertical-slice / feature-folder layout, also propose a per-folder `README.md` for each package or feature with conventions distinct from the root.

Use `instructions/feature-readme-md.md` when writing these files.

Do not propose a per-folder `README.md` for folders that have nothing folder-specific to say. A folder that follows root conventions exactly does not need one.

From bogdanbujdea/ai-coding-playbook, MIT.

More from bogdanbujdea/ai-coding-playbook