iii-directory

v1.2.41

Engine introspection, workers registry proxy, filesystem-backed skills, system prompts, and agent profiles, kit install and update with reviewed plans, plus function search ranked by the judge worker (falling back to local hybrid/lexical) with a conditional pre-generate hint.

license: Apache-2.0Published 6h agoUsed in 1 kitagents directory functions introspect kits registry search skills

Install

bash

iii trigger compose::add worker=iii-directory

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions42

directory::__on_worker_added

Function

Internal: auto-download skills on worker add event.

Request

workerstring

Response

okbooleanrequired

directory::agents::create

Function

Create a new agent profile at <agents_folder>/<id>.md from full-file markdown (frontmatter with a non-empty `name`, emoji-only `logo`, optional `skills:` preloads, `skills_index: false` to start sessions without the skills index, and `functions:` list of engine function ids to pre-load into sessions; the body is the system prompt and may be empty). Rejects ids or paths that already exist; a bundled id is shadowed.

Request

contentstringrequired
Full file content, frontmatter included; `name` is required, the body is the system prompt and may be empty.
idstringrequired
New profile id, used as the file stem; lowercase ASCII, digits, `-` and `_` only, and not already taken.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
descriptionstringrequired
idstringrequired
logostring
modified_atstringrequired
File mtime after the write, RFC 3339.
namestringrequired
Display name parsed from the (new) frontmatter.

directory::agents::delete

Function

Delete one existing agent profile's markdown file by id. Deleting the local shadow of a bundled profile falls back to the bundled copy; profiles that extend it stop resolving until fixed.

Request

idstringrequired
Existing agent profile id, as returned by `directory::agents::list`.

Response

idstringrequired

directory::agents::functions::add

Function

Add preloaded functions to one existing agent profile: appends the given engine function ids (e.g. `coder::tree`) to the profile's own `functions:` list — the contracts the harness pre-loads into the system prompt of every new session running as this profile. Ids already present are kept once; the rest of the file is untouched. Editing a bundled profile creates the local file that shadows it.

Request

functionsstring[]required
Engine function ids (e.g. `coder::tree`), verbatim, one per entry.
idstringrequired
Existing agent profile id, as returned by `directory::agents::list`.

Response

addedstring[]required
Ids this call actually added (already-present ids are not repeated).
bytesinteger· uintrequiredmin 0
Bytes on disk after the call.
functionsstring[]required
The profile's OWN `functions:` list after the write (not resolved through `extends`), in file order.
idstringrequired
modified_atstringrequired
File mtime after the call, RFC 3339.
removedstring[]required
Ids this call actually removed (absent ids are ignored).
unchangedbooleanrequired
True when the request changed nothing; the file was not rewritten.

directory::agents::functions::remove

Function

Remove preloaded functions from one existing agent profile: drops the given engine function ids from the profile's own `functions:` list (ids not present are ignored); the rest of the file is untouched. Only the profile's OWN list is edited; ids inherited through `extends` stay (the resolved list is the union of the chain) and are removed on the parent.

Request

functionsstring[]required
Engine function ids (e.g. `coder::tree`), verbatim, one per entry.
idstringrequired
Existing agent profile id, as returned by `directory::agents::list`.

Response

addedstring[]required
Ids this call actually added (already-present ids are not repeated).
bytesinteger· uintrequiredmin 0
Bytes on disk after the call.
functionsstring[]required
The profile's OWN `functions:` list after the write (not resolved through `extends`), in file order.
idstringrequired
modified_atstringrequired
File mtime after the call, RFC 3339.
removedstring[]required
Ids this call actually removed (absent ids are ignored).
unchangedbooleanrequired
True when the request changed nothing; the file was not rewritten.

directory::agents::get

Function

Fetch one agent profile by id: the system prompt resolved through its `extends` chain, display fields, preloaded `skills` (skill ids whose bodies the harness pre-loads into the session prompt) plus `unknown_skills`, preloaded `functions` (engine function ids the harness pre-loads into the session prompt) plus `unknown_functions`, model, reasoning_effort, `skills_index` (false = sessions start without the skills index), and `inheritance_error` when the chain does not resolve. Pass raw: true for the exact on-disk file to edit with directory::agents::update.

Request

idstringrequired
rawboolean
When true, also return the exact on-disk file (frontmatter included) as `raw`, ready for directory::agents::update.

Response

