Skip to main content

skills/

Skills live at skills/<name>/SKILL.md. They are procedures or reference material loaded on demand, not always-on prompt text. Add a skill when guidance is useful only sometimes, or when the agent should improve by editing skills.

There is no defineSkill — the SKILL.md file is the whole contract:

mkdir -p skills/note-taking
$EDITOR skills/note-taking/SKILL.md

Minimal Example​

---
description: Capture durable notes for the user
allowed-tools: [record_note]
---

# Note Taking

Use this skill when the user shares a fact, preference, or decision that should
outlive the conversation.

Full Options​

Frontmatter is the skill's entire option surface:

KeyType / valuesDefaultEffect
descriptionstringSkill <name>Model-facing summary in the compact skill index; drives skill selection.
allowed-toolsstring[]—Tools the procedure is expected to use.
tagsstring[]—Discovery tags in the capability catalog.
aliasesstring[]—Alternate names for capability lookup.

The body below the frontmatter is the skill's trusted instructions, loaded at the same trust level as instructions.md when the skill is selected.

How Skills Load​

Runs see a compact skill index up front: names, descriptions, aliases, tags, and paths. The full body is loaded only when selected through the model-facing load_skill tool or host-driven loadSkill(runId, skillName) API.

If a sandbox already exists, the selected skill may also be projected into /skills/<name>/SKILL.md for filesystem inspection.

Self-Improvement​

Self-improvement means the agent can author and edit its own skills as it learns procedures. Skills are writable by default (selfImprovement.writable defaults to true); configure it in agent.ts to require approval or turn writing off:

export default defineAgent({
  id: "research-agent",
  model: "openai/gpt-5.4-mini",
  selfImprovement: {
    writable: true,
    writeApproval: false
  }
});

Compiled skills/ seed a durable skill store. Redeploys upgrade pristine seeded skills and preserve skills that the agent or user changed. When selfImprovement.writable is off, /skills writeback is blocked and the skill surface is fully static.

Conventions​

  • Keep skills focused on repeatable procedures.
  • Put durable product data in memory or state, not in skill bodies.
  • Prefer a short description that helps the model choose the skill.
  • Keep allowed-tools aligned with the tools the procedure actually needs.