skip to content
iii / worker
$worker

iii-directory

v1.2.1

Engine introspection, workers registry proxy, filesystem-backed skills, system prompts, and agent profiles, plus lexical function search with a conditional pre-generate hint.

iiiverified
2,916 installs25 in 7d1 today
install
$iii trigger compose::add worker=iii-directory@1.2.1
binarylicense: Apache-2.0agentsdirectoryfunctionsintrospectregistrysearchskills
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
22functions3triggers1skills1depsv1.2.1version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

22

directory::__on_worker_added

function

Internal: auto-download skills on worker add event.

request
  • workerstring
response
  • okbooleanrequired

directory::engine::functions::info

function

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

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::on-config-change

function

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

request
empty object
response
  • okbooleanrequired

directory::prompts::create

function

Create a NEW command-template prompt at <skills_folder>/prompts/<name>.md from full-file markdown content (frontmatter block included; a non-empty `description` is required, and a declared frontmatter `name` must match the requested name). Rejects names that already exist anywhere in the merged command-prompt scan, or a target path that already exists on disk (even one the scanner would skip). The write is atomic and fans out directory::prompts::on-change with { op: "create" }. Use directory::prompts::update to edit existing prompts.

request
  • contentstringrequired

    FULL file content, frontmatter block included — the same form `directory::prompts::update` takes. Frontmatter must carry a non-empty `description`; a declared `name` must match the requested name.

  • namestringrequired

    New prompt name — becomes the file stem (`<skills_folder>/prompts/<name>.md` for command templates, `<skills_folder>/system-prompts/<name>.md` for system prompts). Same charset rules as list/get names; must not collide with an existing prompt of the SAME kind (a command prompt and a system prompt may share a name).

response
  • bytesinteger· uintrequiredmin 0

    Bytes written.

  • descriptionstringrequired

    Description parsed from the frontmatter.

  • modified_atstringrequired

    File mtime after the write, RFC 3339.

  • namestringrequired

    The created prompt's name (as requested).

directory::prompts::get

function

Fetch one filesystem-backed command-template prompt by name. 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 block included) as `raw`. For editors that need to round-trip the exact file (`directory::prompts::update` takes the same full-file form); agent readers should leave this unset and use `body`.

response
  • bodystringrequired

    Raw markdown body (post-frontmatter) from disk.

  • descriptionstringrequired
  • modified_atstringrequired

    File mtime as RFC 3339.

  • namestringrequired
  • rawstring

    FULL on-disk file content (frontmatter included). Present only when the request set `raw: true` — the exact string to hand back to `directory::prompts::update`.

directory::prompts::list

function

List filesystem-backed command-template prompts (name, description, modified_at) from skills_folder (`prompts/` path segment).

request
empty object
response
  • promptsobject[]required
    • descriptionstringrequired
    • modified_atstringrequired

      File mtime as RFC 3339.

    • namestringrequired

directory::prompts::update

function

Overwrite one EXISTING filesystem-backed prompt with new full-file markdown content. The frontmatter must keep a non-empty `description` (and a valid `name` when it declares one) — the same rules the scanner enforces, so an update can never produce a file the next directory::prompts::list would skip. The write is atomic and fans out directory::prompts::on-change with { op: "update" }. Returns the prompt's effective name after the write (frontmatter `name:` wins over the file stem). Command templates only — system prompts have their own directory::system-prompts::* family.

request
  • contentstringrequired

    FULL new file content, frontmatter block included. The frontmatter must keep a non-empty `description` — a prompt without one would be skipped by the next scan.

  • namestringrequired

    Prompt name to overwrite, as returned by the matching list for this kind (`directory::prompts::list` for command templates, `directory::system-prompts::list` for system prompts). The target file must already exist.

response
  • bytesinteger· uintrequiredmin 0

    Bytes written.

  • descriptionstringrequired

    Description parsed from the new frontmatter.

  • modified_atstringrequired

    File mtime after the write, RFC 3339.

  • namestringrequired

    The 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 prompt.

directory::registry::workers::info

function

