Developer Reference

Ability-Bundled Skills

Updated Jun 5, 2026 · 1 min read

Ability-Bundled Skills

An ability/feature can ship a skill — a how-to playbook — alongside its tools.
When the ability is enabled for an agent, its skill is folded into the agent's
# [SKILLS] catalog automatically: the agent always sees the "when to use it"
line and pulls the full body on demand.

This co-locates the "what" (tools) with the "how" (skill) so they can't
drift apart, and means exploring an ability teaches the agent how to use it.

Declaring one

Add to the feature's the-feature-header:

FEATURE = {
    # ... id, display_name, category, status ...
    "skill_mode": "selectable",          # selectable (load on demand) | always_on
    "skill_handle": "email_a1b2c3d4",    # minted ONCE, frozen — never regenerated
    "skill": "## Using email\n- step one...\n- step two...",
}

Skill identity (collision-proof + stable)

Agent-authored skills stay keyed by name (the save path rejects

duplicate names on an agent — no suffix needed).

Ability skills get a unique handle minted once and frozen

(e.g. email_a1b2c3d4). Random for uniqueness, fixed for stability — a loaded
ability-skill still matches itself across restarts and conversation replay.

The two live in separate id spaces, so they can never collide. The agent loads

its own skills by name and ability skills by handle; the call handle itself
disambiguates.

How it loads

load_skill(<handle>) pulls the body into the conversation (stays active for the
rest of it). list_skills shows both authored and ability skills.

Implementation: app/agent/ability_skills.py, merged in
prompts.append_skills_section, resolved in core_tools.load_skill /
list_skills, rendered by skills.format_skills_section.

#skills#agent#plugins#architecture