Skills - Ona Documentation

Skills are step-by-step workflow instructions that agents discover and use automatically. Unlike AGENTS.md (which provides general context) or slash commands (which you invoke manually), skills are task-specific workflows that agents read on-demand when they match the task at hand.

Why skills matter

Your team has proven workflows - how to create a pull request, deploy to production, or debug a specific type of issue. Skills codify these workflows so agents can follow them consistently. Without skills: Agents improvise each time, potentially missing steps or using inconsistent approaches. With skills: Agents discover the right workflow for the task and follow your proven process.

Skills vs AGENTS.md vs slash commands

Feature	Skills	AGENTS.md	Slash commands
Purpose	Task-specific workflows	General codebase context	Manual prompt shortcuts
Discovery	Automatic by description	Always loaded	User invokes with `/`
Scope	Workspace or organization	Workspace only	Organization only
Content loading	On-demand via `read_skill`	Loaded at conversation start	Loaded when invoked
Best for	Multi-step processes	Project conventions	Reusable prompts

Example use cases:

Skill: “Create pull request” - step-by-step workflow for opening PRs following repo conventions
AGENTS.md: Project structure, test commands, branch naming patterns
Slash command: /review-like-mads - apply a specific review philosophy

Workspace-level skills

Workspace skills live in your repository and are available to anyone working in that codebase.

Create a workspace skill

Create a directory in .ona/skills/ (or .claude/skills/) with your skill name:

mkdir -p .ona/skills/create-pr

Create a SKILL.md file with frontmatter and workflow instructions:

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

# Create Pull Request

Use this workflow when creating a pull request.

## Prerequisites
- Changes are committed to a feature branch
- Tests pass locally
- Code follows project style guide

## Workflow

1. **Verify branch name**
   - Format: `initials/short-description`
   - Example: `jd/fix-auth-bug`
   - If incorrect, rename: `git branch -m old-name new-name`

2. **Run pre-PR checks**
   ```bash
   npm run typecheck
   npm test
   npm run lint

Create PR with template
- Title: Start with issue number if applicable
- Description: Include “What changed” and “Why”
- Link related issues
- Add screenshots for UI changes
Request reviewers
- Add at least one reviewer from CODEOWNERS
- Tag security team for auth/permissions changes

Anti-patterns

Don’t create PRs with failing tests
Don’t skip the PR template
Don’t merge without approval

3. Commit the skill to your repository:

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

SKILL.md format

Skills use YAML frontmatter followed by markdown content:

---
name: skill-name
description: When to use this skill (shown to agent during discovery)
---

# Skill Title

Workflow instructions in markdown...

Required fields:

name: Unique identifier (must match directory name)
description: When agents should use this skill

Content structure:

Prerequisites
Step-by-step workflow
Examples
Anti-patterns (what to avoid)

Directory structure

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

Agents discover all skills in .ona/skills/ and .claude/skills/ directories.

Organization-level skills

Organization skills are stored in the management plane and available across all environments in your organization. They take precedence over workspace skills with the same name.

Create an organization skill

Use the CLI to create organization skills:

ona ai skill create \
  --name create-pr \
  --description "Create pull requests following organization standards" \
  --file ./create-pr-workflow.md

Or provide content inline:

ona ai skill create \
  --name create-pr \
  --description "Create pull requests following organization standards" \
  --content "# Create PR

## Workflow
1. Run tests
2. Create PR with template
3. Request reviewers"

Manage organization skills

List all skills:

ona ai skill list

Get a specific skill:

ona ai skill get create-pr

Update a skill:

ona ai skill update create-pr \
  --description "Updated description" \
  --file ./updated-workflow.md

Delete a skill:

ona ai skill delete create-pr

Import from workspace:

ona ai skill import ./.ona/skills/create-pr/SKILL.md

This reads the workspace skill file and creates an organization skill with the same content.

How agents use skills

Discovery

When an agent conversation starts, it discovers all available skills:

Fetches organization-level skills via API
Scans workspace directories (.ona/skills/, .claude/skills/)
Merges skills (organization skills override workspace skills with same name)
Lists skills in system prompt with descriptions

The agent sees:

## Skills

Available skills discovered from organization and workspace.
Content not inlined to keep context lean.

- create-pr: Create pull requests following repository conventions (organization)
- debug-performance: Debug performance issues in production (file: .ona/skills/debug-performance/SKILL.md)
- deploy-staging: Deploy to staging environment (file: .ona/skills/deploy-staging/SKILL.md)

### Usage Instructions
1. When a task matches a skill's description, use the read_skill tool to get its content
2. Read only enough to follow the workflow
3. Load referenced files only as needed; don't bulk-load
4. Prefer running scripts/ over retyping code

Reading skill content

Agents use the read_skill tool to fetch workflow instructions on-demand:

{
  "tool_name": "read_skill",
  "arguments": {
    "skill_name": "create-pr"
  }
}

This returns the full skill content. Agents read skills only when needed, keeping context lean.

Precedence rules

When skills have the same name:

Organization skills take precedence over workspace skills
.ona/skills/ takes precedence over .claude/skills/

Example:

Organization has create-pr skill → Agent uses organization version
Workspace has create-pr in .ona/skills/ → Ignored (org wins)
Workspace has debug-perf in .ona/skills/ → Agent uses workspace version (no org conflict)

Best practices

Keep skills focused: One skill per workflow. Don’t create a mega-skill that covers everything. Write clear descriptions: The description determines when agents use the skill. Be specific:

✅ “Create pull requests following repository conventions”
❌ “PR stuff”

Include anti-patterns: Tell agents what NOT to do. This prevents common mistakes. Reference, don’t duplicate: Link to existing scripts or documentation rather than copying content:

## Deployment

Run the deployment script:
```bash
./scripts/deploy-staging.sh

