# Maintain Agent Docs

> Maintain repository agent guidance. Use for AGENTS.md, CLAUDE.md compatibility, skill drift, duplicated instructions, or context budgets.

- Skill: `videojs/maintain-agent-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add videojs/maintain-agent-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/videojs/maintain-agent-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: videojs (https://skillmd.com/u/videojs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/videojs/maintain-agent-docs

---


# Agent documentation

Keep agent guidance as a routing and correction layer over project sources, not a second documentation system.

## Placement

- Put durable, broadly applicable repository facts in the nearest `AGENTS.md`.
- Keep each `CLAUDE.md` as `@AGENTS.md` unless Claude-only behavior is genuinely required.
- Put an explicit, repeatable vertical workflow in a skill.
- Keep checked-in skills as direct children of `.agents/skills/`; treat `.claude/skills/` and `.opencode/skills/` as generated directory aliases.
- Put conditional detail in a directly linked skill reference.
- Put rules that can be mechanically checked in code, tests, lint, hooks, or `build/scripts/check-workspace.mjs`.
- When the user explicitly requests a durable record, put architecture rationale in `internal/design/`, `internal/decisions/`, or `rfc/`; never create one as a default by-product of other work.

## Process

1. Identify the repeated failure or new fact and the executable source that proves it.
2. Search existing agent docs and skills for overlap or contradiction.
3. Prefer updating a source pointer or validator over copying code, schemas, commands, or examples.
4. Remove obsolete guidance in the same change.
5. Keep skill frontmatter portable: `name` and a precise `description` only.
6. Run `pnpm check:workspace` and review the reported context budgets.

Do not add generic software advice the model already knows. Add a rule only when an agent would plausibly get this repository wrong without it.

## Example

Input: “Remove duplicated setup instructions from agent guidance.”

Output: Smaller routing docs that point to executable sources, corrected aliases, passing validators, and an updated context-budget report.