Yield for Python

Move repeatable coding-agent instructions from words into Python.

Build typed, resumable workflows that stay beside the code they operate on.

Website · Documentation · PyPI · GitHub

The package name and import name are both yieldskill. Python reserves yield as a keyword.

Create a workflow

1. Install Yield

Yield supports Python 3.10 or later on macOS, Linux, and Windows. Create a virtual environment and install the public package:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install yieldskill
python -m yieldskill --version

On Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install yieldskill
python -m yieldskill --version

Each wheel contains the matching yskill runtime for its platform. You do not need Go, Node.js, or a separate CLI installation.

2. Create the workflow

Create a Python workflow inside your repository:

python -m yieldskill init skills/env-doctor \
  --language python \
  --description "Check the Python environment and explain the required fix."

Replace skills/env-doctor/main.py with this tested workflow:

from yieldskill import define_skill

def program(ctx):
    probe = ctx.run_command(
        "probe-python", "python3 --version || python --version", timeout_seconds=60
    )

    diagnosis = ctx.agent_task(
        "diagnose",
        "Given the probe output, is this environment healthy for the project? "
        "If not, state the single most likely fix.",
        context={"exit_code": probe.exit_code, "stdout": probe.stdout, "stderr": probe.stderr},
        schema={
            "type": "object",
            "required": ["healthy"],
            "properties": {
                "healthy": {"type": "boolean"},
                "fix_hint": {"type": "string"},
            },
        },
    )

    if not diagnosis["healthy"]:
        answer = ctx.ask_user(
            "apply-fix",
            f"The environment needs a fix: {diagnosis.get('fix_hint', 'unknown')}. Apply it now and reply done.",
            options=[{"value": "done"}, {"value": "skip"}],
        )
        if answer != "done":
            ctx.blocked("the environment fix was not applied")
        recheck = ctx.run_command(
            "recheck-python", "python3 --version || python --version", timeout_seconds=60
        )
        ctx.require(recheck.exit_code == 0, "the environment probe passes after the fix", recheck)
        return {"healthy": True, "fixed": True}

    ctx.require(probe.exit_code == 0, "the environment probe passes", probe)
    return {"healthy": True, "fixed": False}


define_skill(program)

The generated skill.json declares Python as the runner. The generated SKILL.md tells a coding agent how to start and resume the workflow.

3. Test the workflow

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

{
  "diagnose": { "healthy": true }
}

Then test the workflow:

python -m yieldskill doctor skills/env-doctor --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:

python -m yieldskill register skills/env-doctor --root .

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

python -m yieldskill register skills/env-doctor --root . \
  --agent cursor,codex,claude-code

The generated adapters point back to skills/env-doctor. 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:

/env-doctor

Otherwise, ask the agent in plain language:

Use the env-doctor skill to check this project.

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

How Yield runs and resumes

1. Your Python 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 the probe result. With its schema, Yield checks the returned JSON shape before the workflow continues; it does not prove the diagnosis is correct. Host workspace and conversation access are host-dependent.

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:

python -m yieldskill helper install --root . --language python

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.

• Read the documentation
• Explore tested examples
• View the Python source
• Report an issue

Yield is available under the MIT license.