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:

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

useSkill() selects the compact skill entries available in a capability snapshot. Select load_skill with useTool() when the model should retrieve a selected skill's full body on demand. load_skill cannot load an unselected skill and never widens the snapshot's tool set.

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:

import { defineAgent, useModel, useSkill } from "@assemblyline-agents/core";

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

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.

Related Docs

• Configuration Reference: skills
• Customization: Self-Improvement
• Tools
• instructions.md