agents-md

Files (3)

• SKILL.md
• best-practices.md · references/
• examples.md · references/

SKILL.md (first lines)

# Agents Md

AGENTS.md is a README for AI agents: a dedicated place to provide context and instructions to help AI coding agents work effectively on a project.

## Important: Keep It Minimal

**Key principle**: Include only what agents cannot infer from the codebase itself. Redundant documentation is harmful—agents already read files, search code, and understand common patterns.

## When to Create/Update

- **Create**: When the project has non-obvious tooling, specific commands, or critical boundaries agents must know
- **Update**: When commands change, new critical constraints are added, or tooling requirements evolve
- **Omit**: If your repository has standard structure and common tooling (React, Python, etc.) that agents already understand

## What to Include

Focus only on information agents cannot discover themselves:

### 1. Essential Commands (Required)

Specific commands with full flags. Include only if non-standard or critical.

```markdown
## Commands

- Install: `pnpm install`
- Dev: `pnpm dev --port 3000`
- Test: `pnpm test --coverage`
- Build: `pnpm build`
```

**Skip this section if using standard commands** (e.g., `npm install`, `npm test`).

### 2. Tooling Requirements (If Non-Standard)

Specify tools agents should use. Research shows agents DO follow specific tool instructions (e.g., `uv` usage increases 1.6x when mentioned).

```markdown
## Tooling

- Use `uv` for Python dependency management
- Use `ruff` for linting (not flake8)
- Use `just` for task running (not Make)
```

**Only include if different from defaults** agents would assume.

### 3. Boundaries (Critical)

What agents must NEVER do. This is the highest-value content.

```markdown
## Boundaries

- Never commit secrets, API keys, or `.env` files
- Never modify `vendor/`, `node_modules/`, or lock files
- Never remove failing tests—fix or ask first
- Ask before changing database schemas
```

**Always include this section.** It prevents costly mistakes.

### 4. Project-Specific Patterns (If Unusual)

Only document patterns that differ from standard conventions in your stack.

```markdown
## Patterns

- Use functional React components, not classes
- Place tests in `__tests__/` folders (not `.test.ts` files)
- Import order: React, third-party, `@/`, relative
```

**Skip if following standard conventions** for your framework/language.

## What to Avoid

Based on research findings, do NOT include:

### ❌ Codebase Overviews

Research shows "context files do not provide effective overviews"—agents don't discover files faster with overviews present. They already search and explore code effectively.

**Don't write:**

```markdown
## Overview

This is a React application with a component-based architecture...
```

### ❌ Comprehensive Structure Documentation

Listing every directory is redundant. Agents can explore the filesystem.

**Don't write:**

```markdown
## Structure

- `src/components/` - React components
- `src/hooks/` - Custom hooks
- `src/utils/` - Utility functions
```

### ❌ Obvious Style Guidelines

Agents already know common patterns (camelCase, functional components, etc.).

**Don't write:**

```markdown
## Code Style

- Use camelCase for functions
- Use PascalCase for components
- Prefer const over let
```

From adampoit/ai, MIT.

More from adampoit/ai