ext.yml Manifest Reference

ext.yml is an extension container's manifest, placed at the root of the container directory. It declares the container's metadata and, in the contributes section, lists the capabilities the container provides to the system. This is the authoritative reference for all fields.

To understand the overall model first, read the Extension System Overview. When writing a manifest, validate it with clacky ext verify — it reports errors field by field with locations.

Top-Level Fields

id: weather-panel          # unique container id (defaults to directory name); lowercase letters, digits, -, _
name: Weather Panel        # display name
description: Sidebar weather panel
version: "0.1.0"           # semantic version; used as-is on publish
author: Your Name          # credit, shown on the New Session card
origin: self               # source nature: self / marketplace / enterprise
contributes:               # contributions (see below)
  ...
Field Required Description
id No Unique container id; defaults to directory name. Overridden across layers by id (local > installed > builtin).
name Yes Display name.
title No Optional short title (used by some UIs).
description No One-line summary.
version Yes Semantic version string, e.g. "0.1.0". Used as-is when publishing a new version.
author No Credit, shown on the New Session card.
origin No Source nature: self (locally authored, default) / marketplace (commercial, encrypted) / enterprise (internal).
homepage No Homepage / repo URL.
license No License identifier, e.g. MIT.
license_required No Boolean; whether install / use requires a license.
public No Boolean; whether it may be listed publicly in the marketplace.
keywords No Array of strings; keywords for marketplace search.
contributes Yes Contribution section declaring what the container provides.

The contributes Section

contributes may hold any combination of the following seven keys. Detailed usage is in each linked doc; here we only list fields.

panels — Web UI Panels

contributes:
  panels:
    - id: weather                    # panel id, globally unique
      title: Weather                 # tab / title text
      title_zh: 天气                  # Chinese title (optional)
      view: panels/weather/view.js   # panel script path (relative to container root)
      attach: ["*"]                  # visibility: array of agent ids, or ["*"] for all
      order: 100                     # ordering when multiple panels share a slot (default 100)
Field Description
id Panel id, globally unique; other agents can reuse it via panels: [id].
title / title_zh Title text (EN / ZH).
description / description_zh Panel description (optional).
view Panel JS script path, relative to container root.
attach Visibility: array of agent-id strings, or ["*"] for all. Omit to let referencing agents' panels: decide mounting.
order Ordering number, default 100.

See Web UI Extensions.

api — HTTP Backend Endpoint

A single backend can be written inline:

contributes:
  api: api/handler.rb        # single handler, mounted at /api/ext/<id>/

handler.rb defines a Clacky::ApiExtension subclass declaring endpoints with a routing DSL. See HTTP API Extensions.

skills — AI Skills

contributes:
  skills:
    - id: triage             # skill id
      dir: skills/triage/    # directory holding SKILL.md (defaults to skills/<id>/)
      protected: false       # whether encrypted (for commercial extensions)

agents — Assistants

contributes:
  agents:
    - id: designer
      title: Designer
      title_zh: 设计师
      description: A demo agent that owns the canvas panel.
      description_zh: 拥有画布面板的演示 agent。
      order: 100
      prompt: agents/designer.md   # system prompt for personality / role
      avatar: agents/designer.png  # avatar (optional)
      panels: [canvas]             # which panels to mount (referenced by id)
      skills: [layout-tips]        # which skills to bind (referenced by id)

panels: / skills: reference by id — they can reference contributions from this container or shared components elsewhere (e.g. the builtin git). See Agent Configuration.

channels — IM Channel Adapters

contributes:
  channels:
    - id: slack
      platform: slack              # platform identifier (optional)
      adapter: channels/slack.rb   # adapter script path

See Custom Channel Adapter.

patches — Runtime Patches

contributes:
  patches:
    - target: "Clacky::Tools::Terminal#execute"  # method to prepend onto
      file: patches/audit.rb                     # patch file path
      fingerprint: "a1b2c3..."                   # optional: source fingerprint of the target
      on_mismatch: disable                       # on fingerprint mismatch: disable / warn

Omitting fingerprint = trust the patch and require it directly; providing one lets the loader act via on_mismatch when upstream source drifts. See Runtime Patches.

hooks — Tool-Call Interception

contributes:
  hooks:
    - event: before_tool_use     # event name (see table below)
      file: hooks/audit.rb       # callback script path

Valid events: before_tool_use, after_tool_use, on_tool_error, on_start, on_complete, on_iteration, session_rollback. See Declarative Shell Hooks.

Full Example

A "Slack suite" contributing five capabilities from one container:

id: slack-suite
name: Slack Suite
description: Slack integration + support agent + inbox panel
version: "0.1.0"
author: Your Name
origin: self
contributes:
  channels:
    - id: slack
      adapter: channels/slack.rb
  agents:
    - id: support
      title: Support
      prompt: agents/support.md
      panels: [inbox]
      skills: [triage]
  panels:
    - id: inbox
      view: panels/inbox/view.js
      attach: [support]        # only appears in the support agent's sessions
  skills:
    - id: triage
      dir: skills/triage/
  api: api/handler.rb

Validate with clacky ext verify: it checks field validity, id uniqueness, and reference integrity (do the inbox/triage that support references exist, do the view/prompt files exist), reporting locatable errors.

Extension System Overview
Custom Channel Adapter