$worker

iii-directory

v0.4.1

Engine introspection (functions / triggers / workers), workers registry proxy, and filesystem-backed skill + prompt reader.

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

agent-ready brief for v0.4.1

install + config + dependencies + readme + api reference, all in one place. fetch as agent-context.md for an llm to consume.

full markdown

open as agent-context.md

the same content rendered as discrete blocks below is exposed as a single markdown document at /workers/iii-directory.md?version=0.4.1. paste it into an llm prompt or pipe it through curl from a worker.

install

$iii worker add iii-directory@0.4.1

configuration

iii-config.yaml

- download_timeout_ms: 60000
  registry_url: https://api.workers.iii.dev
  skills_folder: ./skills

dependencies

no dependencies for v0.4.1

readme

README.md

iii-directory

Engine introspection, workers registry proxy, and filesystem-backed skill + prompt reader for the iii engine. Hosts four surfaces, all MCP-agnostic:

Surface	What clients see	When to use it
Skills (`skills::*`, `skill::fetch`)	Markdown documents under `iii://{id}` plus an `iii://skills` index	Orientation: "when and why to use my worker's tools"
Prompts (`prompts::*`)	Static prompt templates listed by `prompts::list` and read by `prompts::get`	Parametric command templates the user invokes
Directory (`directory::*`)	Read-side enrichment over `engine::functions::list`, `engine::workers::list`, `engine::trigger-types::list`, `engine::triggers::list`	"What's connected to the engine right now?"
Registry (`registry::*`)	HTTP proxy over `api.workers.iii.dev` with the same shape as `directory::*`	"What's published in the public registry?"

Skills and prompts are sourced from a single configured folder on disk (skills_folder). The only write path is the skills::download function, which pulls markdown into skills_folder from either the workers registry or a GitHub repo. Once downloaded, files belong to the developer — edit them however you want.

directory::* and registry::* share the same worker-list / worker-info envelope shape so callers can switch between the local engine view and the published-registry view without re-learning the API.

Install
Configuration
Quickstart: download some skills
On-disk layout
URI scheme
Functions
Custom trigger types
Local development & testing
Migration from skills v0.2.x

Install

iii worker add iii-directory

iii worker add fetches the binary, writes a config block into ~/.iii/config.yaml, and the engine starts the worker on the next iii start.

Configuration

# Folder that backs every read (`iii://`, `skill::fetch`, `skills::list`,
# `prompts::*`) and every write from `skills::download`. Resolved
# relative to the directory of this config file.
skills_folder: ./skills

# Workers registry base URL — used by `skills::download` when a
# `worker=` source is specified. Override for self-hosted deployments.
registry_url: https://api.workers.iii.dev

# Timeout for a single download (`git clone` or HTTP request) in ms.
download_timeout_ms: 60000

The folder is created on first download if it doesn't exist.

Quickstart: download some skills

# Pull a specific worker's skills + prompts at a fixed semver from
# the registry. Files land under `<skills_folder>/agent-memory/`.
iii trigger --function-id=skills::download \
  --payload='{"worker": "agent-memory", "version": "1.2.3"}'

# Same, but always fetch whatever's tagged `latest`.
iii trigger --function-id=skills::download \
  --payload='{"worker": "agent-memory", "tag": "latest"}'

# Pull a single subfolder out of a public GitHub repo via
# `git clone --depth 1`. Files land under
# `<skills_folder>/frontend-design/`.
iii trigger --function-id=skills::download \
  --payload='{
    "repo": "https://github.com/anthropics/skills",
    "skill": "frontend-design"
  }'

The response is { namespace, skills_written, prompts_written, source } where skills_written and prompts_written are arrays of relative paths / prompt names that were materialised in this run.

After every successful download the worker fires the skills::on-change and/or prompts::on-change trigger types so that subscribers like the mcp worker can forward MCP notifications/list_changed to their clients.

On-disk layout

The worker assumes a fixed layout under skills_folder:

skills_folder/
  <namespace>/                 # one folder per `skills::download` namespace
    index.md                   # → iii://<namespace>/index
    contacts.md                # → iii://<namespace>/contacts
    emails/send-email.md       # → iii://<namespace>/emails/send-email
    prompts/                   # ← magic marker for prompts
      send-email.md            # ← MCP slash-command (needs YAML frontmatter)
      triage.md

