AGENTS.md Authoring

by Sentry

Apache-2.0

Repository Docs

markdown Writing & Communication

documentationagentsconventions

Summary

Write and maintain concise AGENTS.md and CLAUDE.md files that document the conventions an agent actually needs.

Features

Creates concise, reference-backed AGENTS.md and CLAUDE.md files
Documents conventions agents actually need
Keeps instruction files maintained rather than stale

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

Copy the skill content with the button below.
Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
Ask the agent to apply the skill whenever the task matches.

Claude Code & Claude apps

Claude loads skills automatically from its skills directory.

Claude Code

Create a skill folder — personal: ~/.claude/skills/agents-md/, or per-project: .claude/skills/agents-md/
Save the skill content as SKILL.md inside that folder.
Claude Code picks it up automatically and invokes it when relevant.

mkdir -p ~/.claude/skills/agents-md

Claude.ai / Claude Desktop

Enable Skills under Settings → Capabilities, then upload the skill (a folder or zip containing SKILL.md).

One-prompt install

Paste this prompt into any agent with web access and it will install the skill for you.

Install the "AGENTS.md Authoring" skill from Onei AI. Fetch https://onei.ai/skills/agents-md, extract the full skill content from the page, and save it where you load skills from (for Claude Code: .claude/skills/agents-md/SKILL.md). From now on, apply this skill whenever it is relevant to my request.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

# 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
2. 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
3. Write the smallest useful file.
4. 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:

```markdown
## 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

Description

Project instruction files fail in two directions: too thin to be useful, or so long that the important rules are buried. This skill produces ones that work.

It covers what belongs in an AGENTS.md or CLAUDE.md — build and test commands, architectural constraints, conventions that are not obvious from the code, and the mistakes newcomers reliably make — and, just as importantly, what does not: restating what the code says, generic best practice, and anything an agent can determine by looking.

It also covers maintenance, since the main failure mode of these files is drifting out of date until they actively mislead. Every claim is expected to be backed by a reference in the repository rather than asserted. Published by Sentry.

Related Skills

UX Writing

by content-designer (Christopher Greer)

Write and audit interface microcopy, from buttons to error messages, against four checkable quality standards.

Writing & Communication

ux-writingmicrocopycontent-design

Browse all skills →