Skip to main content
Every codebase has conventions — how you name branches, which commands run tests, where important files live. Without context, agents guess: they run npm test when your project uses yarn test, or put a component in the wrong directory. AGENTS.md teaches them your conventions, commands, and architecture so they produce code that fits your project. AGENTS.md is an open standard stewarded by the Linux Foundation, supported by Ona and other AI coding tools. Think of it as a README for agents — the tribal knowledge that senior engineers carry in their heads.

​
Create your AGENTS.md

Create an AGENTS.md file in your repository root: 
# Project Guidelines

## Commands
- `npm test` - Run tests
- `npm run build` - Build for production
- `npm run lint` - Check code style

## Project Structure
- `src/components/` - React components
- `src/utils/` - Helper functions
- `src/api/` - API client and types

## Code Style
- Use TypeScript for all new files
- Components use PascalCase (e.g., `UserProfile.tsx`)
- Utilities use camelCase (e.g., `formatDate.ts`)
Ona Agent automatically loads this file at the start of every session.

​
Keep it concise

Shorter is better. As instruction count increases, instruction-following quality decreases. Aim for:
  • Under 300 lines - the recommended maximum
  • Under 60 lines - ideal for most projects
If you need more detail, link to other files rather than duplicating content: 
## Code Style
Follow the guidelines in [CONTRIBUTING.md](./CONTRIBUTING.md)

​
What to include

Commands - The most important section. Tell agents exactly how to:
  • Run tests
  • Build the project
  • Start the dev server
  • Lint and format code
Project structure - Where things live:
  • Key directories and their purpose
  • Where to add new components or features
Conventions - How your team does things:
  • Branch naming patterns
  • Commit message format
  • Code style rules
Security considerations - What to avoid:
  • Files that should never be committed
  • Sensitive patterns to watch for
  • Security-related commands to run

​
Make critical rules stand out

Agents pay attention to emphasis. For rules that must not be broken: 
**IMPORTANT**: Always run `npm run typecheck` before committing.

**ALWAYS** use the `useApi` hook for data fetching, never raw fetch calls.

**NEVER** commit .env files or API keys.

​
Use nested files for large projects

For monorepos or large codebases, you can place AGENTS.md files in subdirectories. Agents read the nearest file in the directory tree, so each package can have tailored instructions: 
repo/
├── AGENTS.md              # Global conventions
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API-specific instructions
│   └── web/
│       └── AGENTS.md      # Frontend-specific instructions

​
Example

# Project Guidelines

## Commands
- `npm test` - Run test suite (required before PR)
- `npm run build` - Production build
- `npm run dev` - Start dev server at localhost:3000
- `npm run typecheck` - TypeScript validation

**IMPORTANT**: Run `npm test` and `npm run typecheck` before creating a PR.

## Project Structure
- `src/components/` - Reusable UI components
- `src/features/` - Feature-specific code
- `src/lib/` - Shared utilities

## Conventions
- TypeScript for all files
- Components: PascalCase (`UserCard.tsx`)
- Branch naming: `initials/short-description`

## Security
**NEVER** commit `.env` files or hardcode API keys.
Run `npm run security-check` before merging to main.
After adding AGENTS.md, start a session and ask the agent to make a change. If it misses a convention, add emphasis or move that rule higher in the file.

​
Skills for multi-step workflows

Agent Skills are SKILL.md files that live in your repository. For repeatable, multi-step procedures (deployment workflows, triage runbooks, PR checklists), use repository skills. The agent discovers and loads them automatically when a task matches. For organization-wide workflows that apply across all projects, use organization skills.

​
Getting notified when an agent finishes

Enable the completion sound in Settings > Preferences to hear when a task completes. For webhook-style notifications, add an instruction to your AGENTS.md that tells the agent to run a curl command after completing all work: 
After completing all tasks, run in the background:
curl -X POST -H "Content-Type: application/json" \
  -d '{"status": "done"}' https://your-webhook-url.com/
You can also monitor task completion programmatically via the WatchEvents API method.

​
Next steps