Agent Skills
Agent Skills are portable instruction packages following the Agent Skills 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
Three-stage disclosure
- Discovery (~100 tokens per skill): names and descriptions appear in the system prompt under
<available_skills>. - Activation (under 5,000 tokens): full SKILL.md instructions load when the agent calls
activate_skill. - 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 | 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 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: author a SKILL.md, bundle scripts, and share it through the registry.
See also
- Agent Skills capability reference: tools, dependencies, config.
- SKILL.md format spec: upstream open spec.