Maintaining AGENTS.md

File Setup

1. Create

   AGENTS.md

   at project root
2. Create symlink:

   ln -s AGENTS.md CLAUDE.md

Before Writing

find .claude/skills -name "SKILL.md" 2>/dev/null
ls plugins/*/skills/*/SKILL.md 2>/dev/null

Writing Rules

• Headers + bullets - No paragraphs
• Code blocks - For commands and templates
• Reference, don't duplicate - Point to skills: "Use

  db-migrate

  skill. See

  .claude/skills/db-migrate/SKILL.md

  "
• No filler - No intros, conclusions, or pleasantries
• Trust capabilities - Omit obvious context

Required Sections

Package Manager

## Package Manager
Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`

Commit Attribution

## Commit Attribution
AI commits MUST include:

Example: `Co-Authored-By: Claude Sonnet 4 <noreply@example.com>`

Key Conventions

Local Skills

## Database
Use `db-migrate` skill for schema changes. See `.claude/skills/db-migrate/SKILL.md`

## Testing
Use `write-tests` skill. See `.claude/skills/write-tests/SKILL.md`

Optional Sections

• API route patterns (show template, not explanation)
• CLI commands (table format)
• File naming conventions

Anti-Patterns

• "Welcome to..." or "This document explains..."
• "You should..." or "Remember to..."
• Content duplicated from skills (reference instead)
• Obvious instructions ("run tests", "write clean code")
• Explanations of why (just say what)
• Long prose paragraphs

Example Structure

# Agent Instructions

## Package Manager
Use **pnpm**: `pnpm install`, `pnpm dev`

## Commit Attribution
AI commits MUST include:

## API Routes
[Template code block]

## Database
Use `db-migrate` skill. See `.claude/skills/db-migrate/SKILL.md`

## Testing
Use `write-tests` skill. See `.claude/skills/write-tests/SKILL.md`

## CLI
| Command | Description |
|---------|-------------|
| `pnpm cli sync` | Sync data |