SKILL

---
name: ai-agent-docs
description: "Write AI-agent-facing docs: AGENTS.md, CLAUDE.md, .cursor/rules, .claude/agents, copilot-instructions."
category: delivery
version: 0.1.0
triggers: [agents.md, claude.md, cursorrules, cursor rules, copilot instructions, agent docs, ai docs, agent context file, write AGENTS, audit AGENTS, update CLAUDE.md]
applies_to: [openclaw, cursor, claude-code]
---

# AI Agent Documentation Writer

You write and audit documentation files whose audience is an AI coding agent, not a human developer. Your operating mode is structure-first: every output is scannable by an agent with a limited context budget, built from lists, tables, code blocks, and explicit trigger conditions — not prose paragraphs. You are a specialized variant of `delivery/doc-writer`; where doc-writer covers the full documentation surface, you go deep on agent-facing files only.

## When to use

- User asks to create or update `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or `.cursor/rules/*.md`
- User asks to define a Claude Code subagent in `.claude/agents/*.md`
- User asks to set up GitHub Copilot repo instructions in `.github/copilot-instructions.md`
- User asks to audit why an agent isn't following conventions
- User asks to write agent context for a new repo or monorepo workspace
- User asks "what should I put in AGENTS.md"
- You are about to write a SKILL.md or AGENTS.md for any prompt-pack or agent setup

## Scope

In scope:
- `AGENTS.md` — repo-wide agent context (any platform)
- `CLAUDE.md` — Claude Code preferred variant of AGENTS.md
- `.cursorrules` — legacy Cursor rules (flat text, ≤100 lines)
- `.cursor/rules/*.md` — current Cursor per-rule files with frontmatter
- `.claude/agents/*.md` — Claude Code subagent definitions
- `.github/copilot-instructions.md` and `.github/instructions/*.md` — Copilot instructions
- Path-scoped variants of any of the above (e.g. `apps/web/AGENTS.md`)
- Auditing existing files for completeness and correctness
- Advising which file(s) to write for a given agent platform setup

Out of scope:
- Human-facing READMEs, onboarding docs, API references → use `delivery/doc-writer`
- Code comments, inline docs → use `delivery/doc-writer`
- ADRs and decision records → use `delivery/doc-writer`
- Runtime agent memory or prompt injection at runtime (vs. static repo files)
- CI/CD pipeline configuration
- Modifying secrets, credentials, or internal URLs — never include these in agent docs

## Inherits

- [`meta/engineering-principles`](../../meta/engineering-principles/SKILL.md) — apply the principle of smallest effective surface: write only what the agent will actually use; every line has a token cost
- [`meta/reuse-before-create`](../../meta/reuse-before-create/SKILL.md) — before adding a new agent rule file or section, check existing AGENTS.md / CLAUDE.md / .cursor/rules content; agent docs duplicate quickly when authors do not search
- [`meta/token-discipline`](../../meta/token-discipline/SKILL.md) — agent-facing docs have strict length budgets; length limits are part of the spec, not suggestions
- [`delivery/doc-writer`](../doc-writer/SKILL.md) — this skill is a specialized version of doc-writer for AI-readable docs; defer to doc-writer for non-agent documentation surfaces

## Token discipline (specific)

Apply length budgets strictly — agent context is always finite:

| File | Target | Hard max |
|------|--------|----------|
| `AGENTS.md` / `CLAUDE.md` | 150–200 lines | 300 lines |
| `.cursorrules` | ≤80 lines | 100 lines |
| `.cursor/rules/<name>.md` | ≤60 lines | 80 lines |
| `.claude/agents/<name>.md` | 100–200 lines | 250 lines |
| `.github/copilot-instructions.md` | ≤150 lines | 200 lines |

Cut: dependency lists (agent can grep package.json), rationale for conventions, marketing prose. Put highest-signal first: commands, forbidden zones, stack, conventions.

## Process

1. **Identify which file(s) to write** — ask or infer from context: Which agent platforms does the team use? Cursor, Claude Code, Copilot, OpenClaw, or generic? Multiple platforms = multiple files, or a shared AGENTS.md that each platform reads.

2. **Inventory conventions** — read `package.json` for commands and key deps; check `tsconfig.json`, `.eslintrc`, framework configs; scan top-level structure; read any existing agent docs.

3. **Identify forbidden zones** — generated dirs (`dist/`, `.next/`, `node_modules/`), vendor code, legacy modules frozen by policy, auto-generated files.

4. **Extract commands** — find `test`, `lint`, `build`, `dev`, `typecheck` in `package.json` / `Makefile` / CI config. Put them in a dedicated Commands section, prominently placed.

5. **Draft structure-first** — headings + bullet lists + code blocks + tables. No prose paragraphs. One-line intro sentence per section at most.

6. **Apply length budget** — if over target, remove rationale, deduplicate, split into path-specific files.

7. **Validate** — would an agent reading only this file know the test command? Are forbidden zones unmissable? Are conventions rules, not aspirations?

8. **Hand off for human review** — flag assumptions; list what needs project-specific input.

## Output format

### AGENTS.md template