> ## 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 Ona Agent to follow your workflows automatically. 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//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 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 ```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: ```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** - `/` (max 24 chars) 5. **Commit** - use Conventional Commits 6. **Push** - `git push -u origin ` 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 ``` ```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` ``` Requires [Linear integration](/ona/integrations/configure-linear). ```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 ``` ```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 ``` ```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 Ona Agent discovers skills At session start, Ona 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 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 ```markdown theme={null} ## Database migrations See [migrations guide](./docs/migrations.md) for the full process. ``` ## Next steps * [AGENTS.md](/ona/agents-md): general codebase context * [Organization skills](/ona/skills): team-wide reusable prompts with optional slash commands * [Automations](/ona/automations/overview): run workflows automatically ## Troubleshooting **Check the description**: Be specific about when to use it and include trigger words. **Check the path**: Skills must be in `.ona/skills//SKILL.md` (or `.claude/skills/` or `.agents/skills/`) **Check path**: Ensure the file is at `.ona/skills//SKILL.md` (or `.claude/skills/` or `.agents/skills/`) **Check frontmatter**: Ensure YAML is valid with required `name` and `description` fields