Lab 4: Team Essentials - Ona Documentation

You’ve learned how to use Ona as an individual. Now let’s explore features that help teams adopt Ona organization-wide: reusable skills, shared secrets, and safety guardrails.

Organization-level skills

Your best engineers have prompts that work: ways of reviewing code, writing tests, or debugging issues that they’ve refined over time. Skills let you capture that expertise and share it with everyone. Skills are reusable prompts that the agent can discover and use proactively when relevant. They can optionally be made available as slash commands, so users can also invoke them manually by typing / in the chat.

Creating skills requires Admin privileges in your organization. If you’re not an admin, you can skip this section. However, if you see value in creating skills for your team, read through to understand how they work and then ask your organization administrator to create them, or request admin access for yourself.

Why skills matter

Without shared skills, quality varies. One developer’s code review catches security issues; another’s misses them. One person knows how to write tests that actually test behavior; others write tests that only hit coverage targets. With skills:

Expertise scales: A senior engineer’s review checklist becomes available to the whole team
Quality standardizes: Everyone follows the same process
Onboarding accelerates: New team members immediately have access to proven workflows
Agents get smarter: Skills are discoverable by the agent, so it can apply them proactively without being asked

How skills work

Skills are created in the dashboard under Settings > Agents > Skills. Each skill has:

Name: What appears in the skill list (e.g., “Security Review”)
Description: When to use it; helps the agent decide when to apply it proactively
Prompt: The full prompt text
Available as slash command: Optional toggle to let users invoke it with a /trigger

The agent discovers skills automatically and applies them when a task matches. No user action needed. If a skill also has a slash command trigger, users can invoke it manually by typing / in the chat.

Example: Code review skill

A skill that captures one engineer’s review philosophy: Name: Review like Mads Prompt:

You are reviewing code changes. Apply this review philosophy systematically:

## Design System First
- Theme compatibility: Works in light/dark AND old/new themes?
- Semantic tokens: Replace hardcoded colors with `border-subtle`, `surface-glass`
- Visual evidence: Request screenshots/videos if missing

## Aggressive Cleanup
- Remove unused: Components, imports, files, commented code
- Consolidate: Similar components that could be unified

## Technical Excellence
- React patterns: Proper `forwardRef`, `useImperativeHandle`, TypeScript
- Component reuse: Composing existing vs creating new
- Accessibility: ARIA, keyboard nav, screen readers

Priority order: Design system consistency > Code cleanliness > Component reusability > Technical implementation > Test coverage

With the slash command toggle on and trigger set to review-like-mads, anyone can type /review-like-mads to get a review with that level of rigor. The agent can also apply this skill on its own when it detects a code review task.

Try it: Create your first skill

Go to Settings > Agents > Skills
Click New Skill
Configure:
- Name: Code Review
- Description: Review code changes for logic errors, edge cases, and simplification opportunities
- Prompt:
  Review the code I've changed for: - Logic errors - Edge cases I might have missed - Opportunities to simplify Show me specific issues with file names and line numbers.
- Available as slash command: Toggle on
- Command trigger: review
Click Create Skill
In your agent panel, type /review

The agent receives your full prompt. You can also add context after the command:

/review

Focus especially on the authentication changes in src/auth/

Skills to create for your team

Skill	Slash trigger	What it codifies
Pull Request	`/pr`	Create PRs with standardized format
Code Review	`/review`	Code review with your team’s standards
Write Tests	`/test`	Generate tests following your patterns
Fix CI	`/fix-ci`	Debug and fix failing CI builds
Security Review	`/security`	Security audit focused on your stack
Deploy Checklist	`/deploy`	Everything to verify before shipping

Secrets management

Your apps need API keys, database passwords, and tokens. Ona provides secure secret management.

Three levels of secrets

Secrets are configured at three levels, with a strict precedence order when names overlap:

User secrets (highest precedence): Personal credentials like your GitHub token or AWS keys. These override project and organization secrets with the same name.
Project secrets: Shared within a project, such as a staging database password. These override organization secrets with the same name.
Organization secrets (lowest precedence): Available across all projects, such as company-wide API keys.

Types of secrets

Secrets come in different forms depending on what you need to inject:

Environment variables: Key-value pairs injected into your environment (e.g. API_KEY=sk-123...)
Files: Entire files like certificates or config files injected into a path in your environment
Container registry secrets: Authentication credentials for pulling images from private container registries

For full details, see Secrets overview.

Adding secrets

Secrets can be managed in the dashboard or via the CLI. User secrets (personal credentials, available in all your environments):

Click your username at the bottom-left of the Ona dashboard, then click the gear icon to open User Settings
Go to Secrets
Click New Secret
Select Environment Variable as the secret type
Enter a name (e.g. API_KEY) and value
Your next environment will have $API_KEY available

Project secrets (shared with everyone on the project):

Go to Project → Secrets
Click New Secret
Select Environment Variable as the secret type
Enter a name and value. All team members’ environments will have access

Using secrets in code

Secrets appear as environment variables:

// Node.js
const apiKey = process.env.API_KEY

