Iii Directory

iii-directory

The directory worker is how an agent finds its way around the engine. It exposes five surfaces: function search (directory::search_functions), installed-worker docs (directory::skills::*), chat identity prompts (directory::system-prompts::*), reusable agent profiles (directory::agents::*), and the public worker catalogue (directory::registry::*). A download pulls a bundle onto disk, and each filesystem-backed family also takes direct create / update / delete calls — those are this worker's only writes. Everything else here is read-only.

Two kinds of id flow through this worker and they must not be mixed up. A callable id uses :: (directory::skills::get) and goes in the function: field of agent_trigger. A skill id uses / (iii-sandbox, agent-memory/observe) and names a document — pass it as the id argument to directory::skills::get. The ids that list and index print are skill ids; a worker's overview is the bare worker name (iii-sandbox, not iii-sandbox/index, and the iii- prefix is never dropped). Use the id you were given — do not invent one.

Only installed workers are visible. index, list, and get show on-disk skills for installed workers, plus this worker and the iii engine which are always present. A skill you know exists stays invisible until its worker is downloaded, so when one is missing, install it and look again. With auto_download enabled the worker subscribes to the engine worker add event and pulls a newly added worker's skills automatically, so freshly installed workers can appear without a manual download. System-installed agent skills under the read-only agents_skills_folder (.agents/skills under III_COMPOSE_DIR, or the process current directory when standalone) are also always visible in list/get — they are skills, not workers, so they never appear in index and update/delete refuse them.

When to Use

• You need functions for a step's unmet capabilities (usually one to six, at most eighteen) — directory::search_functions.
• You need to see which workers are installed — directory::skills::index (token-light; start here).
• You need to read a worker's overview or a deeper doc it linked to — directory::skills::get.
• You need to find a skill across the repo with filters — directory::skills::list.
• You need the system prompts the chat picker offers as an identity override — directory::system-prompts::list / get.
• You need a reusable agent profile (display name, emoji logo, skill selection, and its system prompt) — directory::agents::list / get.
• You are deciding whether to install a worker — directory::registry::workers::info is the pre-install card: public function/trigger names with descriptions, config, dependencies, skill paths (no schemas; readme: true adds the README). Contracts come from engine::functions::info after install.
• You need to install a published worker's skills — directory::skills::download_from_registry.
• You can only reach the directory:: namespace but need one engine function's exact schema — directory::engine::functions::info.

Boundaries

