iii-directory

Full file content, frontmatter included; `name` is required, the body is the system prompt and may be empty.

New profile id, used as the file stem; lowercase ASCII, digits, `-` and `_` only, and not already taken.

Bytes written.

File mtime after the write, RFC 3339.

Display name parsed from the (new) frontmatter.

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

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

Bundled with the worker, no file behind it (see `list`).

Harness subagent color token (closed set, validated at write time); `null` = neutral.

Parent profile id (`extends:`), as declared; `null` = none.

Harness subagent icon token (closed set, validated at write time); `null` = caller picks.

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.

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.

File mtime as RFC 3339; empty for a bundled profile.

FULL on-disk file content (this profile's own file, ancestors excluded). Present only when the request set `raw: true`.

Provider-native reasoning effort paired with `model`, resolved through `extends`; `null` = the model/provider default. Served verbatim and validated at use time.

The skill filter, resolved through `extends` (the nearest profile with a non-empty filter). Empty = every skill.

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.

Filter entries that resolve to no currently visible skill. Warnings — the agent profile still loads.

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

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

Bytes written.

File mtime after the write, RFC 3339.

Display name parsed from the (new) frontmatter.

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

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

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.

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

Cursor from a previous call's `pagination.next_cursor`; omit for the first page.

Optional free-text query, fuzzy-matched by the registry; omitted means ordered by downloads.

Pagination envelope returned alongside a worker-list page. Mirrors the OpenAPI `Pagination` schema.

One to six non-empty capability searches derived from the goal and current execution state. 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.

Matching workers from the private registry. Their functions are NOT callable until the worker is installed.

Full file content, frontmatter optional; only the size cap and a non-empty body are enforced.

New skill id, used as the file path under skills_folder (`/`-separated segments of `[a-z0-9_-]`), not already taken.

Bytes written.

Frontmatter `function_id:` of the content, `null` when absent.

The created skill's id (normalized form of the input id).

File mtime after the write, RFC 3339.

Title resolved from the content (frontmatter `title:`, then `name:`, then body H1, then the id) — what `list` rows will show.

Frontmatter `type:` of the content, `null` when absent.

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

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

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

Registry tag to pull (default `latest`); mutually exclusive with `version`.

Source B: explicit semver to pull. Mutually exclusive with `tag`.

Source B: workers registry name. Pair with exactly one of `version` / `tag`.

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"`).

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

Skill id as returned by directory::skills::list (e.g. `directory/skills/list`); `<id>.md` and `iii://<id>` forms are accepted.

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

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.

Whether model-facing indexes should omit this skill from invocation candidates.

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.

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

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.

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.

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.

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:`.

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

Skill id to overwrite (same forms directory::skills::get accepts); the file must already exist.

Bytes written.

Frontmatter `function_id:` of the new content, `null` when absent.

The id that was updated (normalized form of the input id).

File mtime after the write, RFC 3339.

Title resolved from the NEW content (frontmatter `title:`, then body H1, then the id) — what `list` rows will now show.

Frontmatter `type:` of the new content, `null` when absent.

Full file content, frontmatter included; `description` is required and a declared `name` must match.

New system prompt name, used as the file stem; same charset as listed names and not already taken.

Bytes written.

Description parsed from the frontmatter.

File mtime after the write, RFC 3339.

The created system prompt's name (as requested).

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

Name of the system prompt whose file was removed.

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

Served from the copy bundled with the worker (no local file yet): an update creates the local file.

Full file content, frontmatter included; `description` must stay non-empty.

System prompt name to overwrite, as listed; a bundled prompt (`builtin: true`) is copied to a local file first.

Bytes written.

Description parsed from the new frontmatter.

File mtime after the write, RFC 3339.

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.

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

The asset source, verbatim.

MIME type the console should serve the asset with.