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

# Lab 4: Team Essentials

> Scale Ona adoption across your team with skills, secrets, and safety guardrails

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](/ona/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.

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

### 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:**

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

1. Go to [Settings > Agents > Skills](https://app.ona.com/settings/agent-skills)
2. Click **New Skill**
3. Configure:
   * **Name**: Code Review
   * **Description**: Review code changes for logic errors, edge cases, and simplification opportunities
   * **Prompt**:
     ```markdown theme={null}
     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`
4. Click **Create Skill**
5. 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:

1. **User secrets** (highest precedence): Personal credentials like your GitHub token or AWS keys. These override project and organization secrets with the same name.
2. **Project secrets**: Shared within a project, such as a staging database password. These override organization secrets with the same name.
3. **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](/ona/configuration/secrets/overview).

### Adding secrets

Secrets can be managed in the dashboard or via the CLI.

**User secrets** (personal credentials, available in all your environments):

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

**Project secrets** (shared with everyone on the project):

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

### Using secrets in code

Secrets appear as environment variables:

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

1. **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`

2. **Create a new environment** (secrets are injected at environment creation)

3. **Verify it's available**:
   ```bash theme={null}
   echo $WORKSHOP_SECRET
   ```

4. **Use it in code**: Create `test-secret.js`:

   ```javascript theme={null}
   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](/ona/guardrails/overview) and requires a **Core or Enterprise plan**.

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

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

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

1. Go to **Settings → Agents → Policies**
2. Add patterns to the **Command Deny List** (one per line)
3. 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

1. Have an org admin go to **Settings → Agents → Policies**
2. Add these patterns to the Command Deny List:
   ```
   rm -rf *
   git push --force*
   git push -f*
   npm publish*
   ```
3. Save and start a new agent session
4. 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](/workshops/lab-5-automations)