iii-directory

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

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.

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

Bytes written.

Description parsed from the frontmatter.

File mtime after the write, RFC 3339.

The created prompt's name (as requested).

Existing prompt name, as returned by the matching list function for this kind (`directory::prompts::list` / `directory::system-prompts::list`).

Name of the prompt whose file was removed.

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

Raw markdown body (post-frontmatter) from disk.

File mtime as RFC 3339.

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

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.

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.

Bytes written.

Description parsed from the new frontmatter.

File mtime after the write, RFC 3339.

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.

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

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.

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 registry workers from verified authors. Their functions are NOT callable until the worker is installed.

FULL file content, frontmatter block included — the same form `directory::skills::update` takes. Frontmatter is optional for skills; only the size cap and a non-empty body are enforced.

New skill id — becomes the file path (`<skills_folder>/<id>.md`), so it may contain `/`-separated segments (`[a-z0-9_-]` each). Must not collide with an existing visible skill (including system-installed agents skills) or an on-disk file at the target path.

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

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

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

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

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.

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

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 block included — the same form `directory::prompts::update` takes. Frontmatter must carry a non-empty `description`; a declared `name` must match the requested name.

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

Bytes written.

Description parsed from the frontmatter.

File mtime after the write, RFC 3339.

The created prompt's name (as requested).

Existing prompt name, as returned by the matching list function for this kind (`directory::prompts::list` / `directory::system-prompts::list`).

Name of the prompt whose file was removed.

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

Raw markdown body (post-frontmatter) from disk.

File mtime as RFC 3339.

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

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.

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.

Bytes written.

Description parsed from the new frontmatter.

File mtime after the write, RFC 3339.

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.

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.