Skills

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

The definition: SKILL.md

A skill is a bundle: SKILL.md at the root, and any scripts and reference files beside it. The frontmatter declares what the skill is and what it may run; the body is the procedure the agent reads.

---
name: csv-cleaner
description: Normalise messy CSV data deterministically and report every change.
tags: [data, utility]
version: 1
allowed_tools: []              # must be a SUBSET of the agent's tools
entrypoints:                   # scripts that may run in the sandbox
  - path: scripts/clean.py
    runtime: python3.12
    examples:
      - name: basic
        args: ["input.csv", "--dedupe"]
        description: Trim, dedupe and coerce types.
---

# csv-cleaner

## When to use
The agent has a CSV file whose headers, types or duplicates are inconsistent
and needs a clean copy plus a report of what changed.

## How input reaches the script
The sandbox has no network and cannot read conversation attachments. All input
arrives as command-line arguments (argv). Write any files you want to return
under /out.

## Procedure
1. Run `scripts/clean.py` with the file path and the flags the user asked for.
2. Return the cleaned file and summarise the change report.

Authoring a skill in the app

Catalog → Skills → New skill opens the skill editor. You author the bundle in place: SKILL.md and its scripts as files in the panel on the left, a Monaco editor for whichever file is selected, and live frontmatter validation on the right. Or switch to Upload .zip bundle and upload a zip with SKILL.md at its root plus a scripts/ folder.

• Workspace. The destination is a visible field, "My Personal workspace (default)" until you change it. Members author in their personal ring; a skill reaches a shared ring through promotion.
• Bundle files. The starter bundle is SKILL.md plus scripts/run.py; add files with Add file and remove them from the list. The declared entrypoints appear as chips above the editor.
• Validation. The frontmatter is parsed as you type. On Save skill the files are zipped and uploaded as a bundle, then validated and scanned. Every declared entrypoint must have a matching file, and allowed_tools must be a subset of the attaching agent's tools.
• The starter script. scripts/run.py reads its arguments from argv, writes anything it wants to return under /out, and prints a one-line summary. That is the whole contract with the sandbox: no network, no access to conversation attachments, files in /out come back as run artifacts.

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, through load_skill:

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

Skills that run code

Declared entrypoints run through run_skill_script in the same isolated sandbox as code_execution: no network, capped memory, CPU and wall-clock time, a non-root user, package managers removed, and numpy, pandas, matplotlib and pillow available. Files written to /out come back as run artifacts, downloadable from the conversation and from Observe.

Two gates apply before a script runs:

• The path must be a declared entrypoint; an arbitrary file in the bundle cannot be executed.
• The skill's allowed_tools must be a subset of the agent's tools.

The skill page

Every skill has a page in the catalog with five parts:

The catalog

Catalog → Skills lists every skill you can see, filtered by ring (personal, team, org, public) and searchable semantically, so "make a chart from JSON" finds basic-chart-builder without knowing its name. Each card shows the ring, a scan badge and whether it is new.

Install built-in skills seeds the thirteen first-party skills that ship with the platform into your org ring, all scan-passed: among them basic-chart-builder, csv-cleaner, data-profiler, ics-scheduler, pdf-report and web-summarize, plus the research method and playbooks. They are ordinary skills once installed: attach them, pin them, read their bundles, and use them as a starting point for your own. Each one is documented under Built-in skills.

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:

When an agent is promoted to a shared ring, its skill references are frozen on the promoted copy. The shared agent cannot change underneath its users just because the author kept editing, while the author's personal original keeps floating. Promoting a whole workspace freezes the pins of every agent inside it the same way.

Who can build skills

Every member can create skills in their personal ring and edit what they authored there. Builders and team admins can edit what they authored at any altitude, and an org admin can edit anything. The skill page hides the controls you cannot use rather than refusing them. A skill reaches the team or org ring only through promotion, which runs the scan gate first; a version that has not passed its scan cannot be published to a shared ring.

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, and the proposal records which run it came from.

Skill vs. agent instructions

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