skills

Agentic content registry worker for the iii engine. Persists two kinds of content for AI clients: skills (markdown orientation docs about a worker's tools, served at iii://{id} plus an auto-rendered iii://skills index) and prompts (parametric slash-command templates, dispatched on demand to a registered handler function). Workers register their content at boot via iii.trigger; skills persists everything to iii-state and emits change notifications on skills::on-change / prompts::on-change for any other worker that wants to react.

The rest of this README walks you through installing the worker and writing a worker that publishes skills and slash-command prompts.

Table of contents

1. Install
2. Quickstart: publish a skill and a slash-command
3. Configuration
4. Functions
5. Custom trigger types
6. Local development & testing

Install

iii worker add skills

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.

Quickstart: publish a skill and a slash-command

A worker can plug into this registry three ways. They compose: most workers ship one top-level skill, optional sub-skill markdown sections, and zero or more slash-commands.

The interface is two iii.trigger calls, plus optional in-process handler functions for sub-skills and prompt rendering:

Skills (markdown orientation docs)

A skill is a markdown document explaining when and why to use your worker's tools. Skills don't replicate the JSON schemas of your functions — clients get those from the engine's tool listing. Skills tell the LLM which tool for which job.

Register one with skills::register:

use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::json;

let iii = register_worker("ws://localhost:49134", InitOptions::default());

iii.trigger(TriggerRequest {
    function_id: "skills::register".into(),
    payload: json!({
        "id": "myworker",
        "skill": include_str!("../docs/skill.md"),
    }),
    action: None,
    timeout_ms: Some(5_000),
}).await?;

Validation rules (rejected at registration time):

• id: 1+ path segments separated by /. Each segment uses lowercase ASCII letters, digits, - and _; max 64 chars per segment. Total id length capped at 1024 chars.
• The literal fn is reserved as the first segment of any id (used as the section-URI marker — see Section URIs). fn may appear at deeper segments freely (docs/fn-reference is fine).
• skill: non-empty; max 256 KiB.

Re-registering with the same id overwrites the body and refreshes the registered_at timestamp. Workers MUST re-register on every boot so any updated content shipped with the worker lands in the registry. Doing this unconditionally also keeps you robust to state being wiped during local development.

URI scheme

The first-segment fn literal flips the URI from "skill body lookup" to "function trigger". Anything else as the first segment is treated as a slashed path of skill ids and resolved against the skills state scope as a single key. This keeps the scheme unambiguous at arbitrary depth: iii://resend/email/send is always a stored markdown body, while iii://fn/resend/email/send is always a call to resend::email::send.

The auto-rendered iii://skills index uses the first H1 of each skill as the link title and the first non-heading paragraph as the description (truncated at 140 chars). Nested entries are indented by 2 * depth spaces so the index reads as a tree. Lead each registered body with a # {title} and a short summary paragraph and the index reads cleanly without further work.

Modeling a deep skill tree

Top-level skill bodies should stay small — a router that links to deeper, more granular content. The agent only loads iii://yourworker initially; everything else is fetched lazily through skill::fetch (see below). Token cost grows with how deep the agent actually drills, not with how big your worker's docs are.

Each level is an independent state row. Parents don't have to exist first (orphans are allowed but read awkwardly in the index). A re-register at the same id overwrites that row only — siblings and children are untouched.

Worked example: a small resend worker with two depths of nested skills plus one section URI that points at a function.

use iii_sdk::{RegisterFunction, TriggerRequest};
use serde_json::{json, Value};

// 1. Top-level router (small body — links into children).
iii.trigger(TriggerRequest {
    function_id: "skills::register".into(),
    payload: json!({
        "id": "resend",
        "skill": "# resend\n\nEmail provider integration.\n\n\
                  - [`email`](iii://resend/email) — sending and tracking\n\
                  - [`contacts`](iii://resend/contacts) — audience management\n\
                  \n\
                  Live status check: \
                  [`health`](iii://fn/resend/health)\n",
    }),
    action: None,
    timeout_ms: Some(5_000),
}).await?;

// 2. Mid-level group (also a router into its own children).
iii.trigger(TriggerRequest {
    function_id: "skills::register".into(),
    payload: json!({
        "id": "resend/email",
        "skill": "# resend/email\n\nEmail flows.\n\n\
                  - [`send`](iii://resend/email/send) — outbound\n\
                  - [`track`](iii://resend/email/track) — webhooks + status\n",
    }),
    action: None,
    timeout_ms: Some(5_000),
}).await?;

// 3. Leaf body — the actual content the agent will read once it
// decides to drill in. Loaded on demand via skill::fetch.
iii.trigger(TriggerRequest {
    function_id: "skills::register".into(),
    payload: json!({
        "id": "resend/email/send",
        "skill": include_str!("../docs/resend-email-send.md"),
    }),
    action: None,
    timeout_ms: Some(5_000),
}).await?;

// 4. A section URI: live function output instead of a static body.
// `iii://fn/resend/health` triggers `resend::health` with {} and
// returns its output. Useful for status, dynamic catalogues, etc.
iii.register_function(
    RegisterFunction::new("resend::health", |_input: Value| {
        Ok::<_, String>(json!({
            "content": "# Resend health\n\nAPI: ok. Quota: 73% remaining."
        }))
    })
    .description("Live operational health for the resend integration."),
);

Once registered, an agent reading iii://resend sees the small router. If it needs send semantics, it asks skill::fetch for iii://resend/email/send (one round trip, ~200 lines of markdown instead of the worker's full 2000-line documentation).

Section URIs (function-backed content)

Section URIs trigger an iii function with {} and serve its output as resource content. The URI shape is iii://fn/{a}/{b}/... and the mapping to a function id is mechanical: every / after fn/ becomes ::. This means agents and humans can construct a URI from any function id by string-replace alone.

A function backing a section URI should return one of:

• a String → served as text/markdown.
• { "content": "..." } → the content field is served as text/markdown.
• anything else → pretty-printed JSON, served as application/json.

The recursion guard blocks the internal namespaces (engine::*, state::*, mcp::*, skills::*, prompts::*, iii::*, iii.*, a2a::*) at read time so a crafted iii://fn/state/set can't tunnel into infra.

Function ids that contain . (e.g. the engine's iii.on_foo lifecycle handlers) are NOT reachable through this shape. That's intentional — those handlers are triggered on engine events, not by agents.

Fetching skills on demand

Top-level skill bodies are designed to stay small (a router that points at sub-skills) so they don't burn the LLM's context budget on content the agent might never need. Consumers resolve those iii:// links lazily via the skill::fetch tool — a thin batched wrapper over the same resolver that backs skills::resources-read.

Each URI is wrapped as # {uri}\n\n{body} and sections are joined with \n\n---\n\n into one markdown document, so the agent can pull several sub-skills in one round trip:

{ "uris": ["iii://resend/email/send", "iii://resend/email/track"] }

This composes naturally with the multi-level body shape: the agent loads the top-level router once, then batches fetches for the deeper bodies it actually needs (and the iii://fn/... section URIs of the functions it expects to call).

Two registrations, one handler:

• skill::fetch — public alias on a non-hidden namespace. MCP clients see it as the tool skill__fetch, which is what the description tells agents to call when they encounter iii:// links in skill instructions. This is the id agents should use.
• skills::fetch_skill — canonical id, colocated with the rest of the registry. Hidden from MCP tools/list because the bridge hard-floors every skills:: prefix; sibling workers can still call it directly via iii.trigger.

Validation rules (rejected before any resource is touched):

• At least one of uri / uris must be present and non-blank after trim.
• Every URI must start with iii://. Other schemes are rejected with a clear error so an agent can correct the call rather than silently fetching nothing.

Prompts (slash commands)

A prompt is a parametric template the user invokes from the client (e.g. typing /send-email). The template is rendered by your handler function with the user-supplied arguments.

Registration is two steps:

1. Register a normal handler function. No special opt-in flag is needed — skills dispatches the handler directly through iii.trigger when the prompt is invoked.
2. Register the prompt itself, pointing at that function.

use iii_sdk::{RegisterFunction, TriggerRequest};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::json;

#[derive(Deserialize, JsonSchema)]
struct SendEmailArgs {
    to: String,
    subject: String,
}

#[derive(Serialize, JsonSchema)]
struct PromptOutput {
    content: String,
}

// Step 1: handler renders the prompt
iii.register_function(
    RegisterFunction::new("myworker::send_email_prompt", |args: SendEmailArgs| {
        Ok::<_, String>(PromptOutput {
            content: format!(
                "Compose an email to {} with the subject \"{}\". Be concise and friendly.",
                args.to, args.subject
            ),
        })
    })
    .description("Render the send-email slash-command body."),
);

// Step 2: register the slash-command
iii.trigger(TriggerRequest {
    function_id: "prompts::register".into(),
    payload: json!({
        "name": "send-email",
        "description": "Compose and send an email",
        "arguments": [
            { "name": "to",      "description": "Recipient address", "required": true },
            { "name": "subject", "description": "Subject line",      "required": true }
        ],
        "function_id": "myworker::send_email_prompt"
    }),
    action: None,
    timeout_ms: Some(5_000),
}).await?;

Validation rules (rejected at registration time):

• name: lowercase ASCII letters, digits, - and _ only; max 64 chars (no ::, no /, no whitespace)
• description: non-empty after trim
• function_id: non-empty after trim
• arguments[].name: non-empty, no duplicates within the list

Argument schema gotcha

The arguments field is what the client sees in its argument-picker UI. It does not auto-validate at runtime. The handler is responsible for validating its own input — treat the schema as a contract you uphold inside the function.

Output normalization

The handler can return any of:

• String → wrapped as a single user-text message
• { "content": "..." } → wrapped as a single user-text message
• { "messages": [ ... ] } → passed through unchanged (full control; use this for multi-turn templates or assistant-prefilled responses)
• anything else → an error returned to the client

Lifecycle & boot-time handshake

Skills and prompts are stored in iii-state under scopes skills and prompts (configurable). Both registries are durable and survive restarts of either skills or your worker.

Workers MUST re-register on every boot. skills itself can be absent or come up after your worker, so treat the registration as best-effort with capped exponential backoff:

use std::sync::Arc;
use std::time::{Duration, Instant};
use iii_sdk::{TriggerRequest, III};
use serde_json::json;

fn register_with_iii_skills(iii: Arc<III>) {
    tokio::spawn(async move {
        let mut backoff = Duration::from_secs(5);
        let started = Instant::now();
        loop {
            let result = iii.trigger(TriggerRequest {
                function_id: "skills::register".into(),
                payload: json!({
                    "id": "myworker",
                    "skill": include_str!("../docs/skill.md"),
                }),
                action: None,
                timeout_ms: Some(5_000),
            }).await;
            if result.is_ok() {
                tracing::info!("registered myworker skill");
                return;
            }
            if started.elapsed() > Duration::from_secs(180) {
                tracing::warn!("skills handshake gave up; install / start it and restart this worker");
                return;
            }
            tokio::time::sleep(backoff).await;
            backoff = (backoff * 2).min(Duration::from_secs(60));
        }
    });
}

On graceful shutdown, optionally call skills::unregister and prompts::unregister to clean up. Crashes leave entries in state indefinitely; an operator can list them with skills::list / prompts::list (which expose registered_at) and remove dead ones manually.

Mutations of either scope fire the skills::on-change / prompts::on-change custom trigger types automatically. Any worker can subscribe and react to registrations without polling.

Subscribing to registry changes

Workers that need to react to registrations (a dashboard, a metrics sink, a sibling protocol bridge) subscribe to the custom trigger types:

use iii_sdk::RegisterTriggerInput;
use serde_json::json;

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "skills::on-change".into(),
    function_id: "myworker::on_skill_change".into(),
    config: json!({}),
    metadata: None,
})?;

Payload sent to each subscriber:

Dispatches are fire-and-forget (Void), so the write path on skills::register / prompts::register doesn't block on downstream latency. Idempotent unregisters that found nothing to delete don't fire.

Full multi-language example

Self-contained worker that registers one skill, one sub-skill function, and one slash-command prompt. Boots, registers everything, then sleeps until SIGINT.

Rust

use iii_sdk::{register_worker, InitOptions, RegisterFunction, TriggerRequest};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

#[derive(Default, Deserialize, JsonSchema)]
struct GreetArgs {
    name: String,
}

#[derive(Serialize, JsonSchema)]
struct SkillContent {
    content: String,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    // 1. Sub-skill function: returns extended docs as markdown.
    iii.register_function(
        RegisterFunction::new("demo::guide", |_input: Value| {
            Ok::<_, String>(SkillContent {
                content: "# Demo guide\n\nThe long-form docs for the demo worker."
                    .into(),
            })
        })
        .description("Detailed guide for the demo worker."),
    );

    // 2. Prompt handler: turns slash-command args into a templated message.
    iii.register_function(
        RegisterFunction::new("demo::greet_prompt", |input: GreetArgs| {
            Ok::<_, String>(SkillContent {
                content: format!("Greet {} warmly.", input.name),
            })
        })
        .description("Render the greet prompt."),
    );

    // Wire the registries. Always skills::register / prompts::register
    // at startup so the entries refresh after any worker upgrade.
    iii.trigger(TriggerRequest {
        function_id: "skills::register".into(),
        payload: json!({
            "id": "demo",
            "skill": "# demo\n\n\
                      A demo worker.\n\n\
                      See [`guide`](iii://demo/demo::guide) for the long version.\n"
        }),
        action: None,
        timeout_ms: Some(5_000),
    }).await?;

    iii.trigger(TriggerRequest {
        function_id: "prompts::register".into(),
        payload: json!({
            "name": "greet",
            "description": "Compose a greeting.",
            "arguments": [
                { "name": "name", "description": "Who to greet", "required": true }
            ],
            "function_id": "demo::greet_prompt"
        }),
        action: None,
        timeout_ms: Some(5_000),
    }).await?;

    tokio::signal::ctrl_c().await?;
    Ok(())
}

Node

import { registerWorker } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

iii.registerFunction({ id: 'demo::guide' }, async () => ({
  content: '# Demo guide\n\nThe long-form docs for the demo worker.',
}))

iii.registerFunction({ id: 'demo::greet_prompt' }, async ({ name = 'world' }) => ({
  content: `Greet ${name} warmly.`,
}))

await iii.trigger({
  function_id: 'skills::register',
  payload: {
    id: 'demo',
    skill: '# demo\n\nA demo worker.\n\nSee [`guide`](iii://demo/demo::guide) for the long version.\n',
  },
})

await iii.trigger({
  function_id: 'prompts::register',
  payload: {
    name: 'greet',
    description: 'Compose a greeting.',
    arguments: [{ name: 'name', description: 'Who to greet', required: true }],
    function_id: 'demo::greet_prompt',
  },
})

Python

from iii_sdk import register_worker

iii = register_worker('ws://localhost:49134')

@iii.register_function('demo::guide')
async def guide(_input):
    return {'content': '# Demo guide\n\nThe long-form docs for the demo worker.'}

@iii.register_function('demo::greet_prompt')
async def greet_prompt(input):
    name = input.get('name', 'world')
    return {'content': f'Greet {name} warmly.'}

await iii.trigger(
    function_id='skills::register',
    payload={
        'id': 'demo',
        'skill': '# demo\n\nA demo worker.\n\nSee [`guide`](iii://demo/demo::guide) for the long version.\n',
    },
)

await iii.trigger(
    function_id='prompts::register',
    payload={
        'name': 'greet',
        'description': 'Compose a greeting.',
        'arguments': [{'name': 'name', 'description': 'Who to greet', 'required': True}],
        'function_id': 'demo::greet_prompt',
    },
)

Configuration

# skills runtime config.

# State scopes used to persist the two registries. Changing these at
# runtime is supported but orphans prior entries; treat them as
# deployment-time constants in practice.
scopes:
  skills: skills
  prompts: prompts

# Default timeout for state::* and sub-skill function triggers (ms).
state_timeout_ms: 10000

CLI flags:

--config <PATH>    Path to config.yaml [default: ./config.yaml]
--url <URL>        WebSocket URL of the iii engine [default: ws://127.0.0.1:49134]
--manifest         Output the module manifest as JSON and exit
-h, --help         Print help

If the config file is missing or malformed the worker logs a warning and falls back to the defaults — boot is never blocked by a bad config path.

Functions

Thirteen functions across the two registries plus one fetch alias. The seven public CRUD entries (six registry CRUD + the public fetch alias) are callable by any worker over iii.trigger; the alias is also surfaced as an MCP tool. The remaining six entries are internal-RPC reserved for protocol-bridge workers; they never appear in tools/list because their ids start with the skills:: / prompts:: hard-floor prefixes.

Custom trigger types

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 --test bdd -- --tags @pure

# Full suite — requires an iii engine on ws://127.0.0.1:49134
# (or III_ENGINE_WS_URL). Runs the full BDD scenario set covering
# every function and every validation rule.
cargo test

# One feature group at a time. Available tags:
#   @pure  @markdown
#   @engine  @skills_register  @skills_resources  @skills_fetch  @skills_nested
#   @prompts_register  @prompts_get  @notifications  @mcp_bridge
cargo test --test bdd -- --tags @skills_nested

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 (v0.1.x → v0.2.0)

The URI scheme changed in two breaking ways. Workers that registered skills against 0.1.x need to update before upgrading.

1. Function-backed URIs use fn/ as a fixed prefix. The legacy two-segment form iii://{anything}/{worker::function_id} is gone. Rewrite each link by prefixing iii://fn/ and replacing every :: with /:

The legacy two-segment form now resolves to a state-backed sub-skill lookup, so it returns "Skill not found" instead of triggering the function. There is no silent fallback.

2. Multi-segment ids are now stored skills. iii://resend/email and similar are state-backed bodies you can register. There is no depth cap (per-segment cap stays at 64 chars; total id capped at 1024 chars). The fn literal is reserved as the first segment of any registered id; deeper occurrences (docs/fn-reference) are fine.

Workers MUST update their bundled markdown bodies (replace any iii://x/worker::fn in skill text with iii://fn/worker/fn) and re-register at boot. The skills::on-change trigger fires on every re-registration, so subscribers stay in sync automatically.