agents-md

SKILL.md

Maintaining AGENTS.md

Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100.

Workflow

Inspect before writing:

package manager: lock files and manifests

commands: package.json, Makefile, task runners, CI workflows

docs/specs/policies: README.md, CONTRIBUTING.md, docs/, specs/, policies/, SECURITY.md, .github/

conventions: current code patterns, test layout, generated files, legacy areas to avoid

Choose scope:

root AGENTS.md: repo-wide defaults

nested AGENTS.md: only when a subtree has different commands or rules

closest instruction file wins; keep narrower files shorter than root files

Write the smallest useful file.

Verify exact paths and commands exist.

File Setup

Create AGENTS.md at the repository root.

If a Claude-compatible entrypoint is required, symlink CLAUDE.md to AGENTS.md.

Do not maintain divergent AGENTS.md and CLAUDE.md copies.

Default Sections

Use only sections that add non-obvious value.

# Agent Instructions

## Package Manager
- Use **pnpm**: `pnpm install`

## Commands
| Task | Command |
|------|---------|
| Test file | `pnpm vitest run path/to/file.test.ts` |
| Lint file | `pnpm eslint path/to/file.ts` |

## External References
| Need | File |
|------|------|
| Setup | `CONTRIBUTING.md` |
| Architecture | `docs/architecture.md` |
| Security policy | `SECURITY.md` |

## Key Conventions
- Generated files: update with `pnpm generate`; do not edit by hand.

## Commit Attribution
AI commits MUST include:
```
Co-Authored-By: (the agent's name and attribution byline)
```

Writing Rules

Use headings, bullets, and tables; avoid paragraphs.

Use repo-relative paths; avoid vague references like "see docs".

Reference existing docs/specs/policies instead of copying them.

List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.

Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.

Put commands in tables when there is more than one.

Keep one rule per bullet.

Keep rationale out unless it prevents a likely mistake.

Do not restate linter, formatter, or typechecker config.

Do not list installed skills or plugins.

Do not include generic quality slogans.

External Reference Rules

Good:

## External References
| Need | File |
|------|------|
| API contract | `docs/api.md` |
| Release process | `docs/releasing.md` |

Anti-Patterns

welcome text, intros, conclusions, or pleasantries

long prose explaining why instructions matter

duplicated content from README.md, CONTRIBUTING.md, or policy docs

project-wide commands when file-scoped commands are available

nested AGENTS.md files that repeat root instructions