# Agent Skills

> Portable instruction packages following the agentskills.io open spec, from the session workspace or the organization-wide Skills Registry, loaded on demand.

Source: <https://everruns.com/docs/features/skills/>

**Agent Skills** are portable instruction packages following the [Agent Skills](https://agentskills.io/) open specification. They keep the agent’s context efficient through *progressive disclosure*: the agent sees only short names and descriptions until it activates a skill, at which point the full instructions and bundled resources load.

## Overview video

[Agent Skills Overview](https://www.youtube.com/embed/mNqXP4NA_8U)

## Three-stage disclosure

1. **Discovery** (\~100 tokens per skill): names and descriptions appear in the system prompt under `<available_skills>`.
2. **Activation** (under 5,000 tokens): full SKILL.md instructions load when the agent calls `activate_skill`.
3. **Resources**: bundled files mount at `/workspace/.agents/skills/{name}/` and are read with the normal filesystem tools.

This keeps thousands of skills available to an agent without burning context on the ones it doesn’t need.

## Two ways to use skills

| Source           | Where they live                                               | When to use                                          |
| ---------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
| Workspace skills | `/.agents/skills/` in the session VFS                         | Project-specific skills; per-session experimentation |
| Registry skills  | Organization-wide, in the [Skills Registry](#skills-registry) | Shared across agents; managed via API                |

The built-in `skills` capability handles discovery and activation for both. Registry skills appear in the capability system as virtual capabilities (`skill:{uuid}`) that mount the skill into `/.agents/skills/{name}/`, where the `skills` capability finds it alongside workspace skills.

## Skills Registry

The **Skills Registry** stores skills at the organization level. Registry skills persist across sessions and can be assigned to any agent like any other capability, with ID `skill:{uuid}`. The organization must have the `skills` feature enabled.

### API surface

| Method | Path                      | Description                                  |
| ------ | ------------------------- | -------------------------------------------- |
| POST   | `/v1/skills`              | Create from SKILL.md                         |
| POST   | `/v1/skills/upload`       | Create from ZIP archive                      |
| GET    | `/v1/skills`              | List                                         |
| GET    | `/v1/skills/usage`        | How many agents and harnesses use each skill |
| GET    | `/v1/skills/{id}`         | Get metadata                                 |
| GET    | `/v1/skills/{id}/content` | Get full content                             |
| PATCH  | `/v1/skills/{id}`         | Update                                       |
| DELETE | `/v1/skills/{id}`         | Delete                                       |
| POST   | `/v1/skills/validate`     | Validate without creating                    |

See the [API reference](https://everruns.com/docs/api/) for request and response schemas.

### ID formats

| Source    | ID                                   | Example                                      |
| --------- | ------------------------------------ | -------------------------------------------- |
| Registry  | `skill:{uuid}`                       | `skill:550e8400-e29b-41d4-a716-446655440000` |
| Workspace | Aggregated under `skills` capability | –                                            |

### Dependencies

Registry skills automatically depend on `session_file_system` so bundled resources can be read after activation. You don’t need to add it explicitly.

### Security

* Archive uploads are validated against path traversal, ZIP bombs, and size limits.
* Skill instructions are returned as tool results, not injected into the system prompt, so they cannot bypass capability isolation.
* Skill names are unique per organization.
* Disabled skills are hidden from listings.

## Do something

* [Package and publish an agent skill](https://everruns.com/docs/how-to/package-a-skill/): author a SKILL.md, bundle scripts, and share it through the registry.

## See also

* [Agent Skills capability reference](https://everruns.com/docs/capabilities/agent-skills/): tools, dependencies, config.
* [SKILL.md format spec](https://agentskills.io/): upstream open spec.