yieldskill 0.5.0

Build portable, resumable skill workflows in Rust.
Documentation

The crate and library names are both yieldskill. The installed command is yskill.

Create a workflow

1. Install Yield

Yield supports Rust on macOS, Linux, and Windows. Install the public crate:

cargo install yieldskill --root .yield --locked
.yield/bin/yskill --version

The crate contains the matching yskill runtime for your platform. You do not need Go, Node.js, or a separate CLI download.

2. Create the workflow

Create a Rust workflow inside your repository:

.yield/bin/yskill init skills/data-migration \
  --language rust \
  --description "Dry-run, approve, apply, and verify a database migration."

Replace skills/data-migration/src/main.rs with this tested workflow:

use serde_json::json;
use yieldskill::{define_skill, Context, SkillResult};

fn program(ctx: &mut Context) -> SkillResult {
    let dry_run = ctx.run_command("dry-run", "echo 'plan: add index users_email_idx'", 300);
    ctx.require(
        dry_run.exit_code == 0,
        "the dry run succeeds",
        Some(&json!({ "exit_code": dry_run.exit_code })),
    );

    let review = ctx.agent_task(
        "summarize-plan",
        "Summarize the migration plan for the operator: what changes, what is irreversible, what the rollback is.",
        Some(json!({ "plan": dry_run.stdout })),
        Some(json!({
            "type": "object",
            "required": ["summary"],
            "properties": { "summary": { "type": "string", "minLength": 1 } }
        })),
    );

    let approval = ctx.ask_user(
        "approve-apply",
        "Apply the migration to the live database?",
        &[("apply", "Apply now"), ("abort", "Abort")],
    );
    if approval != "apply" {
        return Err(ctx.refused("the operator declined to apply the migration"));
    }

    let apply = ctx.run_command("apply", "echo apply-ok", 600);
    ctx.require(
        apply.exit_code == 0,
        "the migration applies cleanly",
        Some(&json!({ "exit_code": apply.exit_code })),
    );

    let verify = ctx.run_command("verify", "echo verify-ok", 300);
    ctx.require(
        verify.exit_code == 0,
        "post-apply verification passes",
        Some(&json!({ "exit_code": verify.exit_code })),
    );

    Ok(json!({
        "applied": true,
        "summary": review["summary"],
    }))
}

fn main() {
    define_skill(program);
}

The generated Cargo.toml pins the public yieldskill crate to the installed CLI version. The generated skill.json runs the named Rust binary.

3. Test the workflow

Use deterministic fixture responses during tests. Save this as skills/data-migration/fixtures/responses.json:

{
  "summarize-plan": {
    "summary": "Adds users_email_idx concurrently; no data rewrite; rollback is DROP INDEX. The only irreversible step is index creation time."
  },
  "approve-apply": { "value": "apply" }
}

Then test the workflow:

.yield/bin/yskill doctor skills/data-migration --root . --test

Yield runs commands for real and supplies agent and user responses from the fixture. A successful test reaches completed without leaving a run journal.

4. Register the skill

Registration lets installed coding agents discover the workflow:

.yield/bin/yskill register skills/data-migration --root .

Select the verified agents explicitly when you do not want automatic detection:

.yield/bin/yskill register skills/data-migration --root . \
  --agent cursor,codex,claude-code

The generated adapters point back to skills/data-migration. They do not copy the workflow or install its dependencies again.

5. Run the skill

Start a new coding-agent session so it discovers the registered skill. Where slash skills are supported, run:

/data-migration

Otherwise, ask the agent in plain language:

Use the data-migration skill to apply this migration safely.

The agent follows the adapter, starts the canonical Rust workflow, and asks for each required agent or user response.

How Yield runs and resumes

  1. Your Rust function emits one typed operation.
  2. Yield records the request and exits. It does not run a daemon.
  3. The coding agent, user, or CLI supplies the result.
  4. Yield replays the function from its journal until it reaches the next operation.

Replay must produce the same operation sequence. Yield reports divergence instead of giving a recorded response to a different operation.

Where AgentTask fits

ctx.agent_task() delegates one bounded judgment to the coding agent. Pass important evidence explicitly, as this workflow passes its dry-run output. With its schema, Yield checks the returned JSON shape before the workflow continues; it does not prove the summary is correct. Host workspace and conversation access are host-dependent.

Rust primitive Purpose
ctx.run_command() Execute a command and record its exit code and output.
ctx.agent_task() Delegate one bounded judgment; an optional schema validates the result.
ctx.ask_user() Request an explicit human decision.
ctx.require() Bind a required claim to recorded evidence.
ctx.blocked() / ctx.refused() Stop honestly when work cannot or must not continue.

See the primitive guides and CLI reference for the complete contract.

Guarantees and limits

Yield provides deterministic control flow, typed requests and responses, persistent run state, replay with divergence detection, stale and duplicate response rejection, and evidence-bound completion.

Schema validity is not truth. Yield cannot prove that a coding agent performed only the requested work. run_command is different: the Yield CLI executes the command, so its recorded exit code and output are observed facts.

Programs must remain deterministic between operations. Do not read clocks, random values, environment variables, or changing files to choose the next operation. Cross those boundaries through a Yield operation instead.

Yield is not a daemon, hosted runtime, workflow DSL, marketplace, coding-agent loop, multi-agent orchestrator, or security sandbox.

Optional developer helper

Installing yieldskill does not create skills or coding-agent adapters. After learning the manual workflow above, install guided assistance explicitly:

.yield/bin/yskill helper install --root . --language rust

Review the plan and restart the coding agent after installation. The helper can teach, create, convert, check, repair, upgrade, and register workflows. yskill bootstrap remains a compatibility alias.

Coding agents and source

Cursor, Codex, and Claude Code are verified integrations. Yield also provides registry-backed project paths for other coding agents; those paths are not presented as end-to-end verified.

Yield is available under the MIT license.