Agents Md

Maintaining AGENTS.md

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

Workflow

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

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

1. Write the smallest useful file.
2. 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.

````markdown

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: getsentry
• Source: getsentry/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.