AI agent skill · by @videojs

Maintain Agent Docs

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

Archived 2026-10-23 · Source updated 2026-10-08. Check the original repository for the latest version.

SKILL.md instructions

# 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.