A few rules:

Skill ids are the relative path under skills_folder with .md stripped. Each segment must satisfy [a-z0-9_-]{1,64} and the first segment must not be the literal fn (reserved for section URIs).
Prompts live under any */prompts/*.md path. They must start with a YAML frontmatter block declaring at least description; name is optional and overrides the file-stem default.
Files anywhere else (i.e. not in a prompts/ segment) are skills.

The download function namespaces by source:

Source	Destination
`repo=URL skill=NAME`	`//...`
`worker=NAME version=…`	`//...`
`worker=NAME tag=…`	`//...`

Re-pulling the same source overwrites files file-by-file — existing siblings outside the response set are preserved (so hand-edited additions survive a re-pull).

URI scheme

Same scheme as previous releases, anchored now on the filesystem:

URI	Returns
`iii://skills`	Auto-rendered markdown index of every skill in `skills_folder`.
`iii://{id}`	The body at `/{id}.md`. Any depth. First segment must NOT equal `fn`.
`iii://fn/{a}/{b}/.../{leaf}`	Trigger function `a::b::...::leaf` with `{}` and serve its output. Each `/` after `fn/` becomes `::`.

The skill::fetch tool is a thin batched wrapper over the same resolver. Pass either uri (single) or uris (array) to read several sections in one round trip; sections are wrapped as # {uri}\n\n{body} and joined with \n\n---\n\n.

There is no recursion guard on iii://fn/ URIs — the resolver will trigger any function the engine exposes, including state::* and engine::* infra. Adapters that surface skill::fetch to untrusted callers should add their own filtering.

Functions

Sixteen functions across four groups. All registrations are namespace-clean; this worker is intentionally agnostic to MCP and any other adapter.

`skills::*` / `skill::fetch` (filesystem reader)

Function ID	Description
`skills::download`	Pull markdown into `skills_folder`. Either `{repo, skill}` or `{worker, version
`skills::list`	Metadata-only listing of every fs-backed skill.
`skills::fetch_skill`	Batched read across one or more `iii://` URIs (returns plain markdown).
`skill::fetch`	Public alias of `skills::fetch_skill` on a non-`skills::*` namespace.

`prompts::*` (filesystem reader)

Function ID	Description
`prompts::list`	Metadata-only listing of every fs-backed prompt.
`prompts::get`	Fetch one prompt's body + `{name, description, modified_at}`. Plain shape, no envelope.

`directory::*` (engine introspection)

Function ID	Description
`directory::function-list`	List functions registered with the engine; filter by search/prefix/worker.
`directory::function-info`	Single-function detail: schemas, owning worker, registered triggers, bundled how-to.
`directory::trigger-list`	List trigger TYPES registered with the engine; filter by search/prefix/worker.
`directory::trigger-info`	Single trigger-type detail: configuration schema, return schema, instance count.
`directory::registered-trigger-list`	List registered trigger INSTANCES (subscriber rows).
`directory::registered-trigger-info`	Composite: instance + trigger-type detail + function detail.
`directory::worker-list`	List workers connected to the engine; same row shape as `registry::worker-list`.
`directory::worker-info`	One worker's `worker` envelope + functions + trigger types + registered triggers.

`registry::*` (workers registry HTTP proxy)

Function ID	Description
`registry::worker-list`	Search published workers in `api.workers.iii.dev`. Same row shape as `directory::worker-list`.
`registry::worker-info`	Full registry detail for one worker: `worker` envelope (matching `directory::worker-info.worker`) plus `readme`, `api_reference`, `skills_tree`.

Both registry::* responses are cached in-process for registry_cache_ttl_ms (default 60s).

There is no skills::register / prompts::register — see Migration below.

Custom trigger types

Trigger type	Fires when	Payload to subscribers
`skills::on-change`	After a `skills::download` that wrote at least one skill markdown file	`{ "op": "download", "namespace": "", "source": "repo" \| "registry" }`
`prompts::on-change`	After a `skills::download` that wrote at least one prompt markdown file	`{ "op": "download", "namespace": "", "source": "repo" \| "registry" }`

Dispatches are fire-and-forget (Void), so the download path doesn't block on downstream latency.

Local development & testing

Run from source

cargo run --release -- --url ws://127.0.0.1:49134 --config ./config.yaml

Tests

# Fast, offline — exercises the pure helpers (markdown / URI / validators)
# without needing an iii engine.
cargo test --lib

# Full BDD suite — requires an iii engine on ws://127.0.0.1:49134
# (or III_ENGINE_WS_URL). The git-backed download scenarios spin up
# a local fixture repo via `git init`; the registry-backed scenarios
# point a wiremock server at the worker's `registry_url` config.
cargo test

# One feature group at a time. Available tags:
#   @engine  @read  @prompts  @download  @download_repo  @download_registry
cargo test --test bdd -- --tags @download

The BDD harness lives under tests/. Feature files mirror the modules in src/functions/. Step definitions under tests/steps/ drive each feature through the same iii.trigger path the production binary uses.

Migration from skills v0.2.x

skills v0.3.0 is a breaking change. The state-backed registry and the skills::register / prompts::register functions are gone. Workers in this monorepo that called those functions at boot will start receiving "function not found" errors on the registration call (the rest of the worker keeps working).

The new flow:

The worker publishes its skills + prompts to the workers registry as part of the standard release pipeline.
Operators run iii trigger skills::download worker= tag=latest (or pin a version) once per worker on each machine that runs mcp.
The downloaded markdown lives at //... and is served via iii:// to MCP clients. Operators are free to edit the files locally; a re-pull will overwrite the response set but leave any hand-added sibling files alone.

Workers that ship a private repo can also seed via the GitHub source:

iii trigger --function-id=skills::download \
  --payload='{"repo": "https://github.com/<org>/<repo>", "skill": "<folder>"}'

The mcp worker's existing subscriptions to skills::on-change and prompts::on-change continue to work unchanged — those triggers now fire after every successful download instead of every register.

api reference (json)

agent-api-reference.json

{
  "functions": [
    {
      "description": "List registered trigger instances (the link rows between trigger types and target functions). Filter by trigger_type, function_id, worker, or free-text search.",
      "metadata": {},
      "name": "directory::registered-trigger-list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "function_id": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "search": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "trigger_type": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "worker": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "RegisteredTriggerListInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "RegisteredTriggerListEntry": {
            "properties": {
              "config_summary": {
                "description": "Truncated (~80 chars) JSON preview of `config` so listings stay scannable. Use `directory::registered-trigger-info` for the full payload.",
                "type": "string"
              },
              "function_id": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "trigger_type": {
                "type": "string"
              },
              "worker_name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "config_summary",
              "function_id",
              "id",
              "trigger_type"
            ],
            "type": "object"
          }
        },
        "properties": {
          "registered_triggers": {
            "items": {
              "$ref": "#/definitions/RegisteredTriggerListEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "registered_triggers"
        ],
        "title": "RegisteredTriggerListOutput",
        "type": "object"
      }
    },
    {
      "description": "Download skills + prompts into skills_folder. Pass {repo, skill} to clone a single skill folder from a GitHub repo (git clone --depth 1), or {worker, version|tag} to pull from the workers registry. Files in the destination namespace are overwritten file-by-file.",
      "metadata": {
        "tool": {
          "label": "Download skills"
        }
      },
      "name": "skills::download",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "repo": {
            "default": null,
            "description": "Source A: GitHub repo URL. Pair with `skill`.",
            "type": [
              "string",
              "null"
            ]
          },
          "skill": {
            "default": null,
            "description": "Source A: subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.",
            "type": [
              "string",
              "null"
            ]
          },
          "tag": {
            "default": null,
            "description": "Source B: registry tag to pull (e.g. `latest`). Mutually exclusive with `version`.",
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "default": null,
            "description": "Source B: explicit semver to pull. Mutually exclusive with `tag`.",
            "type": [
              "string",
              "null"
            ]
          },
          "worker": {
            "default": null,
            "description": "Source B: workers registry name. Pair with exactly one of `version` / `tag`.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "DownloadInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "namespace": {
            "type": "string"
          },
          "prompts_written": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "skills_written": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "source": true
        },
        "required": [
          "namespace",
          "prompts_written",
          "skills_written",
          "source"
        ],
        "title": "DownloadOutput",
        "type": "object"
      }
    },
    {
      "description": "Fetches the content of one or more skill resources identified by iii:// URIs. When you encounter iii:// links in skill instructions, use this tool to retrieve their contents (batch with `uris` when helpful).",
      "metadata": {
        "tool": {
          "label": "Fetch skill"
        }
      },
      "name": "skill::fetch",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "uri": {
            "default": null,
            "description": "A single iii:// URI to read. Must start with \"iii://\".",
            "type": [
              "string",
              "null"
            ]
          },
          "uris": {
            "default": null,
            "description": "One or more iii:// URIs to read in order. When both `uri` and `uris` are provided, `uris` wins (matches the TS reference implementation).",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          }
        },
        "title": "FetchSkillInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "String",
        "type": "string"
      }
    },
    {
      "description": "Fetches the content of one or more skill resources identified by iii:// URIs. When you encounter iii:// links in skill instructions, use this tool to retrieve their contents (batch with `uris` when helpful).",
      "metadata": {},
      "name": "skills::fetch_skill",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "uri": {
            "default": null,
            "description": "A single iii:// URI to read. Must start with \"iii://\".",
            "type": [
              "string",
              "null"
            ]
          },
          "uris": {
            "default": null,
            "description": "One or more iii:// URIs to read in order. When both `uri` and `uris` are provided, `uris` wins (matches the TS reference implementation).",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          }
        },
        "title": "FetchSkillInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "String",
        "type": "string"
      }
    },
    {
      "description": "Worker envelope plus the lists of functions, trigger types, and registered triggers it owns. The `worker` field has the same shape as registry::worker-info so callers can switch between local + registry surfaces with the same parser.",
      "metadata": {},
      "name": "directory::worker-info",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "WorkerInfoInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "Worker": {
            "description": "Shared worker envelope used by both `directory::worker-list` rows and the `worker` field of `directory::worker-info`. Field names line up with `registry::Worker` (see [`crate::functions::registry::Worker`]) so callers learn one shape across local + registry surfaces.",
            "properties": {
              "active_invocations": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "connected_at_ms": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "description": {
                "description": "Engine-side workers carry no description; field present for shape parity with `registry::Worker.description`. Always `None`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "function_count": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "id": {
                "description": "Engine-assigned connection id (directory-specific).",
                "type": "string"
              },
              "ip_address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "isolation": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "description": "Worker name as registered with the engine.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "os": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "runtime": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "description": "Connection state (e.g. `\"connected\"`, `\"disconnected\"`).",
                "type": "string"
              },
              "version": {
                "description": "Worker version string from the worker's published manifest.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "active_invocations",
              "connected_at_ms",
              "function_count",
              "id",
              "status"
            ],
            "type": "object"
          },
          "WorkerFunctionEntry": {
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "function_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "function_id",
              "name"
            ],
            "type": "object"
          },
          "WorkerRegisteredTriggerEntry": {
            "properties": {
              "function_id": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "trigger_type": {
                "type": "string"
              }
            },
            "required": [
              "function_id",
              "id",
              "trigger_type"
            ],
            "type": "object"
          },
          "WorkerTriggerTypeEntry": {
            "properties": {
              "description": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "description",
              "id",
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "functions": {
            "items": {
              "$ref": "#/definitions/WorkerFunctionEntry"
            },
            "type": "array"
          },
          "registered_triggers": {
            "items": {
              "$ref": "#/definitions/WorkerRegisteredTriggerEntry"
            },
            "type": "array"
          },
          "trigger_types": {
            "items": {
              "$ref": "#/definitions/WorkerTriggerTypeEntry"
            },
            "type": "array"
          },
          "worker": {
            "allOf": [
              {
                "$ref": "#/definitions/Worker"
              }
            ],
            "description": "Same shape as `worker-list` rows (and `registry::worker-info.worker`)."
          }
        },
        "required": [
          "functions",
          "registered_triggers",
          "trigger_types",
          "worker"
        ],
        "title": "WorkerInfoOutput",
        "type": "object"
      }
    },
    {
      "description": "Fetch one filesystem-backed prompt by name. Returns the raw markdown body plus name, description, and modified_at — no envelope, no templating.",
      "metadata": {},
      "name": "prompts::get",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "PromptGetInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "body": {
            "description": "Raw markdown body (post-frontmatter) from disk.",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "modified_at": {
            "description": "File mtime as RFC 3339.",
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "body",
          "description",
          "modified_at",
          "name"
        ],
        "title": "PromptGetOutput",
        "type": "object"
      }
    },
    {
      "description": "Full detail for one function: schemas, owning worker, registered triggers that target it, and any matching how-to skill from skills_folder.",
      "metadata": {},
      "name": "directory::function-info",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "function_id": {
            "type": "string"
          }
        },
        "required": [
          "function_id"
        ],
        "title": "FunctionInfoInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "HowGuide": {
            "properties": {
              "abs_path": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "frontmatter": {
                "$ref": "#/definitions/HowToFrontmatter"
              },
              "skill_id": {
                "type": "string"
              }
            },
            "required": [
              "abs_path",
              "body",
              "frontmatter",
              "skill_id"
            ],
            "type": "object"
          },
          "HowToFrontmatter": {
            "description": "Subset of frontmatter fields the scanner cares about. Anything else in the YAML block is preserved verbatim by `split_frontmatter` but ignored here.",
            "properties": {
              "function_id": {
                "default": null,
                "description": "Optional single function id (alternative to `functions`).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "functions": {
                "default": [],
                "description": "Optional list of function ids this how-to covers.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "title": {
                "default": null,
                "description": "Optional human-readable title (mirrors what an `# H1` would give).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": {
                "default": null,
                "description": "Required marker — only `type: how-to` files are considered.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "RegisteredTriggerSummary": {
            "properties": {
              "config": true,
              "id": {
                "type": "string"
              },
              "trigger_type": {
                "type": "string"
              }
            },
            "required": [
              "config",
              "id",
              "trigger_type"
            ],
            "type": "object"
          }
        },
        "properties": {
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "function_id": {
            "type": "string"
          },
          "how_guide": {
            "anyOf": [
              {
                "$ref": "#/definitions/HowGuide"
              },
              {
                "type": "null"
              }
            ]
          },
          "metadata": true,
          "name": {
            "type": "string"
          },
          "registered_triggers": {
            "items": {
              "$ref": "#/definitions/RegisteredTriggerSummary"
            },
            "type": "array"
          },
          "request_schema": true,
          "response_schema": true,
          "worker_name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "function_id",
          "name",
          "registered_triggers"
        ],
        "title": "FunctionInfoOutput",
        "type": "object"
      }
    },
    {
      "description": "Fetch full registry metadata for one worker: worker envelope (same shape as registry::worker-list rows and directory::worker-info), readme, full API reference (functions + triggers schemas), and tree of skill/prompt file paths. Pass either `version` or `tag` (defaults to tag=\"latest\"). Results are cached for `registry_cache_ttl_ms`.",
      "metadata": {},
      "name": "registry::worker-info",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "`registry::worker-info` input. Pass either `version` or `tag`; if neither is provided we fall back to `tag: \"latest\"`.",
        "properties": {
          "name": {
            "description": "Worker name in the registry (e.g. `\"resend\"`).",
            "type": "string"
          },
          "tag": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "default": null,
            "description": "Mutually exclusive with `tag`. If neither is provided we fall back to `tag: \"latest\"`.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name"
        ],
        "title": "WorkerInfoInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ApiReference": {
            "properties": {
              "functions": {
                "default": [],
                "items": {
                  "$ref": "#/definitions/ApiReferenceFunction"
                },
                "type": "array"
              },
              "triggers": {
                "default": [],
                "items": {
                  "$ref": "#/definitions/ApiReferenceTrigger"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ApiReferenceFunction": {
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "metadata": true,
              "name": {
                "type": "string"
              },
              "request_schema": true,
              "response_schema": true
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "ApiReferenceTrigger": {
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "invocation_schema": true,
              "metadata": true,
              "name": {
                "type": "string"
              },
              "return_schema": true
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "RegistryAuthor": {
            "properties": {
              "is_verified": {
                "default": false,
                "type": "boolean"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "profile_picture": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "SkillsTree": {
            "properties": {
              "prompts": {
                "default": [],
                "items": {
                  "$ref": "#/definitions/SkillsTreePrompt"
                },
                "type": "array"
              },
              "skills": {
                "default": [],
                "items": {
                  "$ref": "#/definitions/SkillsTreeSkill"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "SkillsTreePrompt": {
            "properties": {
              "description": {
                "default": null,
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "SkillsTreeSkill": {
            "properties": {
              "path": {
                "type": "string"
              }
            },
            "required": [
              "path"
            ],
            "type": "object"
          },
          "Worker": {
            "description": "Shared worker envelope used by both `registry::worker-list` rows and the `worker` field of `registry::worker-info`. Same field names as [`crate::functions::directory::Worker`] so callers learn one shape across local + registry surfaces.",
            "properties": {
              "author": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/RegistryAuthor"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              },
              "repo": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "description": "Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "api_reference": {
            "$ref": "#/definitions/ApiReference"
          },
          "readme": {
            "type": [
              "string",
              "null"
            ]
          },
          "skills_tree": {
            "$ref": "#/definitions/SkillsTree"
          },
          "worker": {
            "allOf": [
              {
                "$ref": "#/definitions/Worker"
              }
            ],
            "description": "Same shape as `worker-list` rows (and `directory::worker-info.worker`)."
          }
        },
        "required": [
          "api_reference",
          "skills_tree",
          "worker"
        ],
        "title": "WorkerInfoOutput",
        "type": "object"
      }
    },
    {
      "description": "List every function registered with the engine. Filter by free-text search, namespace prefix, and/or worker name.",
      "metadata": {},
      "name": "directory::function-list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "prefix": {
            "default": null,
            "description": "Exact prefix match on `function_id` (e.g. `\"mem::\"`).",
            "type": [
              "string",
              "null"
            ]
          },
          "search": {
            "default": null,
            "description": "Case-insensitive substring match against `function_id` and `description`.",
            "type": [
              "string",
              "null"
            ]
          },
          "worker": {
            "default": null,
            "description": "Exact worker-name match (the worker that registered the function).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "FunctionListInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "FunctionListEntry": {
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "function_id": {
                "type": "string"
              },
              "name": {
                "description": "Last `::` segment of `function_id`.",
                "type": "string"
              },
              "worker_name": {
                "description": "Worker that registered it (resolved via `WorkerInfo.functions[]`), or the first `::` segment of `function_id` as fallback.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "function_id",
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "functions": {
            "items": {
              "$ref": "#/definitions/FunctionListEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "functions"
        ],
        "title": "FunctionListOutput",
        "type": "object"
      }
    },
    {
      "description": "List every worker currently connected to the engine. Filter by name substring, runtime, or status. Same row shape as registry::worker-list so callers learn one envelope.",
      "metadata": {},
      "name": "directory::worker-list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "runtime": {
            "default": null,
            "description": "Exact runtime match (e.g. `\"rust\"`, `\"node\"`).",
            "type": [
              "string",
              "null"
            ]
          },
          "search": {
            "default": null,
            "description": "Case-insensitive substring match against `name`.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "default": null,
            "description": "Exact status match (e.g. `\"connected\"`).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "WorkerListInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "Worker": {
            "description": "Shared worker envelope used by both `directory::worker-list` rows and the `worker` field of `directory::worker-info`. Field names line up with `registry::Worker` (see [`crate::functions::registry::Worker`]) so callers learn one shape across local + registry surfaces.",
            "properties": {
              "active_invocations": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "connected_at_ms": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "description": {
                "description": "Engine-side workers carry no description; field present for shape parity with `registry::Worker.description`. Always `None`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "function_count": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "id": {
                "description": "Engine-assigned connection id (directory-specific).",
                "type": "string"
              },
              "ip_address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "isolation": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "description": "Worker name as registered with the engine.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "os": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "runtime": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "description": "Connection state (e.g. `\"connected\"`, `\"disconnected\"`).",
                "type": "string"
              },
              "version": {
                "description": "Worker version string from the worker's published manifest.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "active_invocations",
              "connected_at_ms",
              "function_count",
              "id",
              "status"
            ],
            "type": "object"
          }
        },
        "properties": {
          "workers": {
            "items": {
              "$ref": "#/definitions/Worker"
            },
            "type": "array"
          }
        },
        "required": [
          "workers"
        ],
        "title": "WorkerListOutput",
        "type": "object"
      }
    },
    {
      "description": "Full detail for one trigger type: configuration schema, return schema, owning worker, and current instance count.",
      "metadata": {},
      "name": "directory::trigger-info",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "id": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "TriggerInfoInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "configuration_schema": {
            "description": "SDK 0.11.3 surfaces a single `trigger_request_format` that doubles as the per-instance configuration shape; expose it explicitly so callers don't have to know the alias."
          },
          "description": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "instance_count": {
            "format": "uint",
            "minimum": 0,
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "return_schema": true,
          "worker_name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "description",
          "id",
          "instance_count",
          "name"
        ],
        "title": "TriggerInfoOutput",
        "type": "object"
      }
    },
    {
      "description": "List filesystem-backed prompts (name, description, modified_at) from skills_folder.",
      "metadata": {},
      "name": "prompts::list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "ListPromptsInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "PromptEntry": {
            "properties": {
              "description": {
                "type": "string"
              },
              "modified_at": {
                "description": "File mtime as RFC 3339.",
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "description",
              "modified_at",
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "prompts": {
            "items": {
              "$ref": "#/definitions/PromptEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "prompts"
        ],
        "title": "ListPromptsOutput",
        "type": "object"
      }
    },
    {
      "description": "Full denormalized detail for one registered trigger: instance config + trigger-type detail + function detail.",
      "metadata": {},
      "name": "directory::registered-trigger-info",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "id": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "RegisteredTriggerInfoInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "FunctionInfoOutput": {
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "function_id": {
                "type": "string"
              },
              "how_guide": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/HowGuide"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "metadata": true,
              "name": {
                "type": "string"
              },
              "registered_triggers": {
                "items": {
                  "$ref": "#/definitions/RegisteredTriggerSummary"
                },
                "type": "array"
              },
              "request_schema": true,
              "response_schema": true,
              "worker_name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "function_id",
              "name",
              "registered_triggers"
            ],
            "type": "object"
          },
          "HowGuide": {
            "properties": {
              "abs_path": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "frontmatter": {
                "$ref": "#/definitions/HowToFrontmatter"
              },
              "skill_id": {
                "type": "string"
              }
            },
            "required": [
              "abs_path",
              "body",
              "frontmatter",
              "skill_id"
            ],
            "type": "object"
          },
          "HowToFrontmatter": {
            "description": "Subset of frontmatter fields the scanner cares about. Anything else in the YAML block is preserved verbatim by `split_frontmatter` but ignored here.",
            "properties": {
              "function_id": {
                "default": null,
                "description": "Optional single function id (alternative to `functions`).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "functions": {
                "default": [],
                "description": "Optional list of function ids this how-to covers.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "title": {
                "default": null,
                "description": "Optional human-readable title (mirrors what an `# H1` would give).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": {
                "default": null,
                "description": "Required marker — only `type: how-to` files are considered.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "RegisteredTriggerSummary": {
            "properties": {
              "config": true,
              "id": {
                "type": "string"
              },
              "trigger_type": {
                "type": "string"
              }
            },
            "required": [
              "config",
              "id",
              "trigger_type"
            ],
            "type": "object"
          },
          "TriggerInfoOutput": {
            "properties": {
              "configuration_schema": {
                "description": "SDK 0.11.3 surfaces a single `trigger_request_format` that doubles as the per-instance configuration shape; expose it explicitly so callers don't have to know the alias."
              },
              "description": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "instance_count": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "return_schema": true,
              "worker_name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "description",
              "id",
              "instance_count",
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "config": true,
          "function": {
            "anyOf": [
              {
                "$ref": "#/definitions/FunctionInfoOutput"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full function detail for `function_id`. `None` if the function has been unregistered between calls."
          },
          "function_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "metadata": true,
          "trigger": {
            "anyOf": [
              {
                "$ref": "#/definitions/TriggerInfoOutput"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full trigger-type detail for `trigger_type`. `None` if the type has been unregistered between calls."
          },
          "trigger_type": {
            "type": "string"
          },
          "worker_name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "config",
          "function_id",
          "id",
          "trigger_type"
        ],
        "title": "RegisteredTriggerInfoOutput",
        "type": "object"
      }
    },
    {
      "description": "List filesystem-backed skills (id, body length, modified_at) from skills_folder.",
      "metadata": {},
      "name": "skills::list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "ListSkillsInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SkillEntry": {
            "properties": {
              "bytes": {
                "format": "uint",
                "minimum": 0,
                "type": "integer"
              },
              "id": {
                "type": "string"
              },
              "modified_at": {
                "description": "File mtime as RFC 3339 (best effort; empty if unavailable).",
                "type": "string"
              }
            },
            "required": [
              "bytes",
              "id",
              "modified_at"
            ],
            "type": "object"
          }
        },
        "properties": {
          "skills": {
            "items": {
              "$ref": "#/definitions/SkillEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "skills"
        ],
        "title": "ListSkillsOutput",
        "type": "object"
      }
    },
    {
      "description": "List every trigger TYPE registered with the engine. Filter by search, prefix, worker. (For registered trigger instances, use directory::registered-trigger-list.)",
      "metadata": {},
      "name": "directory::trigger-list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "prefix": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "search": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          },
          "worker": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "TriggerListInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "TriggerListEntry": {
            "properties": {
              "description": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "worker_name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "description",
              "id",
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "triggers": {
            "items": {
              "$ref": "#/definitions/TriggerListEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "triggers"
        ],
        "title": "TriggerListOutput",
        "type": "object"
      }
    },
    {
      "description": "List workers from the public registry (api.workers.iii.dev) matching the free-text term `search`. Same row shape as directory::worker-list so callers learn one envelope. Results are cached for `registry_cache_ttl_ms` (default 60s).",
      "metadata": {},
      "name": "registry::worker-list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "`registry::worker-list` input. Mirrors [`crate::functions::directory::WorkerListInput.search`] so callers can switch between local and registry surfaces without re-learning the API. Adds `limit` for paging because the registry is paged.",
        "properties": {
          "limit": {
            "default": null,
            "description": "Max results to return. Defaults to 20; capped at 100.",
            "format": "uint32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "search": {
            "default": null,
            "description": "Free-text query forwarded to the registry as `?q=…`. Required — the public registry doesn't support an unscoped browse endpoint.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "WorkerListInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "RegistryAuthor": {
            "properties": {
              "is_verified": {
                "default": false,
                "type": "boolean"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "profile_picture": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "Worker": {
            "description": "Shared worker envelope used by both `registry::worker-list` rows and the `worker` field of `registry::worker-info`. Same field names as [`crate::functions::directory::Worker`] so callers learn one shape across local + registry surfaces.",
            "properties": {
              "author": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/RegistryAuthor"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              },
              "repo": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "description": "Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          }
        },
        "properties": {
          "workers": {
            "items": {
              "$ref": "#/definitions/Worker"
            },
            "type": "array"
          }
        },
        "required": [
          "workers"
        ],
        "title": "WorkerListOutput",
        "type": "object"
      }
    }
  ],
  "triggers": [
    {
      "description": "Fires after every successful skills::download that wrote at least one prompt markdown file.",
      "invocation_schema": {},
      "metadata": {},
      "name": "prompts::on-change",
      "return_schema": {}
    },
    {
      "description": "Fires after every successful skills::download that wrote at least one skill markdown file.",
      "invocation_schema": {},
      "metadata": {},
      "name": "skills::on-change",
      "return_schema": {}
    }
  ]
}

iii-directory

full markdown

install

configuration

dependencies

readme

iii-directory

Table of contents

Install

Configuration

Quickstart: download some skills

On-disk layout

URI scheme

Functions

skills::* / skill::fetch (filesystem reader)

prompts::* (filesystem reader)

directory::* (engine introspection)

registry::* (workers registry HTTP proxy)

Custom trigger types

Local development & testing

Run from source

Tests

Migration from skills v0.2.x

api reference (json)

`skills::*` / `skill::fetch` (filesystem reader)

`prompts::*` (filesystem reader)

`directory::*` (engine introspection)

`registry::*` (workers registry HTTP proxy)