Skip to main content
Skills teach Ona Agent to follow specific workflows automatically. When a task matches a skill’s description, Ona Agent reads and follows those instructions.

​
What are skills?

Skills are SKILL.md files containing step-by-step workflow instructions. They enable you to teach Ona Agent best practices for specific workflows that matter to you—creating PRs, deploying to staging, writing tests in a particular style.
FeatureSkillsAGENTS.mdSlash commands
PurposeTask-specific workflowsGeneral codebase contextManual prompt shortcuts
DiscoveryAutomatic by descriptionAlways loadedUser invokes with /
ScopeRepositoryRepositoryOrganization
Best forMulti-step processesProject conventionsReusable prompts

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

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

​
Create a skill

Skills live in your repository.
  1. Create a directory in .ona/skills/:
mkdir -p .ona/skills/create-pr
  1. 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
  1. 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 (must match 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 conversation start, Ona Agent scans .ona/skills/ in your repository and lists available skills by description. Full content is loaded on-demand via read_skill when a task matches.

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

​
Troubleshooting

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
Check path: Ensure the file is at .ona/skills/<name>/SKILL.mdCheck frontmatter: Ensure YAML is valid with required name and description fields

​
Next steps