// Python
import os
api_key = os.environ['API_KEY']

// Shell script
echo "Using key: $API_KEY"

Try it: Add and use a secret

Add a test secret in the dashboard:
- Click your username at the bottom-left, then the gear icon to open User Settings
- Go to Secrets and create a new environment variable secret named WORKSHOP_SECRET with value hello-from-ona
Create a new environment (secrets are injected at environment creation)
Verify it’s available:
echo $WORKSHOP_SECRET
Use it in code: Create test-secret.js:
console.log('Secret value:', process.env.WORKSHOP_SECRET)
Run it: node test-secret.js

Secrets are encrypted and only injected into your environments. They never appear in logs or Git.

Security best practices

Do:

Use project secrets for shared credentials
Rotate secrets regularly
Use organization secrets for company-wide keys
Keep production secrets separate from staging

Don’t:

Commit secrets to Git
Share secrets in chat or email
Use the same secret for dev and production
Log secret values in code

Command deny lists (safety)

Prevent Ona Agent from running dangerous commands. This feature is part of Guardrails and requires a Core or Enterprise plan.

Command deny lists only block commands executed by Ona Agent. Users can still run any command directly in the terminal.

Configuring command deny lists requires Admin privileges. If you’re not an admin, you can skip this section. If you believe your team would benefit from deny lists, read through to understand how they work and then ask your organization administrator to set them up, or request admin access.

Why this matters

Without restrictions, an agent might accidentally:

Delete production databases
Force-push over main
Run expensive cloud operations
Publish packages without review

Setting up deny lists

Deny lists are configured by organization admins in the dashboard, not via files in the repository.

Go to Settings → Agents → Policies
Add patterns to the Command Deny List (one per line)
Save. Changes apply to new agent sessions

Pattern matching

Patterns use glob-style wildcards:

Pattern	Effect
`shutdown`	Blocks exactly `shutdown`
`shutdown*`	Blocks `shutdown`, `shutdown -h`, `shutdown now`
`rm *`	Blocks all `rm` commands with arguments
`aws *`	Blocks all AWS CLI commands

Try it: Add a deny list

Have an org admin go to Settings → Agents → Policies

Add these patterns to the Command Deny List:

rm -rf *
git push --force*
git push -f*
npm publish*

Save and start a new agent session
Ask the agent to run git push --force. It will be blocked with an error message

Recommended deny patterns

# Block destructive file operations
rm -rf *

# Block force push
git push --force*
git push -f*

# Block package publishing
npm publish*

# Block cloud provider CLIs
aws *
gcloud *

# Block infrastructure changes
terraform apply*

Adjust for your specific tools and workflows. Start with broad patterns (aws *) rather than listing individual subcommands.

Quick wins checklist

Before finishing this lab, ensure you’ve:

Created at least one organization-level skill your team will use
Added a secret (even a test one) and verified it works
Reviewed the command deny list settings in Settings → Agents → Policies

These practices accelerate team adoption and maintain safety.

Troubleshooting

Skill or slash command not working

Verify the skill exists in Settings > Agents > Skills
If using as a slash command, ensure the Available as slash command toggle is on and a trigger is set
Try typing / in the agent panel to see available commands
Skills are organization-wide; any org member can use them

Secret not available

Restarting an environment picks up updates to existing secrets, but newly added secrets require creating a new environment
Check scope: User secrets only available to you, project secrets to everyone
Verify spelling: $SECRET_NAME is case-sensitive
View loaded secrets: env | grep SECRET

Command deny list not blocking

Deny lists are configured in Settings → Agents → Policies (admin-only)
Changes apply to new agent sessions, so restart your session after updating
Use * wildcards for flexible matching (e.g. rm * not just rm)
Only agent-executed commands are blocked; direct terminal commands are unaffected

What you’ve learned

You now know how to:

Create organization-level skills to share expertise and enable proactive agent behavior
Manage secrets securely at user, project, and organization levels
Configure command deny lists to prevent dangerous agent operations

Your team is now set up to adopt Ona effectively and safely.

Next: Lab 5: Automations at Scale

​Organization-level skills

​Why skills matter

​How skills work

​Example: Code review skill

​Try it: Create your first skill

​Skills to create for your team

​Secrets management

​Three levels of secrets

​Types of secrets

​Adding secrets

​Using secrets in code

​Try it: Add and use a secret

​Security best practices

​Command deny lists (safety)

​Why this matters

​Setting up deny lists

​Pattern matching

​Try it: Add a deny list

​Recommended deny patterns

​Quick wins checklist

​Troubleshooting

​What you’ve learned

Organization-level skills

Why skills matter

How skills work

Example: Code review skill

Try it: Create your first skill

Skills to create for your team

Secrets management

Three levels of secrets

Types of secrets

Adding secrets

Using secrets in code

Try it: Add and use a secret

Security best practices

Command deny lists (safety)

Why this matters

Setting up deny lists

Pattern matching

Try it: Add a deny list

Recommended deny patterns

Quick wins checklist

Troubleshooting

What you’ve learned