Concept / Anatomy

One workflow. Small adapters.

You edit one skill workflow. Yield generates the SKILL.md adapter each coding agent expects.

01 / Terms

A skill can think. A skill workflow can run.

Regular skill

Instructions for one capability.

Explains when and how an agent should do a task.
The agent reads and follows the instructions.
Order, retries, checks, and saved state usually stay in words.

Skill workflow

Skills and code in one process.

Calls skills, commands, and people when needed.
Uses code for order, branches, loops, and finish rules.
Saves accepted responses so a later session can continue.

Yield does not replace skills.A skill supplies judgment. The workflow decides when that judgment runs and what must be true before work finishes.

02 / Files

One source. Several discovery files.

Canonical skill workflow

skills/review/

skill.jsonName, language, version, and launcher
SKILL.mdPurpose and agent instructions
main.tsOrder, checks, and outcomes
fixtures/Deterministic test responses
.yield/runs/Saved local runs

You edit these files.

Generated adapters

Agent discovery folders

.cursor/skills/review/SKILL.md
.agents/skills/review/SKILL.md
.claude/skills/review/SKILL.md

Yield owns these files. Regenerate them.

03 / Builder

Create one, or convert an existing skill.

Start from a description

Tell your coding agent what the workflow should do. The builder writes the workflow, tests it, and registers its adapters.

Use Yield to create a tested skill workflow
for releasing my package.

Start from `SKILL.md`

The builder can convert an existing skill into a best-effort starting point. Review the result, or ask your coding agent to verify and improve it for your project.

Use Yield to convert my existing release
SKILL.md into a tested skill workflow.

Keep useful guidance.Move repeatable order, branches, checks, approvals, and finish rules into code. Keep judgment, examples, and tool guidance available to the coding agent.

Before you ask: Create and test one Yield workflow by hand →

04 / Adapter

Registration creates a pointer, not a copy.

Canonical `SKILL.md`

Describe what the workflow does and when the agent should use it. Keep detailed judgment here when the workflow calls an agent task.

---
name: review
description: Check and review a branch before it is shipped.
---

Use this workflow before a branch is shipped.

Generated agent adapter

The adapter keeps the same name and description. It points back to the canonical directory and gives the agent exact start and resume commands.

---
name: review
description: Check and review a branch before it is shipped.
---

Run the canonical workflow at skills/review.
Use the package-local yskill launcher.
Inspect and respond to the pending operation.

This is not a conversion into a second skill.The generated file is a small discovery adapter. Workflow code, dependencies, fixtures, and run state remain under skills/release/.

05 / Trigger

The agent discovers it. Yield runs it.

01
Start a new agent session.
After registration, run /review where slash skills are supported or ask the agent to use the review skill.
02
The coding agent matches the adapter.
The adapter name and description tell the agent when to load it.
03
The adapter starts the canonical workflow.
It runs the package-local yskill command with skills/review.
04
The workflow requests one operation.
Yield may run a command, ask the agent, ask a person, or check a requirement.
05
Yield saves the response.
The workflow restarts, replays accepted work, and moves to the next unanswered step.
06
The run reaches an outcome.
It completes, blocks with a reason, or records a refusal.

user request→agent match→generated adapter→skill workflow→saved run

06 / Use

Create once. Register for each agent.

Create and check · TypeScript

The final command generates adapters for detected agents. Use register-all when the repository contains several skill workflows. Registration updates adapters without moving the canonical workflow.

One workflow. Small adapters.

Instructions for one capability.

Skills and code in one process.

Start from a description

Start from SKILL.md

Canonical SKILL.md

Generated agent adapter

Start from `SKILL.md`

Canonical `SKILL.md`