• Only installed workers are visible. If the engine daemon is unreachable at boot, filtering is skipped and everything on disk is shown instead.
• Writes are downloads plus the per-family create / update / delete calls; every read function leaves disk untouched.
• Skills under agents_skills_folder are read-only: update/delete refuse them (D116), and create refuses ids in their namespaces (D115). Edit them with their owning tool, or copy one into skills_folder on disk to fork it.
• Not the live-connection view. directory::* reflects what is on disk or in the registry, not what is connected right now. For that, call the engine directly (engine::functions::list, engine::workers::list, …); daemon-managed providers (http, cron, state) open no WebSocket, so merge worker::list by name.
• Do not put a skill id (/) in agent_trigger's function: field, and do not pass a function id (::) to directory::skills::get.
• System prompt files without a description: in frontmatter are silently skipped by directory::system-prompts::list.
• Skills and system prompts share skills_folder; a system-prompts/ path component selects the prompt family, other prompts/ paths are ignored, and agents/ is reserved. Agent profiles are direct <agents_folder>/<id>.md files.
• An agent profile's skills: list is its PRELOADED skills, the twin of functions:: the harness freezes each skill's body into the prompt of every session running as the profile (parents' lists included, root-first). It grants no access and never narrows the skills index; unknown ids are reported by get as unknown_skills warnings rather than errors and rendered as unavailable. agents_folder profiles are unrelated to the read-only agents_skills_folder (~/.agents/skills), which holds external tools' skills.
• Registry answers (registry::workers::list / info) are cached ~60 s per unique input by default (registry_cache_ttl_ms) — change a parameter to refresh.

Functions

• directory::search_functions — find compact installed and installable function candidates for the required capabilities (usually one to six, at most eighteen per call).
• directory::skills::index — token-light per-worker overview, one block per installed worker; truncates and tells you to call list when large.
• directory::skills::list — enumerate every visible skill with id/title/type/description/bytes/modified_at; narrow with search, prefix, type, or include_description.
• directory::skills::get — read one skill doc by its skill id; forgiving about short names, a trailing .md, an iii:// prefix, and SKILL.md filenames. The response's path is the absolute on-disk file; its parent directory is the skill's base directory, where payload the body references by relative path (scripts/, reference/) lives.
• directory::skills::download_from_registry — install a published worker's skills from the registry; worker required, pin with version XOR tag (default tag: latest).
• directory::skills::download_from_repo — pull one skill folder from a GitHub repo; repo + skill required, branch defaults to main.
• directory::skills::download — flexible alias accepting either source set; prefer the two explicit forms so the source is unambiguous.
• directory::skills::update — overwrite one EXISTING skill with new full-file markdown (frontmatter included); never creates — author with directory::skills::create or materialize a bundle with a download first.
• directory::skills::create — create a NEW skill at <skills_folder>/<id>.md from full-file content; refuses an id that already resolves in the visible set, an existing target path, and ids the visibility filter (or a system-installed agents namespace) would hide.
• directory::skills::delete — permanently remove one EXISTING skill by id (same forgiving id forms as get); cleans up parent directories left empty.
• directory::system-prompts::list — list the system prompts the chat picker offers; the response array is named prompts.
• directory::system-prompts::get — read one system prompt's body by name; raw: true also returns the full on-disk file for round-tripping.
• directory::system-prompts::create — create a NEW system prompt at <skills_folder>/system-prompts/<name>.md; refuses an existing name or target path.
• directory::system-prompts::update — overwrite one EXISTING system prompt; the frontmatter must keep a non-empty description (a declared name renames it).
• directory::system-prompts::delete — permanently remove one EXISTING system prompt by name.
• directory::agents::list — list agent profiles (id, display name, description, emoji logo, extends, skill_count where null means every skill, function_count of preloaded functions; model/reasoning_effort are resolved through extends; skill_count/function_count count the additive union of the chain's lists). The bundled profiles default (the compact directory-first identity, shown as "Default"), iii (the harness default identity, hidden from the gallery), and iii-minimal (a hidden alias that extends default) are always listed with builtin: true; composer_placeholder, when present, is the profile's own example for the empty chat composer and never inherits; a row with inheritance_error has a broken extends chain.
• directory::agents::get — read one agent profile by id: its RESOLVED system prompt (ancestors' bodies root-first via extends, then its own; blank bodies are skipped, so a prompt-less profile serves its parent chain, or "" when it has no parent), preloaded skills (skill ids whose bodies the harness pre-loads into the session prompt) + unknown_skills, preloaded functions (engine function ids whose contracts the harness pre-loads into the system prompt of every session running as this profile) + unknown_functions (ids the engine does not know right now — a warning), and model (the profile's default model id — use it when spawning/sending with this profile; null = caller decides); raw: true returns the profile's OWN file for editing. inheritance_error set = fix extends before running it.
• directory::agents::create — create a NEW agent profile at <agents_folder>/<id>.md from full-file content; frontmatter needs a non-empty name, logo is emoji-only, skills: and functions: (preloaded function ids, e.g. coder::tree) are optional lists, and the body — the system prompt — may be empty; an extends: <id> that does not resolve is not a write error — get reports it as inheritance_error.
• directory::agents::update — overwrite one EXISTING agent profile (same scanner rules; the id stays the file stem, frontmatter name is display-only). Updating the bundled iii creates the local file that shadows it.
• directory::agents::delete — permanently remove one EXISTING agent profile by id; running sessions are unaffected, profiles extending it stop resolving until fixed. Deleting a local iii falls back to the bundled copy.
• directory::agents::functions::add / directory::agents::functions::remove — { id, functions: ["coder::tree", …] }: add ids to / drop ids from one EXISTING profile's OWN functions: list without a raw round-trip; the rest of the file stays byte-identical, ids already present (or already absent) are ignored, unchanged: true means nothing was written. Editing a bundled profile creates the local shadow. Ids inherited through extends are not touched: the resolved list is the union of the chain (root first), so an inherited id is removed on the parent that declares it.
• directory::registry::workers::list — page through published workers in the public registry (pagination.next_cursor feeds the next page's cursor).
• directory::registry::workers::info — pre-install card for one worker, including ones not installed: envelope, api_reference (public functions + triggers, names and descriptions only) and skills_tree; readme: true adds the README.
• directory::engine::functions::info — thin proxy to the engine's engine::functions::info; returns request/response schema, metadata, and registered triggers for one function id.