Fetch full registry metadata for one worker: worker envelope (same core fields as the engine's `engine::workers::list` row shape, plus registry-only `type` / `config` / `supported_targets` / `total_downloads` / `dependencies` / `image`), readme, full API reference (functions + triggers schemas), and the tree of skill / prompt file paths fetched from the registry's /w/{slug}/skills endpoint. Pass either `version` or `tag` (defaults to tag="latest"). Results are cached for `registry_cache_ttl_ms`.

request
  • namestringrequired

    Worker name in the registry (e.g. `"resend"`).

  • 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
    • promptsobject[]
      • descriptionstring
      • namestringrequired
    • 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
      … expand 2 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[]
      … expand 2 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 (api.workers.iii.dev). Optional free-text `search` is matched fuzzily by the registry; omit it to browse by `total_downloads DESC`. Pagination is cursor-based with a server-authored page size — pass back `pagination.next_cursor` as `cursor` to fetch the next page. Shares the core `name` / `description` / `version` fields with the engine's `engine::workers::list`. Results are cached for `registry_cache_ttl_ms` (default 60s).

request
  • cursorstring

    Opaque cursor returned by a previous call's `pagination.next_cursor`. Pass back verbatim to fetch the next page; omit (or pass `null`) to fetch the first page.

  • searchstring

    Optional free-text query. Forwarded to the registry as `?search=…`; the registry ranks results by `pg_trgm` similarity against `lower(name)` and `lower(description)`. When omitted, results are ordered by `total_downloads DESC`.

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::skills::download

function

Download skills + prompts into skills_folder from EITHER source. Prefer the explicit directory::skills::download_from_registry / directory::skills::download_from_repo, whose schemas can't be mixed up. Pass {repo, skill, branch?} to clone one skill folder from a GitHub repo (branch defaults to "main"), or {worker, version?|tag?} to pull from the workers registry (tag defaults to "latest"). Specify exactly ONE source set. Files in the destination namespace are overwritten file-by-file.

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

    Source B: registry tag to pull (e.g. `latest`). Mutually exclusive with `version`. Defaults to `"latest"` when neither `version` nor `tag` is provided.

  • 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
  • namespacestringrequired
  • prompts_writtenstring[]required
  • skills_writtenstring[]required
  • sourceunknownrequired
  • system_prompts_writtenstring[]required

directory::skills::download_from_registry

function

Download one worker's skills + prompts from the workers registry into skills_folder. `worker` is required; pass either `version` (exact semver) OR `tag` (e.g. "latest", the default when both are omitted), not both. Files in the destination namespace are overwritten file-by-file. A missing worker returns a `D310 not_found` naming the next function to call. To pull from a GitHub repo instead, use directory::skills::download_from_repo.

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
  • namespacestringrequired
  • prompts_writtenstring[]required
  • 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` (the repo URL) and `skill` (the subfolder under `skills/`, which also names the destination namespace) are required; `branch` defaults to "main". The repo URL is validated (https / ssh / git@ only). To pull a published worker instead, use directory::skills::download_from_registry.

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
  • namespacestringrequired
  • prompts_writtenstring[]required
  • skills_writtenstring[]required
  • sourceunknownrequired
  • system_prompts_writtenstring[]required

directory::skills::get

function

Fetch one filesystem-backed 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 (e.g. "iii-sandbox") — that is the id `list`/`index` hand back. Input is forgiving: "iii-sandbox/index", "iii-sandbox/SKILL.md", a trailing ".md", and an iii:// prefix all resolve to the same overview; and if the exact id misses, the worker name is matched case-insensitively as a substring ("sandbox" finds "iii-sandbox"). `title` prefers frontmatter `title:` over the body H1; `type` is the frontmatter `type:`. There is no `description` field here (the body already opens with that paragraph) — use directory::skills::list for the teaser-only view. On a miss you get a `D110 not_found` message naming the closest ids and the next function to call.

request
  • idstringrequired

    Skill id (the same string returned by `directory::skills::list`, e.g. `"directory/skills/list"`). Two ergonomic variants are also accepted: the file-path form `<id>.md` (the trailing `.md` is stripped) and the legacy `iii://{id}` URI form. Other URI schemes are rejected. The filename `SKILLS.md` is aliased to `index.md` to match the filesystem scanner.

  • rawboolean

    When `true`, the response includes the FULL on-disk file content (frontmatter block included) as `raw`. For editors that need to round-trip the exact file (`directory::skills::update` takes the same full-file form); agent readers should leave this unset and use `body`.

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.

  • 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.

  • 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

Render a per-WORKER overview: one short markdown block per installed worker (each worker's root overview doc `<ns>/index`, whether or not it declares frontmatter `type: index`). Each block is a `## <worker title>` heading, the first paragraph of that worker's overview, and a `directory::skills::get` call to read the full reference. Token-light by design and intended for system-prompt injection; for individual per-SKILL rows call 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 as one row PER SKILL (id, title, type, function_id, description, bytes, modified_at) from skills_folder — use this when you need individual skill ids. A worker overview row's `id` is the bare worker name (e.g. `iii-sandbox`); pass it straight to directory::skills::get. For a per-WORKER overview instead, call directory::skills::index. Filters: `search` (case-insens. substring vs id+title+description), `prefix` (worker-namespace prefix; matches the overview row and its sub-skills), `type` (exact frontmatter type match). Pass `include_description: false` for token-light id+title+type rows (default: descriptions included). `title` prefers frontmatter `title:` over the body H1. Each row's `function_id` is the callable bus id (e.g. `sandbox::create`) — pass THAT to agent_trigger, not the row's `id` (which is a documentation address).

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.

    • 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 filesystem-backed skill with new full-file markdown content (frontmatter block included — pass back the `raw` field from directory::skills::get { raw: true }, edited). Accepts the same id forms as `get`. Never creates files (use directory::skills::download to materialize a bundle). Content is validated against the read invariants (size cap, non-empty body after frontmatter); the write is atomic and fans out directory::skills::on-change with { op: "update" }.

request
  • contentstringrequired

    FULL new file content, frontmatter block included — the string `directory::skills::get { raw: true }` returns, edited.

  • idstringrequired

    Skill id to overwrite — the same forms `directory::skills::get` accepts (bare id, `<id>.md`, `SKILL(S).md`, `iii://<id>`). The target file must already exist; update never creates skills.

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 content (frontmatter block included; a non-empty `description` is required, and a declared frontmatter `name` must match the requested name). Rejects names that already exist anywhere in the merged system-prompt scan, or a target path that already exists on disk (even one the scanner would skip). The write is atomic and fans out directory::system-prompts::on-change with { op: "create" }. Use directory::system-prompts::update to edit existing system prompts.

request
  • contentstringrequired

    FULL file content, frontmatter block included — the same form `directory::prompts::update` takes. Frontmatter must carry a non-empty `description`; a declared `name` must match the requested name.

  • namestringrequired

    New prompt name — becomes the file stem (`<skills_folder>/prompts/<name>.md` for command templates, `<skills_folder>/system-prompts/<name>.md` for system prompts). Same charset rules as list/get names; must not collide with an existing prompt of the SAME kind (a command prompt and a system prompt may share a name).

response
  • bytesinteger· uintrequiredmin 0

    Bytes written.

  • descriptionstringrequired

    Description parsed from the frontmatter.

  • modified_atstringrequired

    File mtime after the write, RFC 3339.

  • namestringrequired

    The created 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 filesystem-backed system prompt by name. 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 block included) as `raw`. For editors that need to round-trip the exact file (`directory::prompts::update` takes the same full-file form); agent readers should leave this unset and use `body`.

response
  • bodystringrequired

    Raw markdown body (post-frontmatter) from disk.

  • descriptionstringrequired
  • modified_atstringrequired

    File mtime as RFC 3339.

  • namestringrequired
  • rawstring

    FULL on-disk file content (frontmatter included). Present only when the request set `raw: true` — the exact string to hand back to `directory::prompts::update`.

directory::system-prompts::list

function

List filesystem-backed system prompts (name, description, modified_at) from skills_folder (`system-prompts/` path segment).

request
empty object
response
  • promptsobject[]required
    • descriptionstringrequired
    • modified_atstringrequired

      File mtime as RFC 3339.

    • namestringrequired

directory::system-prompts::update

function

Overwrite one EXISTING filesystem-backed system prompt with new full-file markdown content. The frontmatter must keep a non-empty `description` (and a valid `name` when it declares one) — the same rules the scanner enforces, so an update can never produce a file the next directory::system-prompts::list would skip. The write is atomic and fans out directory::system-prompts::on-change with { op: "update" }. Returns the system prompt's effective name after the write (frontmatter `name:` wins over the file stem). System prompts only — command templates have their own directory::prompts::* family.

request
  • contentstringrequired

    FULL new file content, frontmatter block included. The frontmatter must keep a non-empty `description` — a prompt without one would be skipped by the next scan.

  • namestringrequired

    Prompt name to overwrite, as returned by the matching list for this kind (`directory::prompts::list` for command templates, `directory::system-prompts::list` for system prompts). The target file must already exist.

response
  • bytesinteger· uintrequiredmin 0

    Bytes written.

  • descriptionstringrequired

    Description parsed from the new frontmatter.

  • modified_atstringrequired

    File mtime after the write, RFC 3339.

  • namestringrequired

    The 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 prompt.

iii-directory::ui-content

function

Serve the iii-directory worker's injected console UI assets (content function for its console:script / console:style 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.

triggers

3

directory::prompts::on-change

trigger

Fires after a directory::skills::download that wrote at least one command-template prompt, a directory::prompts::update, or a directory::prompts::create.

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.

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.

invocation
valueunknown
return
valueunknown