> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable Agent Skills — packaged instructions plus scripts, references, and assets that an agent loads and runs in its sandbox.

## What is a Skill?

A **Skill** is a reusable capability package: a folder containing a `SKILL.md` file plus any scripts, reference documents, and assets the skill needs. Skills follow the [Agent Skills](https://www.anthropic.com/news/skills) open standard, so a skill authored for one compliant runtime can be imported into Orca.

When a skill is attached to an agent, its instructions and resources become available to that agent during a run. Skills that ship executable scripts or shell steps run inside the agent's **[sandbox](/concepts/sandboxes)** — an isolated per-agent compute environment — rather than in the conductor process.

<Info>
  Skills are the packaging format for *capabilities* (instructions + code + references). To connect an agent to an external SaaS tool instead, see **[Connected Apps](/concepts/connected-apps)** and **[MCP Integration](/concepts/mcp-integration)**.
</Info>

## Anatomy of a Skill

| Part           | Purpose                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `SKILL.md`     | The entry point — describes what the skill does and how the agent should use it.                                 |
| Metadata       | Name, description, and tags used for discovery in the catalog.                                                   |
| Resource files | Scripts, reference docs, and assets, each addressed by its path within the skill.                                |
| Usage tracking | Orca records which agents currently use a skill, so you can see its blast radius before changing or removing it. |

Resource files are readable and writable through the API by path:

```bash theme={null}
# Read a resource file inside a skill
curl https://api.orcapods.ai/api/skills/pdf-toolkit/resources/scripts/extract.py \
  -H "Authorization: Bearer ao_..."
```

## Catalogs: tenant and platform

Orca maintains two catalogs:

* **Tenant catalog** — skills your organization has imported or created. Managed under **[Skills](/dashboard/skills)** in the dashboard, or via `GET /api/skills`.
* **Platform catalog** — a curated, platform-level set of skills that Orca ships and maintains. These are available to every tenant as a starting point.

## Importing a Skill (two-phase)

Importing a skill package is a deliberate two-phase flow so nothing lands in your catalog until you have seen exactly what it will do.

<Steps>
  <Step title="Dry-run validation">
    Submit the package to `POST /api/skills/import-package`. Orca validates it
    against the Agent Skills open standard and returns a report that flags:

    * whether the skill **requires a sandbox** (because it runs scripts), and
    * any **name collisions** with skills already in your catalog.

    Nothing is written yet — this is a preview.
  </Step>

  <Step title="Commit">
    If the report looks right, confirm with
    `POST /api/skills/import-package/commit` to write the skill into your
    tenant catalog.
  </Step>
</Steps>

<Note>
  The dashboard runs this same two-phase flow for you when you upload a skill — you review the validation summary, then click through to commit.
</Note>

## Attaching a Skill to an agent

Skills are attached per-agent (per [profile](/concepts/profiles)):

<CodeGroup>
  ```bash Attach theme={null}
  curl -X POST https://api.orcapods.ai/api/profiles/support-bot/skills/pdf-toolkit \
    -H "Authorization: Bearer ao_..."
  ```

  ```bash Detach theme={null}
  curl -X DELETE https://api.orcapods.ai/api/profiles/support-bot/skills/pdf-toolkit \
    -H "Authorization: Bearer ao_..."
  ```
</CodeGroup>

<Warning>
  A skill that runs scripts or shell tools needs the agent to have a **sandbox enabled** on its profile. Attaching such a skill to an agent with no sandbox will leave those steps unable to execute — configure a sandbox first. See **[Sandboxes](/concepts/sandboxes)**.
</Warning>

## Next

<CardGroup cols={3}>
  <Card title="Manage skills in the UI" icon="grid-2" href="/dashboard/skills">
    Import, browse, and attach skills from the dashboard.
  </Card>

  <Card title="Sandboxes" icon="box" href="/concepts/sandboxes">
    The compute environment where skill scripts run.
  </Card>

  <Card title="Profiles" icon="id-card" href="/concepts/profiles">
    Where skills are attached to an agent.
  </Card>
</CardGroup>