iii-directory

Internal: auto-download skills on worker add event.

Create a NEW agent profile at <agents_folder>/<id>.md from full-file markdown content (frontmatter block included; a non-empty `name` is required, `logo` is emoji-only, and the body — the system prompt — must be non-empty). Rejects ids that already exist in the configured agents folder, or a target path that already exists on disk. The write is atomic and fans out directory::agents::on-change with { op: "create" }.

Permanently delete one EXISTING agent profile by id. Resolves against the same merged scan as directory::agents::list, removes only that profile's markdown file, and fans out directory::agents::on-change with { op: "delete" }. Sessions already using this profile are not affected; the id just stops resolving for new sends.

Fetch one agent profile by id. Returns the system prompt (the file body, frontmatter stripped), display name, description, emoji logo, the skill filter plus unknown_skills (filter entries matching no visible skill — warnings, the profile still loads), model, reasoning_effort, icon, color, and modified_at. Pass raw: true to also get the exact on-disk file for editing with directory::agents::update.

List filesystem-backed agent profiles (id, display name, description, emoji logo, icon, color, model, reasoning_effort, skill_count, modified_at) from the configured agents folder. An agent profile is a reusable session identity: its file body is the system prompt. skill_count null = sessions using the profile can use every skill.

Overwrite one EXISTING agent profile with new full-file markdown content — the same rules the scanner enforces (required frontmatter with a non-empty `name`, emoji-only `logo`, non-empty body), so an update can never produce a file the next directory::agents::list would skip. The agent profile id stays the file stem; frontmatter `name` is only the display name. The write is atomic and fans out directory::agents::on-change with { op: "update" }.

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.

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

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

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

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

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

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

Search available functions for one to six external capabilities; returns compact function-id candidates grouped by worker.

Create a NEW filesystem-backed skill at <skills_folder>/<id>.md from full-file markdown content (frontmatter optional; only the size cap and a non-empty body are enforced, same as directory::skills::update). Rejects ids that already exist anywhere in the visible skill set (including system-installed agents skills), a target path that already exists on disk (even one the scanner would skip), ids in a namespace reserved by a system-installed agents skill, and — when filter_unregistered is on — ids the visibility filter would immediately hide. The write is atomic and fans out directory::skills::on-change with { op: "create" }. Use directory::skills::update to edit existing skills.

Permanently delete one EXISTING filesystem-backed skill by id. Accepts the same id forms as directory::skills::get, resolves against the same visible set as directory::skills::list, refuses read-only system-installed skills under agents_skills_folder, removes only that skill's markdown file (plus any parent directories the removal left empty), and fans out directory::skills::on-change with { op: "delete" }.

Download skills 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.

Download one worker's directory bundle 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.

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.

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.

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.

List skills as one row PER SKILL (id, title, type, function_id, disable_model_invocation, 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).

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::create to author one, or directory::skills::download to materialize a bundle). Refuses read-only system-installed skills under agents_skills_folder. 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" }.

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.

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" }.

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.

List system prompts (name, description, modified_at): filesystem-backed entries from skills_folder (`system-prompts/` path segment) plus the prompts bundled with this worker. A bundled prompt with no local file carries `builtin: true` — editing it via directory::system-prompts::update creates the local file, which then shadows the bundled copy.

Overwrite one EXISTING filesystem-backed system prompt with new full-file markdown content. Updating a worker-bundled prompt (`builtin: true` in the list) that has no local file yet copy-on-writes that file, which then shadows the bundled copy. 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).

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

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.

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.

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.