Concepts

Skills

A skill is a packaged, reusable playbook: instructions that tell an agent how to do something well, plus optional scripts it can run. Skills carry know-how — never credentials, and never access.

The definition: SKILL.md

---
name: schedule-meeting
description: Find a slot that works and book it, without double-booking.
allowed_tools:              # must be a SUBSET of the agent's tools
  - calendar
  - current_time
entrypoints:                # scripts that may run in the sandbox
  check: scripts/check_conflicts.py
---

# Procedure
1. Use `current_time` to resolve relative dates ("next Tuesday") into an
   absolute range in the user's timezone.
2. Call `calendar` with `op: find_free_time` over that range.
3. Propose the slot to the user and wait for confirmation.
4. Only then call `calendar` with `op: create_event`.

## Conventions
- Never book over an existing event, even a tentative one.
- Default to 30 minutes unless the user says otherwise.

A skill cannot widen access allowed_tools is checked against what the agent grants. If a skill lists a tool the agent doesn't have, the skill's script is refused rather than silently escalating. Skills package procedure; agents package permission.

Progressive disclosure

Skill instructions can be long, and loading every attached skill into every prompt would be wasteful. Instead the agent sees a compact index of its skills, and pulls in detail only when it needs it — via load_skill:

Index — name and description of each attached skill, always present.
Body — the full SKILL.md procedure, loaded when the agent decides the skill applies.
Reference — a specific supporting file from the bundle, loaded on demand by path.

Skills that run code

A skill can ship a bundle of files, including scripts. Declared entrypoints run through run_skill_script in the same isolated sandbox as code_execution: no network, capped memory/CPU/time, non-root, and files written to the output directory come back as run artifacts.

Two gates apply before a script runs:

The path must be a declared entrypoint — an arbitrary file in the bundle can't be executed.
The skill's allowed_tools must be a subset of the agent's tools.

Versions and pinning

Like agents, skill versions are immutable with a pointer to the current one, and every version is scanned. How an agent references a skill matters:

Reference	Resolves to	Use when
`schedule-meeting`	Whatever is current — it floats.	You want improvements to flow through automatically.
`schedule-meeting@3`	Exactly version 3, forever.	You need stability against upstream edits.

When an agent is promoted to a shared ring, its skill references are frozen on the promoted copy. The shared agent can't change underneath its users just because the author kept editing — while the author's personal original keeps floating.

Authoring a skill

Write it

Create a skill in the app with the editor, upload a bundle, and validate the frontmatter live.

Test it

The test bench runs a declared entrypoint through the real sandbox and shows output and artifacts — without creating a run.

Start from a built-in

Twenty first-party, scan-passing skills ship with the platform and can be installed into your org.

Let an agent propose one

An agent can distil a repeated procedure into a proposal with propose_skill. It becomes a real skill only after a human applies it.

The Skill Workshop

Agents notice repetition. When one does, it can call propose_skill to draft a playbook into the workshop for review. The proposal can be revised conversationally, then applied — which validates it and creates a real skill in the proposer's personal ring (triggering a scan) — or rejected with a reason. There is no other path from a proposal to a live skill.

Skill vs. agent instructions

	Agent body	Skill
Scope	Who this agent is, always in context	How to do one task, loaded on demand
Reuse	Belongs to one agent	Shared across many agents
Can ship code	No	Yes — sandboxed entrypoints
Versioned separately	With the agent	Independently, with optional pinning

Rule of thumb: if two agents would benefit from the same procedure, or the procedure is long enough that it shouldn't sit in every prompt, make it a skill.