builtinbooleanrequired
Bundled with the worker, no file behind it (see `list`).
colorstring
Harness subagent color token (closed set, validated at write time); `null` = neutral.
composer_placeholderstring
Example request for the chat's empty composer (see `list`): this profile's own value, never inherited; omitted when absent or blank.
descriptionstringrequired
extendsstring
Parent profile id (`extends:`), as declared; `null` = none.
functionsstring[]required
Preloaded functions, resolved through `extends` (the nearest profile with a non-empty list): engine function ids whose contracts the harness pre-loads into the system prompt of every session running as this profile, so the model calls them without discovery or a contract lookup. Empty = none.
hiddenbooleanrequired
Hidden from the chat's new-session gallery (still selectable by id).
iconstring
Harness subagent icon token (closed set, validated at write time); `null` = caller picks.
idstringrequired
inheritance_errorstring
Set when the `extends` chain does not resolve (unknown parent, loop, deeper than 8): `system_prompt` and the inherited fields then come from this file alone, `raw` still round-trips so the chain can be fixed, and the harness refuses to run the profile meanwhile.
logostring
modelstring
Model id for sessions using this profile, resolved through `extends`; `null` = the send decides. Served verbatim — resolution against the live model catalog happens where it is used.
modified_atstringrequired
File mtime as RFC 3339; empty for a bundled profile.
namestringrequired
rawstring
FULL on-disk file content (this profile's own file, ancestors excluded). Present only when the request set `raw: true`.
reasoning_effortstring
Provider-native reasoning effort paired with `model`, resolved through `extends`; `null` = the model/provider default. Served verbatim and validated at use time.
skillsstring[]required
Preloaded skills, resolved through `extends` (the union of the chain's lists, root first): skill ids whose bodies the harness pre-loads into the system prompt of every session running as this profile. Empty = none. Never a filter on the skills index.
skills_indexboolean
`false` = sessions running as this profile start without the names-only skills index (`<available_skills>`), resolved through `extends`; omitted when no profile in the chain sets it (on).
sourceall ofrequired
Where the file came from (see `list`).
all of (1)
Variant 1
kindstringrequiredenum kit, worker, local, global, builtin
kitstring
Owning kit (`<handle>/<name>`) when `kind` is `kit`.
modifiedboolean
The file differs from what its kit or worker wrote.
versionstring
Version of the kit or worker that wrote the file.
workerstring
Owning worker when `kind` is `worker`.
system_promptstringrequired
The RESOLVED identity: every ancestor's body root-first, then this file's body, frontmatter stripped, joined by a blank line; blank bodies are skipped, so a profile with no prompt of its own serves its parent chain unchanged and a prompt-less profile without `extends` serves `""`. A profile that has a body and no `extends` serves that body verbatim.
unknown_functionsstring[]required
`functions` entries the engine does not currently know (not registered right now, or a typo). Warnings — the profile still loads and the harness skips them; an empty list also results when the engine could not be asked.
unknown_skillsstring[]required
`skills` entries that resolve to no currently visible skill. Warnings — the agent profile still loads and the harness renders them as unavailable.

directory::agents::list

Function

List agent profiles (id, name, description, logo, icon, color, model, reasoning_effort, skill_count, function_count, extends, hidden, composer_placeholder, source, modified_at) from the agents folder plus the bundled ones (`builtin: true`). `source` says where each file came from: kit, worker, local, global or builtin. Inherited fields resolve through `extends` (composer_placeholder never inherits); skill_count null means no preloaded skills, function_count counts the preloaded functions (contracts injected into new sessions).

Request

Empty object

Response

agentsobject[]required
- builtinbooleanrequired
  Bundled with the worker, no file behind it: editing it creates the local file (which then shadows this entry); there is nothing to delete.
- colorstring
  Harness subagent color token for display identities; `null` = neutral.
- composer_placeholderstring
  Example request for the chat's empty composer, from this profile's OWN frontmatter (never inherited through `extends`); omitted when absent or blank. Presentation only — never part of the prompt.
- descriptionstringrequired
- extendsstring
  Parent profile id (`extends:`), as declared; `null` = none.
- function_countinteger· uintrequiredmin 0
  Number of preloaded functions (contracts the harness pre-loads into the session prompt), resolved through `extends`; `0` = none.
- hiddenbooleanrequired
  Hidden from the chat's new-session gallery (still selectable by id).
- iconstring
  Harness subagent icon token for spawn display identities; `null` = caller picks.
- idstringrequired
  Flat agent profile id (the file stem) — what `harness::send { options: { agent } }` will take.
- inheritance_errorstring
  Set when the `extends` chain does not resolve (unknown parent, loop, too deep): the row carries the profile's own fields only, and the harness refuses to run it until the chain is fixed.
- logostring
  Emoji logo, `null` when the agent profile has none.
- modelstring
  Model id for sessions using this profile, resolved through `extends`; `null` = the send decides.
- modified_atstringrequired
  File mtime as RFC 3339; empty for a bundled profile.
- namestringrequired
  Display name from frontmatter (`name:`).
- reasoning_effortstring
  Provider-native reasoning effort paired with `model`, resolved through `extends`; `null` = the model/provider default.
- skill_countinteger· uintmin 0
  Number of preloaded skills (bodies the harness pre-loads into the session prompt), resolved through `extends`; `null` = none.
- sourceall ofrequired
  Where the file came from: an installed kit (`kits.lock`), a worker's skills bundle (its completion marker), the project itself (`local`), the user-global root (`global`) or the worker binary (`builtin`). `modified` says whether a kit's or worker's file was edited here.
  all of (1)
  Variant 1
  kindstringrequiredenum kit, worker, local, global, builtin
  kitstring
  Owning kit (`<handle>/<name>`) when `kind` is `kit`.
  modifiedboolean
  The file differs from what its kit or worker wrote.
  versionstring
  Version of the kit or worker that wrote the file.
  workerstring
  Owning worker when `kind` is `worker`.

directory::agents::update

Function

Overwrite one existing agent profile with full-file markdown (frontmatter with a non-empty `name`, emoji-only `logo`, optional `skills:` and `functions:` lists and `skills_index`; the body is the system prompt and may be empty). Updating a bundled profile creates a local file that shadows it. To change only the preloaded functions, prefer directory::agents::functions::add / remove.

Request

contentstringrequired
FULL new file content, frontmatter block included — the string `directory::agents::get { raw: true }` returns, edited.
idstringrequired
Existing agent profile id, as returned by `directory::agents::list`.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
descriptionstringrequired
idstringrequired
logostring
modified_atstringrequired
File mtime after the write, RFC 3339.
namestringrequired
Display name parsed from the (new) frontmatter.

directory::download-kit

Function

Plan the install of a kit — agent profiles, skills and registry workers published as <author>/<kit>[@version|tag|range] — without writing anything; an installed kit gets an update plan. The plan lists every file, collisions with existing profiles (kit profiles win, with a warning), worker changes and the functions the profiles preload. Review it in the ADE (Directory → Kits) or apply it with directory::kits::apply plan_id=…. apply=true applies at once only when the plan has no warnings, blocks or pending decisions.

Request

applyboolean
Apply right away when the plan has no warnings, no blocking issue and no file that needs a decision (for scripts). Otherwise the plan waits for review.
kitstringrequired
`<author>/<kit>`, optionally `@<version|tag|range>` (default: the installed kit's `requested`, else `latest`).

Response

kitstringrequired
messagestringrequired
One sentence for a terminal user.
planany of
any of (2)
Variant 1
authorany of
Show 2 nestedHide nested
any of (2)
Variant 1
handlestring
namestring
verifiedboolean
Variant 2
valuenull
blockingobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
bumpstring
`major` | `minor` | `patch` | `prerelease` (update).
capabilitiesobjectrequired
Show 3 nestedHide nested
functions_addedobject[]
Show 2 nestedHide nested
agentstring
functionstring
models_changedobject[]
Show 3 nestedHide nested
agentstring
fromstring
tostring
workers_addedstring[]
countsobjectrequired
Show 11 nestedHide nested
addedinteger· uintrequiredmin 0
agentsinteger· uintrequiredmin 0
collisionsinteger· uintrequiredmin 0
conflictsinteger· uintrequiredmin 0
decisions_requiredinteger· uintrequiredmin 0
Files whose `default` is `null`.
functionsinteger· uintrequiredmin 0
modifiedinteger· uintrequiredmin 0
removedinteger· uintrequiredmin 0
skillsinteger· uintrequiredmin 0
unchangedinteger· uintrequiredmin 0
workersinteger· uintrequiredmin 0
created_atstringrequired
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
descriptionstring
expires_atstringrequired
filesobject[]required
Show 20 nestedHide nested
agentany of
Kit profile frontmatter (agents; the side this plan installs, or the removed one).
Show 2 nestedHide nested
any of (2)
Variant 1
colorstring
descriptionstring
extendsstring
functionsstring[]
hiddenboolean
iconstring
idstring
logostring
modelstring
namestring
pathstring
reasoning_effortstring
sha256string
size_bytesinteger· uint64min 0
skillsstring[]
Variant 2
valuenull
agent_changesany of
Frontmatter changes versus the installed version (modified agents).
Show 2 nestedHide nested
any of (2)
Variant 1
fieldsobject
Scalar fields that changed: `field → [from, to]`.
functions_addedstring[]
functions_removedstring[]
skills_addedstring[]
skills_removedstring[]
Variant 2
valuenull
basestring
Content hash the kit installed (the merge base).
body_changedboolean
changeone ofrequired
Show 2 nestedHide nested
one of (2)
Variant 1
valuestringenum added, modified, removed
Variant 2
valuestringenum kept
collisionany of
Show 2 nestedHide nested
any of (2)
Variant 1
kitstring
modifiedboolean
The owner's copy was edited locally.
ownerall ofrequired
Who owns the file at the path today.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum kit, worker, local, global, builtin
sha256string
sha256 of the file there now.
versionstring
workerstring
Variant 2
valuenull
conflictsinteger· uintmin 0
defaultany of
Applied when the caller decides nothing; `null` = a decision is required.
Show 2 nestedHide nested
any of (2)
Variant 1
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
Variant 2
valuenull
idstringrequired
Agent profile id, or skill id.
kindstringrequiredenum agent, skill
localone ofrequired
What the file is on disk right now, relative to the plan.
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum absent
Variant 2
valuestringenum intact
Variant 3
valuestringenum edited
Variant 4
valuestringenum missing
Variant 5
valuestringenum occupied
mergeany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum clean, conflicts
Variant 2
valuenull
notestring
One-line explanation for the review.
optionsone of[]required
Choices the apply accepts for this file.
Show 6 nestedHide nested
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
oursstring
Content hash of the local file when the plan was made.
pathstringrequired
Logical install path (`agents/<id>.md`, `skills/<handle>/<kit>/…`).
skillany of
Skill frontmatter (skills).
Show 2 nestedHide nested
any of (2)
Variant 1
descriptionstring
idstring
pathstring
sha256string
size_bytesinteger· uint64min 0
titlestring
typestring
used_bystring[]
Variant 2
valuenull
skippedboolean
The lock says the user kept someone else's file here.
sourcestringrequired
Path inside the kit (`agents/<id>.md`, `skills/…`).
theirsstring
Content hash of the kit's version this plan installs.
fromstring
Installed version (update, remove).
functionsobject[]required
Functions the kit's profiles preload, with the worker that provides each.
Show 6 nestedHide nested
descriptionstring
idstring
statusstring
used_bystring[]
workerstring
worker_versionstring
kindstringrequiredenum install, update, remove
kitstringrequired
licensestring
majorbooleanrequired
notesstring
plan_idstringrequired
published_atstring
registry_urlstringrequired
The kit's page in the registry web app.
repostring
requestedstringrequired
What was asked for (tag, version or range) — stored in the lock.
reviewstringrequired
Where a human reviews it.
tostring
Version this plan installs (install, update).
warningsobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
workersobject[]required
Show 13 nestedHide nested
actionone ofrequired
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum none
Variant 2
valuestringenum add
Variant 3
valuestringenum update
Variant 4
valuestringenum redeclare
Variant 5
valuestringenum remove
containerstring
declaredstring
`version:` selector in the compose file.
descriptionstring
installedstring
Version Compose has installed.
namestringrequired
pathboolean
The operator's `path://` build; kits never manage it.
rangestring
Range the kit declares (absent for a worker the kit dropped).
range_fromstring
Range the installed kit version declared.
registry_urlstringrequired
tostring
Version the range resolves to in the registry today.
typestring
Worker type (`binary`, `image`, …).
used_bystring[]
Other installed kits that declare this worker.
Variant 2
valuenull
reportany of
any of (2)
Variant 1
agentsstring[]required
Agent profile ids this kit now provides.
agents_changedbooleanrequired
files_keptstring[]required
Files left as they are (kept, skipped, or mine).
files_mergedstring[]required
files_removedstring[]required
files_writtenstring[]required
fromstring
kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum install, update, remove
Variant 2
valuenull
kitstringrequired
lock_pathstringrequired
plan_idstringrequired
skills_changedbooleanrequired
stepsobject[]required
Show 4 nestedHide nested
detailstring
idstringrequired
`workers` | `files` | `lock`.
labelstringrequired
statestringrequiredenum pending, running, done, failed, skipped
tostring
workers_addedstring[]required
workers_removedstring[]required
workers_updatedstring[]required
Variant 2
valuenull
statusone ofrequired
one of (4)
Variant 1
valuestringenum planned
Variant 2
valuestringenum applied
Variant 3
valuestringenum up_to_date
Variant 4
valuestringenum replanned

directory::engine::functions::info

Function

Read full detail for one engine function: schemas, owning worker, and registered triggers that target it. Proxies to the engine's native engine::functions::info.

Request

function_idstringrequired
Fully-qualified function id on the bus (e.g. `sandbox::create`).

Response

descriptionstring
function_idstringrequired
metadataunknown
registered_triggersobject[]required
- configunknownrequired
- idstringrequired
- trigger_typestringrequired
request_schemaunknown
response_schemaunknown
worker_namestring

directory::hint-preview

Function

Internal: the exact search-hint text per exposure mode, for the configuration UI.

Request

Empty object

Response

agent_triggerstringrequired
nativestringrequired

directory::kits::apply

Function

Apply a kit plan from directory::download-kit / plan-update / remove: re-checks the project, downloads the kit (counted), adds or moves its workers through Compose, writes the files atomically and records kits.lock last. decisions maps install paths to overwrite|keep|kit|mine|merged|remove (or {choice: merged, content}); files left out take the plan's default. If the project changed since the plan, nothing is applied and a fresh plan comes back (status replanned).

Request

decisionsobject
Per-file choices by install path: `"overwrite" | "keep" | "kit" | "mine" | "merged" | "remove"`, or `{ "choice": "merged", "content": "…" }`. Files left out take the plan's `default`.
plan_idstringrequired
remove_workersstring[]
Workers the kit no longer declares (update) or declares (removal) to remove from the compose file. Never removed otherwise.

Response

kitstringrequired
messagestringrequired
One sentence for a terminal user.
planany of
any of (2)
Variant 1
authorany of
Show 2 nestedHide nested
any of (2)
Variant 1
handlestring
namestring
verifiedboolean
Variant 2
valuenull
blockingobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
bumpstring
`major` | `minor` | `patch` | `prerelease` (update).
capabilitiesobjectrequired
Show 3 nestedHide nested
functions_addedobject[]
Show 2 nestedHide nested
agentstring
functionstring
models_changedobject[]
Show 3 nestedHide nested
agentstring
fromstring
tostring
workers_addedstring[]
countsobjectrequired
Show 11 nestedHide nested
addedinteger· uintrequiredmin 0
agentsinteger· uintrequiredmin 0
collisionsinteger· uintrequiredmin 0
conflictsinteger· uintrequiredmin 0
decisions_requiredinteger· uintrequiredmin 0
Files whose `default` is `null`.
functionsinteger· uintrequiredmin 0
modifiedinteger· uintrequiredmin 0
removedinteger· uintrequiredmin 0
skillsinteger· uintrequiredmin 0
unchangedinteger· uintrequiredmin 0
workersinteger· uintrequiredmin 0
created_atstringrequired
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
descriptionstring
expires_atstringrequired
filesobject[]required
Show 20 nestedHide nested
agentany of
Kit profile frontmatter (agents; the side this plan installs, or the removed one).
Show 2 nestedHide nested
any of (2)
Variant 1
colorstring
descriptionstring
extendsstring
functionsstring[]
hiddenboolean
iconstring
idstring
logostring
modelstring
namestring
pathstring
reasoning_effortstring
sha256string
size_bytesinteger· uint64min 0
skillsstring[]
Variant 2
valuenull
agent_changesany of
Frontmatter changes versus the installed version (modified agents).
Show 2 nestedHide nested
any of (2)
Variant 1
fieldsobject
Scalar fields that changed: `field → [from, to]`.
functions_addedstring[]
functions_removedstring[]
skills_addedstring[]
skills_removedstring[]
Variant 2
valuenull
basestring
Content hash the kit installed (the merge base).
body_changedboolean
changeone ofrequired
Show 2 nestedHide nested
one of (2)
Variant 1
valuestringenum added, modified, removed
Variant 2
valuestringenum kept
collisionany of
Show 2 nestedHide nested
any of (2)
Variant 1
kitstring
modifiedboolean
The owner's copy was edited locally.
ownerall ofrequired
Who owns the file at the path today.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum kit, worker, local, global, builtin
sha256string
sha256 of the file there now.
versionstring
workerstring
Variant 2
valuenull
conflictsinteger· uintmin 0
defaultany of
Applied when the caller decides nothing; `null` = a decision is required.
Show 2 nestedHide nested
any of (2)
Variant 1
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
Variant 2
valuenull
idstringrequired
Agent profile id, or skill id.
kindstringrequiredenum agent, skill
localone ofrequired
What the file is on disk right now, relative to the plan.
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum absent
Variant 2
valuestringenum intact
Variant 3
valuestringenum edited
Variant 4
valuestringenum missing
Variant 5
valuestringenum occupied
mergeany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum clean, conflicts
Variant 2
valuenull
notestring
One-line explanation for the review.
optionsone of[]required
Choices the apply accepts for this file.
Show 6 nestedHide nested
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
oursstring
Content hash of the local file when the plan was made.
pathstringrequired
Logical install path (`agents/<id>.md`, `skills/<handle>/<kit>/…`).
skillany of
Skill frontmatter (skills).
Show 2 nestedHide nested
any of (2)
Variant 1
descriptionstring
idstring
pathstring
sha256string
size_bytesinteger· uint64min 0
titlestring
typestring
used_bystring[]
Variant 2
valuenull
skippedboolean
The lock says the user kept someone else's file here.
sourcestringrequired
Path inside the kit (`agents/<id>.md`, `skills/…`).
theirsstring
Content hash of the kit's version this plan installs.
fromstring
Installed version (update, remove).
functionsobject[]required
Functions the kit's profiles preload, with the worker that provides each.
Show 6 nestedHide nested
descriptionstring
idstring
statusstring
used_bystring[]
workerstring
worker_versionstring
kindstringrequiredenum install, update, remove
kitstringrequired
licensestring
majorbooleanrequired
notesstring
plan_idstringrequired
published_atstring
registry_urlstringrequired
The kit's page in the registry web app.
repostring
requestedstringrequired
What was asked for (tag, version or range) — stored in the lock.
reviewstringrequired
Where a human reviews it.
tostring
Version this plan installs (install, update).
warningsobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
workersobject[]required
Show 13 nestedHide nested
actionone ofrequired
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum none
Variant 2
valuestringenum add
Variant 3
valuestringenum update
Variant 4
valuestringenum redeclare
Variant 5
valuestringenum remove
containerstring
declaredstring
`version:` selector in the compose file.
descriptionstring
installedstring
Version Compose has installed.
namestringrequired
pathboolean
The operator's `path://` build; kits never manage it.
rangestring
Range the kit declares (absent for a worker the kit dropped).
range_fromstring
Range the installed kit version declared.
registry_urlstringrequired
tostring
Version the range resolves to in the registry today.
typestring
Worker type (`binary`, `image`, …).
used_bystring[]
Other installed kits that declare this worker.
Variant 2
valuenull
reportany of
any of (2)
Variant 1
agentsstring[]required
Agent profile ids this kit now provides.
agents_changedbooleanrequired
files_keptstring[]required
Files left as they are (kept, skipped, or mine).
files_mergedstring[]required
files_removedstring[]required
files_writtenstring[]required
fromstring
kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum install, update, remove
Variant 2
valuenull
kitstringrequired
lock_pathstringrequired
plan_idstringrequired
skills_changedbooleanrequired
stepsobject[]required
Show 4 nestedHide nested
detailstring
idstringrequired
`workers` | `files` | `lock`.
labelstringrequired
statestringrequiredenum pending, running, done, failed, skipped
tostring
workers_addedstring[]required
workers_removedstring[]required
workers_updatedstring[]required
Variant 2
valuenull
statusone ofrequired
one of (4)
Variant 1
valuestringenum planned
Variant 2
valuestringenum applied
Variant 3
valuestringenum up_to_date
Variant 4
valuestringenum replanned

directory::kits::check-updates

Function

Ask the registry whether installed kits (or one) have a newer release matching what they were installed with. Ignored versions are skipped. Also runs at boot and every 6 hours.

Request

kitstring
Check only this installed kit (default: every installed kit).

Response

availableinteger· uintrequiredmin 0
Installed kits with an update to offer.
checked_atstring
errorstring
Why the last check could not reach the registry, if it could not.
kitsobject[]required
- availablestring
  Newest version satisfying `requested`, unless the user ignored it.
- currentstringrequired
- deprecationany of
  any of (2)
  Variant 1
  messagestring
  replaced_bystring
  Variant 2
  valuenull
- ignoredstring
  `available` would be this version, but the user ignored it.
- kitstringrequired
- lateststring
- majorbooleanrequired
- not_foundboolean

directory::kits::diff

Function

The two sides of an installed kit file: `base` (what the kit installed, from the registry) and `local` (the file on disk), for a "view my changes" diff.

Request

kitstringrequired
Installed kit, `<author>/<kit>`.
pathstringrequired
Install path from `directory::kits::get` (`agents/<id>.md`, `skills/…`).

Response

basestring
What the kit installed (the lock's base), from the registry; `null` when the registry does not have it.
kitstringrequired
localstring
The file on disk, `null` when it is missing.
pathstringrequired
stateone ofrequired
Local state of an installed file relative to its lock entry.
one of (2)
Variant 1
valuestringenum intact, edited, missing
Variant 2
valuestringenum skipped

directory::kits::discard

Function

Discard a pending kit plan.

Request

plan_idstringrequired

Response

discardedbooleanrequired
plan_idstringrequired

directory::kits::get

Function

One installed kit: every file with its state (intact, edited, missing, skipped), its workers as Compose has them, and with registry=true the installed version's detail and README.

Request

kitstringrequired
Installed kit, `<author>/<kit>`.
registryboolean
Also fetch the installed version's registry detail and README.

Response

detailany of
Registry detail of the installed version, when reachable.
any of (2)
Variant 1
agentsobject[]
Show 15 nestedHide nested
colorstring
descriptionstring
extendsstring
functionsstring[]
hiddenboolean
iconstring
idstring
logostring
modelstring
namestring
pathstring
reasoning_effortstring
sha256string
size_bytesinteger· uint64min 0
skillsstring[]
authorall of
Show 1 nestedHide nested
all of (1)
Variant 1
handlestring
namestring
verifiedboolean
countsall of
Show 1 nestedHide nested
all of (1)
Variant 1
agentsinteger· uint64min 0
skillsinteger· uint64min 0
workersinteger· uint64min 0
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
descriptionstring
experimentalboolean
idstring
licensestring
namestring
notesstring
published_atstring
release_tagsobject
repostring
skillsobject[]
Show 8 nestedHide nested
descriptionstring
idstring
pathstring
sha256string
size_bytesinteger· uint64min 0
titlestring
typestring
used_bystring[]
tagsstring[]
total_downloadsinteger· uint64min 0
versionstring
workersobject[]
Show 5 nestedHide nested
descriptionstring
namestring
rangestring
resolvedstring
typestring
Variant 2
valuenull
file_listobject[]required
- idstringrequired
  Agent id, or the skill id.
- kindstringrequired
- local_sha256string
  sha256 on disk, `null` when missing.
- pathstringrequired
- sha256stringrequired
  Base sha256 from the lock.
- stateone ofrequired
  Local state of an installed file relative to its lock entry.
  one of (2)
  Variant 1
  valuestringenum intact, edited, missing
  Variant 2
  valuestringenum skipped
filesobjectrequired
- agentsinteger· uintrequiredmin 0
- editedinteger· uintrequiredmin 0
- intactinteger· uintrequiredmin 0
- missinginteger· uintrequiredmin 0
- skillsinteger· uintrequiredmin 0
- skippedinteger· uintrequiredmin 0
installed_atstringrequired
kitstringrequired
pendingstring[]required
Plans of this kit waiting for review.
readmestring
registry_urlstringrequired
requestedstringrequired
updateany of
any of (2)
Variant 1
availablestring
Newest version satisfying `requested`, unless the user ignored it.
currentstringrequired
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
ignoredstring
`available` would be this version, but the user ignored it.
lateststring
majorbooleanrequired
not_foundboolean
Variant 2
valuenull
versionstringrequired
worker_statusunknown[]required
Workers as Compose has them now.
workersobjectrequired

directory::kits::ignore

Function

Skip (or, with ignore=false, stop skipping) one version of an installed kit in update checks; recorded in kits.lock ignored_versions.

Request

ignoreboolean
`false` takes the version back off the list (default `true`).
kitstringrequired
Installed kit, `<author>/<kit>`.
versionstringrequired
Version to skip in update checks.

Response

ignored_versionsstring[]required
kitstringrequired

directory::kits::list

Function

Installed kits (version, file states, worker ranges, available update) and the plans waiting for review. `attention` counts both.

Request

Empty object

Response

attentioninteger· uintrequiredmin 0
Pending plans plus available updates: what the Kits badge counts.
kitsobject[]required
- filesobjectrequired
  agentsinteger· uintrequiredmin 0
  editedinteger· uintrequiredmin 0
  intactinteger· uintrequiredmin 0
  missinginteger· uintrequiredmin 0
  skillsinteger· uintrequiredmin 0
  skippedinteger· uintrequiredmin 0
- installed_atstringrequired
- kitstringrequired
- pendingstring[]required
  Plans of this kit waiting for review.
- registry_urlstringrequired
- requestedstringrequired
- updateany of
  any of (2)
  Variant 1
  availablestring
  Newest version satisfying `requested`, unless the user ignored it.
  currentstringrequired
  deprecationany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  messagestring
  replaced_bystring
  Variant 2
  valuenull
  ignoredstring
  `available` would be this version, but the user ignored it.
  lateststring
  majorbooleanrequired
  not_foundboolean
  Variant 2
  valuenull
- versionstringrequired
- workersobjectrequired
lock_pathstringrequired
pendingunknown[]required
Pending plans (summaries).
updates_checked_atstring
updates_errorstring

directory::kits::plan

Function

Read a pending kit plan, with contents=true the file bodies it refers to (kit blobs by sha256, local files and merge results by install path).

Request

contentsboolean
Include file bodies (`blobs` by sha256, `ours` and `merged` by path).
plan_idstringrequired

Response

contentsany of
File bodies the plan refers to; only with `contents=true`.
any of (2)
Variant 1
blobsobject
Kit blobs by sha256 (theirs and bases).
mergedobject
Three-way merge results, by install path.
oursobject
Local file bodies when the plan was made, by install path.
Variant 2
valuenull
planobjectrequired
- authorany of
  any of (2)
  Variant 1
  handlestring
  namestring
  verifiedboolean
  Variant 2
  valuenull
- blockingobject[]required
  codestringrequired
  messagestringrequired
  pathstring
- bumpstring
  `major` | `minor` | `patch` | `prerelease` (update).
- capabilitiesobjectrequired
  functions_addedobject[]
  Show 2 nestedHide nested
  agentstring
  functionstring
  models_changedobject[]
  Show 3 nestedHide nested
  agentstring
  fromstring
  tostring
  workers_addedstring[]
- countsobjectrequired
  addedinteger· uintrequiredmin 0
  agentsinteger· uintrequiredmin 0
  collisionsinteger· uintrequiredmin 0
  conflictsinteger· uintrequiredmin 0
  decisions_requiredinteger· uintrequiredmin 0
  Files whose `default` is `null`.
  functionsinteger· uintrequiredmin 0
  modifiedinteger· uintrequiredmin 0
  removedinteger· uintrequiredmin 0
  skillsinteger· uintrequiredmin 0
  unchangedinteger· uintrequiredmin 0
  workersinteger· uintrequiredmin 0
- created_atstringrequired
- deprecationany of
  any of (2)
  Variant 1
  messagestring
  replaced_bystring
  Variant 2
  valuenull
- descriptionstring
- expires_atstringrequired
- filesobject[]required
  agentany of
  Kit profile frontmatter (agents; the side this plan installs, or the removed one).
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  colorstring
  descriptionstring
  extendsstring
  functionsstring[]
  hiddenboolean
  iconstring
  idstring
  logostring
  modelstring
  namestring
  pathstring
  reasoning_effortstring
  sha256string
  size_bytesinteger· uint64min 0
  skillsstring[]
  Variant 2
  valuenull
  agent_changesany of
  Frontmatter changes versus the installed version (modified agents).
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  fieldsobject
  Scalar fields that changed: `field → [from, to]`.
  functions_addedstring[]
  functions_removedstring[]
  skills_addedstring[]
  skills_removedstring[]
  Variant 2
  valuenull
  basestring
  Content hash the kit installed (the merge base).
  body_changedboolean
  changeone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum added, modified, removed
  Variant 2
  valuestringenum kept
  collisionany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  kitstring
  modifiedboolean
  The owner's copy was edited locally.
  ownerall ofrequired
  Who owns the file at the path today.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  valuestringenum kit, worker, local, global, builtin
  sha256string
  sha256 of the file there now.
  versionstring
  workerstring
  Variant 2
  valuenull
  conflictsinteger· uintmin 0
  defaultany of
  Applied when the caller decides nothing; `null` = a decision is required.
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  one of (6)
  Variant 1
  valuestringenum overwrite
  Variant 2
  valuestringenum keep
  Variant 3
  valuestringenum kit
  Variant 4
  valuestringenum mine
  Variant 5
  valuestringenum merged
  Variant 6
  valuestringenum remove
  Variant 2
  valuenull
  idstringrequired
  Agent profile id, or skill id.
  kindstringrequiredenum agent, skill
  localone ofrequired
  What the file is on disk right now, relative to the plan.
  Show 5 nestedHide nested
  one of (5)
  Variant 1
  valuestringenum absent
  Variant 2
  valuestringenum intact
  Variant 3
  valuestringenum edited
  Variant 4
  valuestringenum missing
  Variant 5
  valuestringenum occupied
  mergeany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  valuestringenum clean, conflicts
  Variant 2
  valuenull
  notestring
  One-line explanation for the review.
  optionsone of[]required
  Choices the apply accepts for this file.
  Show 6 nestedHide nested
  one of (6)
  Variant 1
  valuestringenum overwrite
  Variant 2
  valuestringenum keep
  Variant 3
  valuestringenum kit
  Variant 4
  valuestringenum mine
  Variant 5
  valuestringenum merged
  Variant 6
  valuestringenum remove
  oursstring
  Content hash of the local file when the plan was made.
  pathstringrequired
  Logical install path (`agents/<id>.md`, `skills/<handle>/<kit>/…`).
  skillany of
  Skill frontmatter (skills).
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  descriptionstring
  idstring
  pathstring
  sha256string
  size_bytesinteger· uint64min 0
  titlestring
  typestring
  used_bystring[]
  Variant 2
  valuenull
  skippedboolean
  The lock says the user kept someone else's file here.
  sourcestringrequired
  Path inside the kit (`agents/<id>.md`, `skills/…`).
  theirsstring
  Content hash of the kit's version this plan installs.
- fromstring
  Installed version (update, remove).
- functionsobject[]required
  Functions the kit's profiles preload, with the worker that provides each.
  descriptionstring
  idstring
  statusstring
  used_bystring[]
  workerstring
  worker_versionstring
- kindstringrequiredenum install, update, remove
- kitstringrequired
- licensestring
- majorbooleanrequired
- notesstring
- plan_idstringrequired
- published_atstring
- registry_urlstringrequired
  The kit's page in the registry web app.
- repostring
- requestedstringrequired
  What was asked for (tag, version or range) — stored in the lock.
- reviewstringrequired
  Where a human reviews it.
- tostring
  Version this plan installs (install, update).
- warningsobject[]required
  codestringrequired
  messagestringrequired
  pathstring
- workersobject[]required
  actionone ofrequired
  Show 5 nestedHide nested
  one of (5)
  Variant 1
  valuestringenum none
  Variant 2
  valuestringenum add
  Variant 3
  valuestringenum update
  Variant 4
  valuestringenum redeclare
  Variant 5
  valuestringenum remove
  containerstring
  declaredstring
  `version:` selector in the compose file.
  descriptionstring
  installedstring
  Version Compose has installed.
  namestringrequired
  pathboolean
  The operator's `path://` build; kits never manage it.
  rangestring
  Range the kit declares (absent for a worker the kit dropped).
  range_fromstring
  Range the installed kit version declared.
  registry_urlstringrequired
  tostring
  Version the range resolves to in the registry today.
  typestring
  Worker type (`binary`, `image`, …).
  used_bystring[]
  Other installed kits that declare this worker.
progressany of
any of (2)
Variant 1
errorstring
started_atstring
stepsobject[]required
Show 4 nestedHide nested
detailstring
idstringrequired
`workers` | `files` | `lock`.
labelstringrequired
statestringrequiredenum pending, running, done, failed, skipped
writtenobject
Install path → sha written (or `""` for a deletion) by an earlier, interrupted attempt. Re-validation accepts these as expected.
Variant 2
valuenull

directory::kits::plan-update

Function

Plan the update of an installed kit to `version` (default: the newest release matching what it was installed with). Files you edited are merged three-way; conflicts need a decision before directory::kits::apply.

Request

kitstringrequired
Installed kit, `<author>/<kit>`.
versionstring
Target version, tag or range (default: what the kit was installed with).

Response

kitstringrequired
messagestringrequired
One sentence for a terminal user.
planany of
any of (2)
Variant 1
authorany of
Show 2 nestedHide nested
any of (2)
Variant 1
handlestring
namestring
verifiedboolean
Variant 2
valuenull
blockingobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
bumpstring
`major` | `minor` | `patch` | `prerelease` (update).
capabilitiesobjectrequired
Show 3 nestedHide nested
functions_addedobject[]
Show 2 nestedHide nested
agentstring
functionstring
models_changedobject[]
Show 3 nestedHide nested
agentstring
fromstring
tostring
workers_addedstring[]
countsobjectrequired
Show 11 nestedHide nested
addedinteger· uintrequiredmin 0
agentsinteger· uintrequiredmin 0
collisionsinteger· uintrequiredmin 0
conflictsinteger· uintrequiredmin 0
decisions_requiredinteger· uintrequiredmin 0
Files whose `default` is `null`.
functionsinteger· uintrequiredmin 0
modifiedinteger· uintrequiredmin 0
removedinteger· uintrequiredmin 0
skillsinteger· uintrequiredmin 0
unchangedinteger· uintrequiredmin 0
workersinteger· uintrequiredmin 0
created_atstringrequired
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
descriptionstring
expires_atstringrequired
filesobject[]required
Show 20 nestedHide nested
agentany of
Kit profile frontmatter (agents; the side this plan installs, or the removed one).
Show 2 nestedHide nested
any of (2)
Variant 1
colorstring
descriptionstring
extendsstring
functionsstring[]
hiddenboolean
iconstring
idstring
logostring
modelstring
namestring
pathstring
reasoning_effortstring
sha256string
size_bytesinteger· uint64min 0
skillsstring[]
Variant 2
valuenull
agent_changesany of
Frontmatter changes versus the installed version (modified agents).
Show 2 nestedHide nested
any of (2)
Variant 1
fieldsobject
Scalar fields that changed: `field → [from, to]`.
functions_addedstring[]
functions_removedstring[]
skills_addedstring[]
skills_removedstring[]
Variant 2
valuenull
basestring
Content hash the kit installed (the merge base).
body_changedboolean
changeone ofrequired
Show 2 nestedHide nested
one of (2)
Variant 1
valuestringenum added, modified, removed
Variant 2
valuestringenum kept
collisionany of
Show 2 nestedHide nested
any of (2)
Variant 1
kitstring
modifiedboolean
The owner's copy was edited locally.
ownerall ofrequired
Who owns the file at the path today.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum kit, worker, local, global, builtin
sha256string
sha256 of the file there now.
versionstring
workerstring
Variant 2
valuenull
conflictsinteger· uintmin 0
defaultany of
Applied when the caller decides nothing; `null` = a decision is required.
Show 2 nestedHide nested
any of (2)
Variant 1
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
Variant 2
valuenull
idstringrequired
Agent profile id, or skill id.
kindstringrequiredenum agent, skill
localone ofrequired
What the file is on disk right now, relative to the plan.
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum absent
Variant 2
valuestringenum intact
Variant 3
valuestringenum edited
Variant 4
valuestringenum missing
Variant 5
valuestringenum occupied
mergeany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum clean, conflicts
Variant 2
valuenull
notestring
One-line explanation for the review.
optionsone of[]required
Choices the apply accepts for this file.
Show 6 nestedHide nested
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
oursstring
Content hash of the local file when the plan was made.
pathstringrequired
Logical install path (`agents/<id>.md`, `skills/<handle>/<kit>/…`).
skillany of
Skill frontmatter (skills).
Show 2 nestedHide nested
any of (2)
Variant 1
descriptionstring
idstring
pathstring
sha256string
size_bytesinteger· uint64min 0
titlestring
typestring
used_bystring[]
Variant 2
valuenull
skippedboolean
The lock says the user kept someone else's file here.
sourcestringrequired
Path inside the kit (`agents/<id>.md`, `skills/…`).
theirsstring
Content hash of the kit's version this plan installs.
fromstring
Installed version (update, remove).
functionsobject[]required
Functions the kit's profiles preload, with the worker that provides each.
Show 6 nestedHide nested
descriptionstring
idstring
statusstring
used_bystring[]
workerstring
worker_versionstring
kindstringrequiredenum install, update, remove
kitstringrequired
licensestring
majorbooleanrequired
notesstring
plan_idstringrequired
published_atstring
registry_urlstringrequired
The kit's page in the registry web app.
repostring
requestedstringrequired
What was asked for (tag, version or range) — stored in the lock.
reviewstringrequired
Where a human reviews it.
tostring
Version this plan installs (install, update).
warningsobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
workersobject[]required
Show 13 nestedHide nested
actionone ofrequired
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum none
Variant 2
valuestringenum add
Variant 3
valuestringenum update
Variant 4
valuestringenum redeclare
Variant 5
valuestringenum remove
containerstring
declaredstring
`version:` selector in the compose file.
descriptionstring
installedstring
Version Compose has installed.
namestringrequired
pathboolean
The operator's `path://` build; kits never manage it.
rangestring
Range the kit declares (absent for a worker the kit dropped).
range_fromstring
Range the installed kit version declared.
registry_urlstringrequired
tostring
Version the range resolves to in the registry today.
typestring
Worker type (`binary`, `image`, …).
used_bystring[]
Other installed kits that declare this worker.
Variant 2
valuenull
reportany of
any of (2)
Variant 1
agentsstring[]required
Agent profile ids this kit now provides.
agents_changedbooleanrequired
files_keptstring[]required
Files left as they are (kept, skipped, or mine).
files_mergedstring[]required
files_removedstring[]required
files_writtenstring[]required
fromstring
kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum install, update, remove
Variant 2
valuenull
kitstringrequired
lock_pathstringrequired
plan_idstringrequired
skills_changedbooleanrequired
stepsobject[]required
Show 4 nestedHide nested
detailstring
idstringrequired
`workers` | `files` | `lock`.
labelstringrequired
statestringrequiredenum pending, running, done, failed, skipped
tostring
workers_addedstring[]required
workers_removedstring[]required
workers_updatedstring[]required
Variant 2
valuenull
statusone ofrequired
one of (4)
Variant 1
valuestringenum planned
Variant 2
valuestringenum applied
Variant 3
valuestringenum up_to_date
Variant 4
valuestringenum replanned

directory::kits::remove

Function

Plan the removal of an installed kit: its files (edited ones are kept unless chosen) and, only if ticked in apply's remove_workers, its workers. Apply with directory::kits::apply.

Request

kitstringrequired
Installed kit, `<author>/<kit>`.

Response

kitstringrequired
messagestringrequired
One sentence for a terminal user.
planany of
any of (2)
Variant 1
authorany of
Show 2 nestedHide nested
any of (2)
Variant 1
handlestring
namestring
verifiedboolean
Variant 2
valuenull
blockingobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
bumpstring
`major` | `minor` | `patch` | `prerelease` (update).
capabilitiesobjectrequired
Show 3 nestedHide nested
functions_addedobject[]
Show 2 nestedHide nested
agentstring
functionstring
models_changedobject[]
Show 3 nestedHide nested
agentstring
fromstring
tostring
workers_addedstring[]
countsobjectrequired
Show 11 nestedHide nested
addedinteger· uintrequiredmin 0
agentsinteger· uintrequiredmin 0
collisionsinteger· uintrequiredmin 0
conflictsinteger· uintrequiredmin 0
decisions_requiredinteger· uintrequiredmin 0
Files whose `default` is `null`.
functionsinteger· uintrequiredmin 0
modifiedinteger· uintrequiredmin 0
removedinteger· uintrequiredmin 0
skillsinteger· uintrequiredmin 0
unchangedinteger· uintrequiredmin 0
workersinteger· uintrequiredmin 0
created_atstringrequired
deprecationany of
Show 2 nestedHide nested
any of (2)
Variant 1
messagestring
replaced_bystring
Variant 2
valuenull
descriptionstring
expires_atstringrequired
filesobject[]required
Show 20 nestedHide nested
agentany of
Kit profile frontmatter (agents; the side this plan installs, or the removed one).
Show 2 nestedHide nested
any of (2)
Variant 1
colorstring
descriptionstring
extendsstring
functionsstring[]
hiddenboolean
iconstring
idstring
logostring
modelstring
namestring
pathstring
reasoning_effortstring
sha256string
size_bytesinteger· uint64min 0
skillsstring[]
Variant 2
valuenull
agent_changesany of
Frontmatter changes versus the installed version (modified agents).
Show 2 nestedHide nested
any of (2)
Variant 1
fieldsobject
Scalar fields that changed: `field → [from, to]`.
functions_addedstring[]
functions_removedstring[]
skills_addedstring[]
skills_removedstring[]
Variant 2
valuenull
basestring
Content hash the kit installed (the merge base).
body_changedboolean
changeone ofrequired
Show 2 nestedHide nested
one of (2)
Variant 1
valuestringenum added, modified, removed
Variant 2
valuestringenum kept
collisionany of
Show 2 nestedHide nested
any of (2)
Variant 1
kitstring
modifiedboolean
The owner's copy was edited locally.
ownerall ofrequired
Who owns the file at the path today.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum kit, worker, local, global, builtin
sha256string
sha256 of the file there now.
versionstring
workerstring
Variant 2
valuenull
conflictsinteger· uintmin 0
defaultany of
Applied when the caller decides nothing; `null` = a decision is required.
Show 2 nestedHide nested
any of (2)
Variant 1
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
Variant 2
valuenull
idstringrequired
Agent profile id, or skill id.
kindstringrequiredenum agent, skill
localone ofrequired
What the file is on disk right now, relative to the plan.
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum absent
Variant 2
valuestringenum intact
Variant 3
valuestringenum edited
Variant 4
valuestringenum missing
Variant 5
valuestringenum occupied
mergeany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum clean, conflicts
Variant 2
valuenull
notestring
One-line explanation for the review.
optionsone of[]required
Choices the apply accepts for this file.
Show 6 nestedHide nested
one of (6)
Variant 1
valuestringenum overwrite
Variant 2
valuestringenum keep
Variant 3
valuestringenum kit
Variant 4
valuestringenum mine
Variant 5
valuestringenum merged
Variant 6
valuestringenum remove
oursstring
Content hash of the local file when the plan was made.
pathstringrequired
Logical install path (`agents/<id>.md`, `skills/<handle>/<kit>/…`).
skillany of
Skill frontmatter (skills).
Show 2 nestedHide nested
any of (2)
Variant 1
descriptionstring
idstring
pathstring
sha256string
size_bytesinteger· uint64min 0
titlestring
typestring
used_bystring[]
Variant 2
valuenull
skippedboolean
The lock says the user kept someone else's file here.
sourcestringrequired
Path inside the kit (`agents/<id>.md`, `skills/…`).
theirsstring
Content hash of the kit's version this plan installs.
fromstring
Installed version (update, remove).
functionsobject[]required
Functions the kit's profiles preload, with the worker that provides each.
Show 6 nestedHide nested
descriptionstring
idstring
statusstring
used_bystring[]
workerstring
worker_versionstring
kindstringrequiredenum install, update, remove
kitstringrequired
licensestring
majorbooleanrequired
notesstring
plan_idstringrequired
published_atstring
registry_urlstringrequired
The kit's page in the registry web app.
repostring
requestedstringrequired
What was asked for (tag, version or range) — stored in the lock.
reviewstringrequired
Where a human reviews it.
tostring
Version this plan installs (install, update).
warningsobject[]required
Show 3 nestedHide nested
codestringrequired
messagestringrequired
pathstring
workersobject[]required
Show 13 nestedHide nested
actionone ofrequired
Show 5 nestedHide nested
one of (5)
Variant 1
valuestringenum none
Variant 2
valuestringenum add
Variant 3
valuestringenum update
Variant 4
valuestringenum redeclare
Variant 5
valuestringenum remove
containerstring
declaredstring
`version:` selector in the compose file.
descriptionstring
installedstring
Version Compose has installed.
namestringrequired
pathboolean
The operator's `path://` build; kits never manage it.
rangestring
Range the kit declares (absent for a worker the kit dropped).
range_fromstring
Range the installed kit version declared.
registry_urlstringrequired
tostring
Version the range resolves to in the registry today.
typestring
Worker type (`binary`, `image`, …).
used_bystring[]
Other installed kits that declare this worker.
Variant 2
valuenull
reportany of
any of (2)
Variant 1
agentsstring[]required
Agent profile ids this kit now provides.
agents_changedbooleanrequired
files_keptstring[]required
Files left as they are (kept, skipped, or mine).
files_mergedstring[]required
files_removedstring[]required
files_writtenstring[]required
fromstring
kindany of
Show 2 nestedHide nested
any of (2)
Variant 1
valuestringenum install, update, remove
Variant 2
valuenull
kitstringrequired
lock_pathstringrequired
plan_idstringrequired
skills_changedbooleanrequired
stepsobject[]required
Show 4 nestedHide nested
detailstring
idstringrequired
`workers` | `files` | `lock`.
labelstringrequired
statestringrequiredenum pending, running, done, failed, skipped
tostring
workers_addedstring[]required
workers_removedstring[]required
workers_updatedstring[]required
Variant 2
valuenull
statusone ofrequired
one of (4)
Variant 1
valuestringenum planned
Variant 2
valuestringenum applied
Variant 3
valuestringenum up_to_date
Variant 4
valuestringenum replanned

directory::on-config-change

Function

Internal: reload tunable iii-directory settings from the authoritative configuration when it changes.

Request

Empty object

Response

okbooleanrequired

directory::on-functions-change

Function

Internal: refresh the search catalog after the engine function set changes.

Request

eventstring

Response

okbooleanrequired

directory::pre-generate

Function

Internal: inject the conditional search hint into one harness generation.

Request

depthinteger· uint32requiredmin 0
generateobjectrequired
- exposeall of
  How the harness exposes functions to the model for this generation. Absent on harnesses that predate the field, which only ever exposed through agent_trigger by default.
  all of (1)
  Variant 1
  one of (2)
  Variant 1
  valuestringenum agent_trigger, native
  Variant 2
  valuestringenum other
- functions_generationinteger· uint64requiredmin 0
- messagesunknown[]required
- system_promptstringrequired
- toolsobject[]required
  descriptionstringrequired
  namestringrequired
  parametersunknownrequired
session_idstringrequired
stepinteger· uint64requiredmin 0
turn_idstringrequired

Response

annotationsobjectrequired
- directoryobjectrequired
  dataobjectrequired
  The durable transcript row for one hook pass. Coarse by design: outcome, reason, and counts only — no prompts, messages, tool contracts, session ids, or timings ever leave the hook.
  Show 4 nestedHide nested
  allowed_functionsinteger· uint64requiredmin 0
  functions_generationinteger· uint64requiredmin 0
  outcomestringrequiredenum hint_injected, skipped
  reasonany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  valuestringenum search_unavailable, already_searched, narrow_surface, already_operating, task_guided, hint_already_sent
  Variant 2
  valuenull
  summarystringrequired
  typestringrequired
  versioninteger· uint8requiredmin 0
decisionstringrequired
mutationsany of
any of (2)
Variant 1
append_messagesunknown[]required
Ephemeral tail messages for this generation only. The hint rides here rather than as a system-prompt mutation: the system prompt is the provider's first input item, and a once-per-turn append there invalidated the entire prompt-cache prefix twice per turn.
Variant 2
valuenull

directory::registry::workers::info

Function

Preview one registry worker before installing: envelope (version, kind, dependencies, config), its public function and trigger names with descriptions, and skill file paths. Schemas are omitted — install, then read contracts with engine::functions::info. Pass `readme: true` for the README prose; `version` or `tag` (default tag "latest").

Request

namestringrequired
Worker name in the registry (e.g. `"resend"`).
readmeboolean
Include the README markdown (10–25 KB for most workers). Off by default: the card is for judging fit before `compose::add`; the README is for setup prose and examples.
tagstring
versionstring
Mutually exclusive with `tag`. If neither is provided we fall back to `tag: "latest"`.

Response

api_referenceobjectrequired
- functionsobject[]
  descriptionstring
  metadataunknown
  namestringrequired
  request_schemaunknown
  response_schemaunknown
- triggersobject[]
  descriptionstring
  invocation_schemaunknown
  metadataunknown
  namestringrequired
  return_schemaunknown
readmestring
skills_treeobjectrequired
- skillsobject[]
  pathstringrequired
workerall ofrequired
Same shape as `directory::registry::workers::list` rows (and the engine's `engine::workers::list` rows for the shared core fields).
all of (1)
Variant 1
authorany of
Show 2 nestedHide nested
any of (2)
Variant 1
namestring
pfpstring
Profile picture URL. `null` when the author hasn't uploaded one.
verifiedboolean
Variant 2
valuenull
configunknown
Free-form runtime configuration block from the publish payload.
dependenciesobject[]
Show 2 nestedHide nested
namestringrequired
versionstringrequired
descriptionstring
imagestring
Container image tag, populated only for `type=image` workers.
namestringrequired
repostring
supported_targetsstring[]
total_downloadsinteger· uint64min 0
typestring
Worker kind — `binary`, `image`, or `engine`.
versionstring
Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).

directory::registry::workers::list

Function

List workers from the public registry, optionally filtered by fuzzy `search` (default order: downloads). Cursor-paginated: pass back `pagination.next_cursor` as `cursor`.

Request

cursorstring
Cursor from a previous call's `pagination.next_cursor`; omit for the first page.
searchstring
Optional free-text query, fuzzy-matched by the registry; omitted means ordered by downloads.

Response

paginationobjectrequired
Pagination envelope returned alongside a worker-list page. Mirrors the OpenAPI `Pagination` schema.
- has_moreboolean
- next_cursorstring
  Opaque cursor for the next page. `null` on the last page.
- page_sizeinteger· uint32min 0
  Server-authored page size. The client cannot override this.
workersobject[]required
- authorany of
  any of (2)
  Variant 1
  namestring
  pfpstring
  Profile picture URL. `null` when the author hasn't uploaded one.
  verifiedboolean
  Variant 2
  valuenull
- configunknown
  Free-form runtime configuration block from the publish payload.
- dependenciesobject[]
  namestringrequired
  versionstringrequired
- descriptionstring
- imagestring
  Container image tag, populated only for `type=image` workers.
- namestringrequired
- repostring
- supported_targetsstring[]
- total_downloadsinteger· uint64min 0
- typestring
  Worker kind — `binary`, `image`, or `engine`.
- versionstring
  Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).

directory::search_functions

Function

Search available functions for the unmet external capabilities of a step (usually one to six, at most eighteen per call); returns compact function-id candidates grouped by worker, plus matching installed skill documents under `skills` and registered trigger bindings under `triggers`.

Request

capabilitiesstring[]requiredmin 1 chars · min 1 items
Non-empty capability searches derived from the goal and current execution state, usually one to six and at most eighteen per call (searched in batches of six). For one search at each decision point, include all unmet external capabilities once. Exclude intrinsic reasoning, summarization, planning, or formatting, and do not repeat needs already represented or satisfied. Requests to summarize provided text or content are ignored. Write every entry in English, translating non-English user requests while preserving proper names, URLs, and function IDs.

Response

guidancestringrequired
installableobject[]
Matching workers from the private registry. Their functions are NOT callable until the worker is installed.
- descriptionstringrequired
- functionsobject[]required
  Compact candidates only. If the remaining task needs these functions, reuse their IDs and fetch the required contracts through `engine::functions::info`.
  descriptionstringrequired
  First description sentence, capped at 160 bytes.
  function_idstringrequired
- installall ofrequired
  The `compose::add` target and payload; agent-trigger callers add `description`.
  all of (1)
  Variant 1
  functionstringrequired
  payloadunknownrequired
- namestringrequired
- versionstringrequired
latency_msnumber· doublerequired
search_modeall ofrequired
The search mode that actually produced these results: `judge`, `hybrid` or `lexical`. It can be lower than the configured mode when a batch fell back (judge worker absent or failing, or no local model).
all of (1)
Variant 1
valuestringenum lexical, hybrid, judge
skillsobject[]
Installed skill documents matching the capabilities. Read one with `directory::skills::get { id }` before acting on it.
- descriptionstringrequired
  First description sentence, capped at 160 bytes.
- idstringrequired
  Pass to `directory::skills::get { id }` to read the document.
- titlestringrequired
triggersobject[]
Registered trigger bindings matching the capabilities: what already fires, schedules, or hooks a function for them.
- configunknownrequired
  The binding's configuration (cron expression, hook filters, …).
- function_idstringrequired
  The function the trigger runs; inspect it with `engine::functions::info`.
- idstringrequired
- trigger_typestringrequired
- worker_namestring
workersobject[]required
- functionsobject[]required
  descriptionstringrequired
  First description sentence, capped at 160 bytes.
  function_idstringrequired
- namespacestringrequired

directory::skills::create

Function

Create a new skill at <skills_folder>/<id>.md from full-file markdown (frontmatter optional, non-empty body). Rejects ids or paths that already exist, including system-installed skills. Use directory::skills::update to edit existing skills.

Request

contentstringrequired
Full file content, frontmatter optional; only the size cap and a non-empty body are enforced.
idstringrequired
New skill id, used as the file path under skills_folder (`/`-separated segments of `[a-z0-9_-]`), not already taken.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
function_idstring
Frontmatter `function_id:` of the content, `null` when absent.
idstringrequired
The created skill's id (normalized form of the input id).
modified_atstringrequired
File mtime after the write, RFC 3339.
titlestringrequired
Title resolved from the content (frontmatter `title:`, then `name:`, then body H1, then the id) — what `list` rows will show.
typestring
Frontmatter `type:` of the content, `null` when absent.

directory::skills::delete

Function

Delete one existing skill's markdown file by id (same id forms as directory::skills::get); refuses read-only system-installed skills.

Request

idstringrequired
Existing skill id — the same forms `directory::skills::get` accepts (bare id, `<id>.md`, `SKILL(S).md`, `iii://<id>`).

Response

idstringrequired
Id of the skill whose file was removed — the RESOLVED on-disk id (e.g. `ns/index` for input `ns`), not the input form.

directory::skills::download

Function

Download skills into skills_folder from exactly one source: {repo, skill, branch?} clones a GitHub skill folder; {worker, version?|tag?} pulls from the workers registry. Prefer the explicit download_from_registry / download_from_repo.

Request

branchstring
Source A: branch to clone. Defaults to `"main"`. Pass `"master"` (or any other branch name) for repos whose default branch is not `main`.
repostring
Source A: GitHub repo URL. Pair with `skill`.
skillstring
Source A: subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.
tagstring
Registry tag to pull (default `latest`); mutually exclusive with `version`.
versionstring
Source B: explicit semver to pull. Mutually exclusive with `tag`.
workerstring
Source B: workers registry name. Pair with exactly one of `version` / `tag`.

Response

agents_skippedobject[]required
Agent profiles the bundle ships but an installed kit owns: left as the kit wrote them (kit profiles take precedence).
- idstringrequired
- owned_bystringrequired
  The owning kit, `<handle>/<name>`.
agents_writtenstring[]required
namespacestringrequired
skills_writtenstring[]required
sourceunknownrequired
system_prompts_writtenstring[]required

directory::skills::download_from_registry

Function

Download one worker's directory bundle from the workers registry into skills_folder. `worker` is required; pass `version` (exact semver) or `tag` (default "latest"), not both. Files are overwritten file-by-file.

Request

tagstring
Registry tag to pull (e.g. `"latest"`). Mutually exclusive with `version`. Defaults to `"latest"` when neither is provided.
versionstring
Explicit semver to pull. Mutually exclusive with `tag`.
workerstringrequired
Worker name in the registry (e.g. `"shell"`).

Response

agents_skippedobject[]required
Agent profiles the bundle ships but an installed kit owns: left as the kit wrote them (kit profiles take precedence).
- idstringrequired
- owned_bystringrequired
  The owning kit, `<handle>/<name>`.
agents_writtenstring[]required
namespacestringrequired
skills_writtenstring[]required
sourceunknownrequired
system_prompts_writtenstring[]required

directory::skills::download_from_repo

Function

Download one skill folder from a GitHub repo into skills_folder: `repo` (https/ssh/git@ URL) and `skill` (subfolder under `skills/`, also the destination namespace) are required; `branch` defaults to "main".

Request

branchstring
Branch to clone. Defaults to `"main"`.
repostringrequired
GitHub repo URL (validated: https / ssh / git@ only).
skillstringrequired
Subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.

Response

agents_skippedobject[]required
Agent profiles the bundle ships but an installed kit owns: left as the kit wrote them (kit profiles take precedence).
- idstringrequired
- owned_bystringrequired
  The owning kit, `<handle>/<name>`.
agents_writtenstring[]required
namespacestringrequired
skills_writtenstring[]required
sourceunknownrequired
system_prompts_writtenstring[]required

directory::skills::get

Function

Fetch one skill by id and return its raw markdown body plus id, title, type, function_id, and modified_at. A worker overview is addressed by the bare worker name; `<id>.md` and `iii://<id>` forms are accepted. On a miss, D110 names the closest ids.

Request

idstringrequired
Skill id as returned by directory::skills::list (e.g. `directory/skills/list`); `<id>.md` and `iii://<id>` forms are accepted.
rawboolean
When true, also return the exact on-disk file (frontmatter included) as `raw`, ready for directory::skills::update.

Response

bodystringrequired
Raw markdown body (post-frontmatter) from disk. Note: there is no `description` field. `description` is the body's first paragraph, which is already inside `body` — every caller asking for the body would otherwise pay for the prefix twice. Use `directory::skills::list` rows when you want the teaser without the full body.
disable_model_invocationbooleanrequired
Whether model-facing indexes should omit this skill from invocation candidates.
function_idstring
Frontmatter `function_id:` when present — the canonical bus function id this skill documents (e.g. `sandbox::create`). The response's `id` field is the SKILL path on disk; `function_id` is what the agent should pass to `agent_trigger`. `null` when the skill isn't 1:1 with a single function.
idstringrequired
modified_atstringrequired
File mtime as RFC 3339.
pathstringrequired
Absolute on-disk path of the skill file. Its parent directory is the skill's base directory — where payload the body references by relative path (`scripts/`, `reference/`, agent-skills convention) lives. Only meaningful to callers sharing this worker's filesystem (shell/file tools on the same machine).
rawstring
FULL on-disk file content (frontmatter block included). Present only when the request set `raw: true`. This is the exact string to hand back to `directory::skills::update`; fallback notes that `get` may prepend to `body` are never added here.
titlestringrequired
Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.
typestring
Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.

directory::skills::index

Function

Read a per-worker overview: one markdown block per installed worker (title, first paragraph, and the directory::skills::get call for the reference). For per-skill rows use directory::skills::list.

Request

Empty object

Response

bodystringrequired
Rendered markdown document — one short `## <title>` block per installed worker (each worker's root overview doc, whether or not it declares frontmatter `type: index`), carrying the worker's first-paragraph overview and a `directory::skills::get` call to read the full reference. Sorted lex by id.
workers_countinteger· uintrequiredmin 0
Number of worker entries rendered (i.e. the count of worker overview rows that survived the filter). Cheap sanity check that doesn't require re-parsing the body.

directory::skills::list

Function

List skills, one row per skill (id, title, type, function_id, description, bytes, modified_at). Filters: `search` (substring on id/title/description), `prefix` (worker namespace), `type`; `include_description: false` for lighter rows. Pass a row's `function_id`, not its `id`, to agent_trigger.

Request

include_descriptionboolean
When `false`, the response omits the first-paragraph `description` field on every row. Useful for token-light pickers that only need `id` + `title` + `type`. Default `true`.
prefixstring
Exact prefix match against `id`. Combine with `search` to scope a fuzzy match to one worker namespace, e.g. `prefix: "sandbox/"`.
searchstring
Case-insensitive substring match against `id`, `title`, and (when `include_description` is true) the first body paragraph. Omitted rows are filtered out cheaply on the FsSkill { id } pass before the per-file frontmatter read, so a narrowed list is dramatically cheaper for the caller than the unfiltered one.
typestring
Exact match against the frontmatter `type:` field (`index`, `how-to`, `reference`, ...). `null` for entries with no frontmatter `type:`.

Response

skillsobject[]required
- bytesinteger· uintrequiredmin 0
- descriptionstringrequired
  First paragraph of the body, empty when the file has only headings. Also empty when the caller passed `list { include_description: false }` for a token-light row.
- disable_model_invocationbooleanrequired
  Whether model-facing indexes should omit this skill from invocation candidates.
- function_idstring
  Frontmatter `function_id:` when present — the canonical bus function id this skill documents (e.g. `sandbox::create`). The row's `id` field is the SKILL path on disk (e.g. `sandbox/skills/sandbox/create`); `function_id` is what an agent should pass to `agent_trigger`. `null` for skills that aren't 1:1 with a single function (index/reference).
- idstringrequired
- modified_atstringrequired
  File mtime as RFC 3339 (best effort; empty if unavailable).
- titlestringrequired
  Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.
- typestring
  Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.

directory::skills::update

Function

Overwrite one existing skill with full-file markdown (pass back the `raw` from directory::skills::get { raw: true }, edited). Never creates files; refuses read-only system-installed skills.

Request

contentstringrequired
FULL new file content, frontmatter block included — the string `directory::skills::get { raw: true }` returns, edited.
idstringrequired
Skill id to overwrite (same forms directory::skills::get accepts); the file must already exist.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
function_idstring
Frontmatter `function_id:` of the new content, `null` when absent.
idstringrequired
The id that was updated (normalized form of the input id).
modified_atstringrequired
File mtime after the write, RFC 3339.
titlestringrequired
Title resolved from the NEW content (frontmatter `title:`, then body H1, then the id) — what `list` rows will now show.
typestring
Frontmatter `type:` of the new content, `null` when absent.

directory::system-prompts::create

Function

Create a new system prompt at <skills_folder>/system-prompts/<name>.md from full-file markdown (non-empty frontmatter `description` required; a declared `name` must match). Rejects names or paths that already exist.

Request

contentstringrequired
Full file content, frontmatter included; `description` is required and a declared `name` must match.
namestringrequired
New system prompt name, used as the file stem; same charset as listed names and not already taken.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
descriptionstringrequired
Description parsed from the frontmatter.
modified_atstringrequired
File mtime after the write, RFC 3339.
namestringrequired
The created system prompt's name (as requested).

directory::system-prompts::delete

Function

Permanently delete one EXISTING filesystem-backed system prompt by name. Resolves against the same merged scan as directory::system-prompts::list, removes only that prompt's markdown file, and fans out directory::system-prompts::on-change with { op: "delete" }.

Request

namestringrequired
Existing system prompt name, as returned by `directory::system-prompts::list`.

Response

namestringrequired
Name of the system prompt whose file was removed.

directory::system-prompts::get

Function

Fetch one system prompt by name — a filesystem-backed entry, or a worker-bundled one (`builtin: true`) when no local file shadows it. Returns the raw markdown body plus name, description, and modified_at — no envelope, no templating.

Request

namestringrequired
rawboolean
When `true`, the response includes the full on-disk file content (frontmatter included) as `raw`, ready for `directory::system-prompts::update`.

Response

bodystringrequired
builtinbooleanrequired
Served from the copy bundled with the worker (no local file yet): an update creates the local file.
descriptionstringrequired
modified_atstringrequired
namestringrequired
rawstring

directory::system-prompts::list

Function

List system prompts (name, description, modified_at) from skills_folder's `system-prompts/` plus the ones bundled with this worker (`builtin: true` until a local file shadows one).

Request

Empty object

Response

promptsobject[]required
- builtinbooleanrequired
  Bundled with the worker, no file behind it: editing it creates the local file (which then shadows this entry); there is nothing to delete.
- descriptionstringrequired
- modified_atstringrequired
- namestringrequired

directory::system-prompts::update

Function

Overwrite one existing system prompt with full-file markdown; the frontmatter must keep a non-empty `description`. Updating a bundled prompt (`builtin: true`) creates a local file that shadows it. Returns the effective name (frontmatter `name:` wins over the file stem).

Request

contentstringrequired
Full file content, frontmatter included; `description` must stay non-empty.
namestringrequired
System prompt name to overwrite, as listed; a bundled prompt (`builtin: true`) is copied to a local file first.

Response

bytesinteger· uintrequiredmin 0
Bytes written.
descriptionstringrequired
Description parsed from the new frontmatter.
modified_atstringrequired
File mtime after the write, RFC 3339.
namestringrequired
The system prompt's EFFECTIVE name after the write: the new frontmatter `name:` when declared, otherwise the file stem. Differs from the input name when the update renames the system prompt.

iii-directory::ui-content

Function

Serve the iii-directory worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request

pathstringrequired
The asset path from the trigger config (e.g. `state/page.js`).

Response

contentstringrequired
The asset source, verbatim.
content_typestringrequired
MIME type the console should serve the asset with.

Triggers4

directory::agents::on-change

Trigger

Fires after a directory::skills::download that wrote at least one agent profile, or a directory::agents::update, create, or delete. Also fires with { op: "external" } when a watched agents file changes on disk outside this worker.

Invocation

valueunknown

Return

valueunknown

directory::kits::on-change

Trigger

Fires when kit state changes: a plan is created or discarded ({ op: "plan" | "discard", kit, plan_id }), an apply makes progress or finishes ({ op: "progress", plan_id, steps } / { op: "apply", kit, plan_id }), or an update check finds a different set of available updates ({ op: "updates" }).

Invocation

valueunknown

Return

valueunknown

directory::skills::on-change

Trigger

Fires after a directory::skills::download that wrote at least one skill markdown file, or a directory::skills::update, create, or delete. Also fires with { op: "external" } when a watched skills root changes on disk outside this worker — including the read-only agents skills root, when that root exists at startup.

Invocation

valueunknown

Return

valueunknown

directory::system-prompts::on-change

Trigger

Fires after a directory::skills::download that wrote at least one system prompt, or a directory::system-prompts::update, create, or delete. Also fires with { op: "external" } when a watched system-prompts root changes on disk outside this worker.

Invocation

valueunknown

Return

valueunknown

Install

Functions42

Triggers4

Search the registry