> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Teach agents to follow your workflows automatically.

Skills are `SKILL.md` files containing step-by-step workflow instructions. They teach agents 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](https://app.ona.com/settings/agent-skills) | Shipped with the 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

```markdown theme={null}
---
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:

> [accordion] create-pr
>
> ```markdown theme={null}
> ---
> 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
> ```

> [accordion] go-tests
>
> ```markdown theme={null}
> ---
> 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`
> ```

> [accordion] linear-ticket
>
> Requires [Linear integration](https://ona.com/docs/ona/integrations/configure-linear.md).
>
> ```markdown theme={null}
> ---
> 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
> ```

> [accordion] sentry-triage
>
> ```markdown theme={null}
> ---
> 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
> ```

> [accordion] sentry-fix
>
> ```markdown theme={null}
> ---
> 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.

1. Create a directory in `.ona/skills/`:

```bash theme={null}
mkdir -p .ona/skills/create-pr
```

2. Create a `SKILL.md` file:

```markdown theme={null}
---
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
```

3. Commit to your repository:

```bash theme={null}
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 agents discover skills

At session start, the agent collects skills from three sources:

1. **Repository skills** in `.ona/skills/`, `.claude/skills/`, or `.agents/skills/` of the current repo
2. **Organization skills** configured for your Ona organization
3. **Built-in skills** that ship with the 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 the 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 the 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 the agent what not to do. This prevents common mistakes.

### Reference, don't duplicate

```markdown theme={null}
## Database migrations
See [migrations guide](./docs/migrations.md) for the full process.
```

## Next steps

* [AGENTS.md](https://ona.com/docs/ona/agents-md.md): general codebase context
* [Organization skills](https://ona.com/docs/ona/skills.md): team-wide reusable prompts with optional slash commands
* [Automations](https://ona.com/docs/ona/automations/overview.md): run workflows automatically

## Troubleshooting

> [accordion] The 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/`)

> [accordion] 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.