See deployment docs for troubleshooting.

**Test in workspace first**: Create workspace skills and validate them before promoting to organization level.

**Use organization skills for standards**: Workflows that should be consistent across all repositories (security reviews, deployment processes) belong at organization level.

## Example: Create PR skill

```markdown
---
name: create-pr
description: Create pull requests following repository conventions and security requirements
---

# Create Pull Request

## Prerequisites
- Feature branch created from `main`
- All tests passing
- No merge conflicts

## Workflow

### 1. Pre-flight checks
```bash
# Run full test suite
npm test

# Type checking
npm run typecheck

# Security scan
npm run security-check

All must pass before proceeding.

2. Branch naming

Format: <initials>/<issue-number>-<short-description> Examples:

jd/123-fix-auth-bug
sm/456-add-export-feature

If branch name is incorrect:

git branch -m old-name new-name
git push origin -u new-name
git push origin --delete old-name

3. Commit message format

<type>(<scope>): <subject>

<body>

Fixes #<issue-number>

Types: feat, fix, docs, refactor, test, chore

4. Create PR

Title: [#<issue>] <description>
Description: Use PR template (.github/pull_request_template.md)
Labels: Add appropriate labels
Reviewers: Minimum 1 from CODEOWNERS
Security: Tag @security-team for auth/permissions changes

5. Post-creation

Link PR to Linear/Jira issue
Notify in #engineering Slack channel
Monitor CI checks

Anti-patterns

❌ Creating PR with failing tests
❌ Skipping security scan for “small changes”
❌ Merging without approval
❌ Force-pushing after review started
❌ Leaving PR description empty

Troubleshooting

Tests fail in CI but pass locally:

Check Node version matches CI
Clear node_modules and reinstall
Verify environment variables

Merge conflicts:

git fetch origin main
git rebase origin/main
# Resolve conflicts
git rebase --continue

## Example: Deploy staging skill

```markdown
---
name: deploy-staging
description: Deploy application to staging environment with proper validation
---

# Deploy to Staging

## Prerequisites
- PR merged to `main`
- All CI checks passing
- Staging environment healthy

## Workflow

### 1. Verify staging health
```bash
./scripts/check-staging-health.sh

Must return “healthy” before proceeding.

2. Create deployment branch

git checkout main
git pull origin main
git checkout -b deploy/staging-$(date +%Y%m%d-%H%M%S)

3. Run deployment

./scripts/deploy-staging.sh

This script:

Builds production assets
Runs database migrations
Deploys to staging cluster
Runs smoke tests

4. Verify deployment

# Check deployment status
kubectl get pods -n staging

# Run integration tests
npm run test:integration:staging

# Manual verification
open https://staging.example.com

5. Notify team

Post in #deployments Slack channel:

Deployed to staging: <commit-sha>
Changes: <brief-summary>
Verification: <test-results>

Rollback procedure

If deployment fails:

./scripts/rollback-staging.sh

Anti-patterns

❌ Deploying without health check
❌ Skipping smoke tests
❌ Deploying during business hours without notice
❌ Not verifying database migrations

## Migrating workspace skills to organization

To promote a workspace skill to organization level:

```bash
# Import from workspace file
ona ai skill import ./.ona/skills/create-pr/SKILL.md

# Or create from scratch
ona ai skill create \
  --name create-pr \
  --description "Create PRs following org standards" \
  --file ./.ona/skills/create-pr/SKILL.md

After creating the organization skill, you can remove the workspace version to avoid confusion.

Troubleshooting

Agent doesn't use my skill

Check the description: The skill description must match the task. Be specific about when to use it.Verify discovery: Organization skills appear with “(organization)” indicator, workspace skills show file path.Check precedence: If you have both org and workspace skills with the same name, only the org skill is used.

Skill content not loading

Organization skills: Verify the skill exists with ona ai skill listWorkspace skills: Check file path is .ona/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.mdFrontmatter: Ensure YAML frontmatter is valid and includes required name and description fields

How to update organization skills

Use the CLI update command:

ona ai skill update <skill-name> \
  --description "Updated description" \
  --file ./updated-content.md

Or delete and recreate:

ona ai skill delete <skill-name>
ona ai skill create --name <skill-name> --description "..." --file ./content.md

Next steps

AGENTS.md - provide general codebase context
Slash commands - create manual prompt shortcuts
Automations - run agent workflows automatically

Get Started

Environments

Agents

Automations

Runners

Security & Compliance

Organizations

Projects

Integrations

Source Control

Editors & IDEs

​Why skills matter

​Skills vs AGENTS.md vs slash commands

​Workspace-level skills

​Create a workspace skill

​Anti-patterns

​SKILL.md format

​Directory structure

​Organization-level skills

​Create an organization skill

​Manage organization skills

​How agents use skills

​Discovery

​Reading skill content

​Precedence rules

​Best practices

​2. Branch naming

​3. Commit message format

​4. Create PR

​5. Post-creation

​Anti-patterns

​Troubleshooting

​2. Create deployment branch

​3. Run deployment

​4. Verify deployment

​5. Notify team

​Rollback procedure

​Anti-patterns

​Troubleshooting

​Next steps

Why skills matter

Skills vs AGENTS.md vs slash commands

Workspace-level skills

Create a workspace skill

Anti-patterns

SKILL.md format

Directory structure

Organization-level skills

Create an organization skill

Manage organization skills

How agents use skills

Discovery

Reading skill content

Precedence rules

Best practices

2. Branch naming

3. Commit message format

4. Create PR

5. Post-creation

Anti-patterns

Troubleshooting

2. Create deployment branch

3. Run deployment

4. Verify deployment

5. Notify team

Rollback procedure

Anti-patterns

Troubleshooting

Next steps