Skip to main content
Every codebase has conventions - how you name branches, which commands run tests, where important files live. When agents understand these conventions, they write code that fits your project and run the right commands the first time. AGENTS.md is how you teach them.

​
Why this matters

Without context, agents guess. They might run npm test when your project uses yarn test. They might create a branch called feature/new-thing when your team uses initials/issue-description. They might put a component in the wrong directory. With an AGENTS.md file:
  • Agents follow your conventions: They know your branch naming, commit message format, and code style.
  • Agents run the right commands: They know how to test, build, lint, and deploy your project.
  • Agents understand your architecture: They know where to put new code and which patterns to follow.
The result: agents produce code that looks like your team wrote it.

​
An industry standard

AGENTS.md is an open standard for guiding AI coding agents, now stewarded by the Linux Foundation. It works across the ecosystem:
  • OpenAI Codex
  • Google Jules
  • Cursor
  • Claude Code
  • Factory, Aider, Zed, and more
Think of it as a README for agents. Your README.md is for humans - quick starts and project descriptions. AGENTS.md contains the tribal knowledge that senior engineers carry in their heads: build steps, test commands, and conventions that agents need to work effectively.

​
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 conversation.

​
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.

​
See it working

Once you’ve added AGENTS.md, start a conversation with Ona Agent and ask it to make a change. You’ll see it:
  1. Reference your conventions when writing code
  2. Run the correct commands from your Commands section
  3. Put files in the right places based on your Project Structure
If the agent misses something, add emphasis or move that rule higher in the file.

​
Skills for repository-specific workflows

Agent Skills are SKILL.md files that live in your repository. Use them for multi-step procedures specific to a codebase - deployment workflows, migration patterns, or project-specific review checklists. For organization-wide workflows that apply across all projects, use slash commands instead. Place skills in .ona/skills/ or .claude/skills/: 
.ona/skills/
├── create-pr/
│   └── SKILL.md
└── sentry-triage/
    └── SKILL.md

---
name: create-pr
description: Create a pull request for code changes. Use when asked to create a PR, open a PR, submit changes, or land changes.
---

# Create PR

## Steps

1. **Clean up code** - remove obvious comments from new/changed code
2. **Format** - run `gofmt` (Go) or `prettier` (JS/TS)
3. **Lint** - run `golangci-lint run ./...` (Go) or `eslint` (JS/TS)
4. **Create branch** - `<initials>/<short-description>` (max 24 chars, get initials from `git config user.name`)
5. **Commit** - use Conventional Commits, add `Co-authored-by: Ona <[email protected]>`
6. **Push** - `git push -u origin <branch-name>`
7. **Open draft PR** - use `.github/pull_request_template.md`

## Anti-patterns

- Don't use superlatives in commits or PR descriptions
- Don't include implementation details
- Don't commit unrelated changes
- Don't push to main directly

---
name: sentry-triage
description: Find and triage Sentry errors. Creates a Linear ticket with analysis.
---

# Sentry Triage

Find the highest-impact untriaged Sentry error and create ONE Linear ticket.

## Workflow

1. **Find first untriaged issue** - Query Sentry for unresolved errors in last 24 hours, sorted by event count
2. **Skip if tracked** - Search Linear for existing ticket with Sentry ID
3. **Check if already fixed** - Look for recent commits that address the error
4. **Analyze** - Get stacktrace, identify root cause, classify as bug/false-positive/noise
5. **Create Linear issue** - Title includes Sentry ID, description has stacktrace and fix assessment

## What this skill does NOT do

- Does NOT implement fixes (use `sentry-fix` skill)
- Does NOT process multiple issues per run

---
name: sentry-fix
description: Implement a fix for a triaged Sentry issue and create a PR. Use when given a Linear issue ID to fix.
---

# Sentry Fix

Implement a fix for a triaged Sentry issue and create a PR.

**Input**: Linear issue ID (e.g., `AGENT-1646`)
**Output**: PR URL, or explanation why fix was not attempted

## Workflow

1. **Get issue context** - Fetch Linear issue, extract Sentry link and fix assessment
2. **Validate** - Confirm root cause documented, fix location identified, change is mechanical
3. **Implement** - Read target file, apply fix following codebase patterns
4. **Create PR** - Use `create-pr` skill, include `Fixes ALL-REPORTS-XXX` for Sentry auto-resolution

## Philosophy

- **Safe by default** - Stop if uncertain, let humans decide
- **Never hide bugs** - Only change log levels for truly expected conditions
- **Clear audit trail** - PR references Linear, Linear links to Sentry
The agent discovers available skills at conversation start and loads them when relevant.

​
Next steps