Teach agents your codebase

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

Create organization skills for organization-wide workflows
Set up your first environment so agents have a reliable run loop
Learn more at agents.md

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Create your AGENTS.md

Keep it concise

What to include

Make critical rules stand out

Use nested files for large projects

Example

Skills for multi-step workflows

Getting notified when an agent finishes

Next steps

​Create your AGENTS.md

​Keep it concise

​What to include

​Make critical rules stand out

​Use nested files for large projects

​Example

​Skills for multi-step workflows

​Getting notified when an agent finishes

​Next steps

Create your AGENTS.md

Keep it concise

What to include

Make critical rules stand out

Use nested files for large projects

Example

Skills for multi-step workflows

Getting notified when an agent finishes

Next steps