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.
iii trigger compose::add worker=iii-directory@0.8.1Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Fetch one filesystem-backed prompt by name. Returns the raw markdown body plus name, description, and modified_at — no envelope, no templating.
Raw markdown body (post-frontmatter) from disk.
File mtime as RFC 3339.
List filesystem-backed prompts (name, description, modified_at) from skills_folder.
File mtime as RFC 3339.
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.
Branch to clone. Defaults to `"main"`.
GitHub repo URL (validated: https / ssh / git@ only).
Subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.
Internal: auto-download skills on worker add event.
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.
Source A: branch to clone. Defaults to `"main"`. Pass `"master"` (or any other branch name) for repos whose default branch is not `main`.
Source A: GitHub repo URL. Pair with `skill`.
Source A: subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.
Source B: registry tag to pull (e.g. `latest`). Mutually exclusive with `version`. Defaults to `"latest"` when neither `version` nor `tag` is provided.
Source B: explicit semver to pull. Mutually exclusive with `tag`.
Source B: workers registry name. Pair with exactly one of `version` / `tag`.
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.
Registry tag to pull (e.g. `"latest"`). Mutually exclusive with `version`. Defaults to `"latest"` when neither is provided.
Explicit semver to pull. Mutually exclusive with `tag`.
Worker name in the registry (e.g. `"shell"`).
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).
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.
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`.
Pagination envelope returned alongside a worker-list page. Mirrors the OpenAPI `Pagination` schema.
Opaque cursor for the next page. `null` on the last page.
Server-authored page size. The client cannot override this.
Profile picture URL. `null` when the author hasn't uploaded one.
Free-form runtime configuration block from the publish payload.
Container image tag, populated only for `type=image` workers.
Worker kind — `binary`, `image`, or `engine`.
Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).
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`.
Worker name in the registry (e.g. `"resend"`).
Mutually exclusive with `tag`. If neither is provided we fall back to `tag: "latest"`.
Same shape as `directory::registry::workers::list` rows (and the engine's `engine::workers::list` rows for the shared core fields).
Profile picture URL. `null` when the author hasn't uploaded one.
Free-form runtime configuration block from the publish payload.
Container image tag, populated only for `type=image` workers.
Worker kind — `binary`, `image`, or `engine`.
Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).
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.
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.
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.
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.
Fully-qualified function id on the bus (e.g. `sandbox::create`).
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.
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.
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.
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.
File mtime as RFC 3339.
Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.
Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.
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).
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`.
Exact prefix match against `id`. Combine with `search` to scope a fuzzy match to one worker namespace, e.g. `prefix: "sandbox/"`.
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.
Exact match against the frontmatter `type:` field (`index`, `how-to`, `reference`, ...). `null` for entries with no frontmatter `type:`.
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.
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).
File mtime as RFC 3339 (best effort; empty if unavailable).
Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.
Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.
Fires after every successful directory::skills::download that wrote at least one prompt markdown file.
Fires after every successful directory::skills::download that wrote at least one skill markdown file.
Find workers, kits and executables, or jump to a page.