Skills

Skills are SKILL.md files containing step-by-step workflow instructions. They teach Ona Agent to follow specific workflows, such as creating PRs, deploying to staging, or writing tests in a particular style. When a task matches a skill’s description, the agent reads and follows those instructions. Skills come from three places, plus AGENTS.md for general codebase context:

Feature	Repository skills	Organization skills	Built-in skills	AGENTS.md
Where they live	`.ona/skills/<name>/SKILL.md` (also `.claude/skills/` and `.agents/skills/`) in the repo	Configured in Settings → Agents → Skills	Shipped with Ona Agent	`AGENTS.md` in the repo
Scope	Repository	Whole organization	All users	Repository
Discovery	Automatic by description	Automatic by agent, or user invokes with `/`	Automatic by description	Always loaded
Best for	Codebase-specific workflows	Team-wide reusable prompts and slash commands	Common workflows like `browse-web`, `ona-docs`, `devcontainer-setup`, `skill-creator`	Project conventions and general context

When two sources publish a skill with the same name, repository skills win over organization skills, which win over built-in skills. This lets a repo customize a team-wide workflow, or a team override a built-in one.

Skill structure

---
name: skill-name
description: What this skill does and when to use it
---

# Skill Title

## Steps
1. **Step one** - Clear instruction
2. **Step two** - Include commands where helpful

## Anti-patterns
- What NOT to do

Here are some skills the Ona engineering team uses:

create-pr

---
name: create-pr
description: Create pull requests following repository conventions. Use when asked to create a PR, open a PR, 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)
5. **Commit** - use Conventional Commits
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 commit unrelated changes
- Don't push to main directly

go-tests

---
name: go-tests
description: Generates Go unit tests using the Expectation pattern with cmp.Diff. Use when writing or fixing Go tests.
---

# Go Tests

Table-driven tests using the Expectation pattern with `cmp.Diff`.

## Rules

1. **Always use `t.Parallel()`** at test function and subtest level
2. **Never use `t.Parallel()` with `t.Setenv()`** - they panic together
3. **Single `cmp.Diff` assertion** comparing entire Expectation struct
4. **Capture errors as strings** in `Expectation.Err`, not with `t.Fatal`
5. **Never use testify** - use `cmp.Diff` only

## Anti-Patterns

- `t.Fatal` for action errors → use `Expectation.Err`
- `context.Background()` → use `t.Context()`
- `testify/assert` → use `cmp.Diff`

linear-ticket

Requires Linear integration.

---
name: linear-ticket
description: Create Linear tickets from code analysis. Use when asked to create a ticket, file an issue, or track work in Linear.
---

# Create Linear Ticket

Create a well-structured Linear ticket from the current context.

## Steps

1. **Gather context** - Understand what needs to be tracked (bug, feature, task)
2. **Check for duplicates** - Search Linear for existing tickets on the same topic
3. **Create ticket** - Use appropriate team, labels, and priority
4. **Link resources** - Attach relevant PRs, files, or documentation

## Ticket format

- **Title**: Clear, actionable (`Fix auth timeout on slow connections`)
- **Description**: Include reproduction steps for bugs, acceptance criteria for features
- **Labels**: Add relevant labels (bug, feature, tech-debt)

## Anti-patterns

- Don't create duplicate tickets
- Don't leave description empty
- Don't assign without checking availability

sentry-triage

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

## Steps

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

sentry-fix

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

## Steps

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 Sentry issue ID for auto-resolution

## Anti-patterns

- Never hide bugs by changing log levels for genuinely unexpected conditions
- Stop if uncertain — let humans decide

Create a skill

Skills live in your repository.

Create a directory in .ona/skills/:

mkdir -p .ona/skills/create-pr

Create a SKILL.md file:

---
name: create-pr
description: Create pull requests following repository conventions
---

# Create Pull Request

## Steps
1. **Run checks**: `npm test && npm run lint`
2. **Create branch**: `initials/short-description`
3. **Create PR**: Use template, link issues

## Anti-patterns
- PRs with failing tests
- Skipping the PR template

Commit to your repository:

git add .ona/skills/create-pr/
git commit -m "Add create-pr skill"

Directory structure

.ona/skills/
├── create-pr/
│   └── SKILL.md
├── deploy-staging/
│   └── SKILL.md
└── debug-performance/
    └── SKILL.md

SKILL.md format

Required fields:

name: Unique identifier. If omitted, defaults to the directory name
description: When to use this skill. Be specific and include trigger words

Naming conventions:

Lowercase letters, numbers, and hyphens
Maximum 64 characters
Avoid vague names: helper, utils, tools

How Ona Agent discovers skills

At session start, Ona Agent collects skills from three sources:

Repository skills in .ona/skills/, .claude/skills/, or .agents/skills/ of the current repo
Organization skills configured for your Ona organization
Built-in skills that ship with Ona Agent

Each source contributes a list of skills (name + description). Full skill content is loaded on demand via read_skill when a task matches a skill’s description. When two sources publish a skill with the same name, repository skills win over organization skills, and organization skills win over built-in skills.

Best practices

Write specific descriptions

The description determines when Ona Agent uses the skill:

✅ “Create pull requests following repository conventions. Use when asked to create a PR, open a PR, or land changes.”
❌ “PR stuff”

Design for stability

Use concepts that remain valid despite refactoring
Let Ona Agent rediscover current code state rather than hardcoding paths
If tools can’t do something, drop it

Keep skills focused

One skill per workflow. Keep SKILL.md under 500 lines. Move reference material to separate files.

Include anti-patterns

Tell Ona Agent what NOT to do. This prevents common mistakes.

Reference, don’t duplicate

## Database migrations
See [migrations guide](./docs/migrations.md) for the full process.

Next steps

AGENTS.md: general codebase context
Organization skills: team-wide reusable prompts with optional slash commands
Automations: run workflows automatically

Troubleshooting

Ona Agent doesn't use my skill

Check the description: Be specific about when to use it and include trigger words.Check the path: Skills must be in .ona/skills/<name>/SKILL.md (or .claude/skills/ or .agents/skills/)

Skill content not loading

Check path: Ensure the file is at .ona/skills/<name>/SKILL.md (or .claude/skills/ or .agents/skills/)Check frontmatter: Ensure YAML is valid with required name and description fields

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Skill structure

Create a skill

Directory structure

SKILL.md format

How Ona Agent discovers skills

Best practices

Write specific descriptions

Design for stability

Keep skills focused

Include anti-patterns

Reference, don’t duplicate

Next steps

Troubleshooting

​Skill structure

​Create a skill

​Directory structure

​SKILL.md format

​How Ona Agent discovers skills

​Best practices

​Write specific descriptions

​Design for stability

​Keep skills focused

​Include anti-patterns

​Reference, don’t duplicate

​Next steps

​Troubleshooting

Skill structure

Create a skill

Directory structure

SKILL.md format

How Ona Agent discovers skills

Best practices

Write specific descriptions

Design for stability

Keep skills focused

Include anti-patterns

Reference, don’t duplicate

Next steps

Troubleshooting