diff --git a/.changeset/readme-trigger-skill.md b/.changeset/readme-trigger-skill.md index 410fc78..23af5f2 100644 --- a/.changeset/readme-trigger-skill.md +++ b/.changeset/readme-trigger-skill.md @@ -2,5 +2,5 @@ "@operatorstack/yield": patch --- -Explain how to run a registered skill from a new coding-agent session and fix -the README logo on npm. +Explain how to register and run a skill, fix the README logo on npm, and point +readers to current public documentation. diff --git a/README.md b/README.md index 27fad97..8af10fe 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@

Website · - Documentation · + Documentation · npm · GitHub

@@ -247,6 +247,7 @@ loop, multi-agent orchestrator, or security sandbox. ## Documentation and development +- [Read the public documentation](https://yield.operatorstack.systems/docs/) - [What a skill workflow is](docs/skill-workflows.md) - [Ten-minute TypeScript quickstart](docs/quickstart.md) - [Working examples in all four languages](docs/examples.md) @@ -267,4 +268,5 @@ updates, database migration, security audit, and package release. --- -Yield is MIT licensed. This repository is its canonical source. +Yield is MIT licensed. This repository contains its canonical source and +versioned technical documentation. diff --git a/docs/README.md b/docs/README.md index 5cc75eb..0a3a4fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,20 @@ # Yield documentation -You already know the skill workflow. You may be repeating it in a prompt: +Move repeatable coding-agent instructions from words into code. + +The [public documentation](https://yield.operatorstack.systems/docs/) is the +best place to start. This directory contains the versioned technical source +that stays with each Yield revision. + +You may already be repeating a workflow in a prompt: > Run the checks. Review the diff. Stop if anything critical remains. Ask me > before publishing. If the session ends, start again without losing our place. Yield lets you keep the useful words and put the repeatable flow in normal -code. The coding agent still investigates, reviews, edits, and explains. Your program -decides which operation comes next, what evidence must exist, and when the run -is finished. +code. The coding agent still investigates, reviews, edits, and explains. Your +program decides which operation comes next, what evidence must exist, and when +the run is finished. A **skill workflow** is a portable, executable process that combines agent skills with deterministic code, state, and verification. The canonical @@ -17,19 +23,21 @@ and start it. ## Start here -1. [Understand skill workflows](skill-workflows.md) — the canonical workflow, +1. [Read the public guide](https://yield.operatorstack.systems/docs/) — the + quickest path from installation to a running workflow. +2. [Understand skill workflows](skill-workflows.md) — the canonical workflow, generated adapter, and execution boundary. -2. [Build and run your first skill workflow](quickstart.md) — a TypeScript +3. [Build and run your first skill workflow](quickstart.md) — a TypeScript workflow you can test in about ten minutes. -3. [Register it with your coding agents](agent-setup.md) — keep one workflow +4. [Register it with your coding agents](agent-setup.md) — keep one workflow and generate the small discovery adapters each agent needs. -4. [Learn the primitives](primitives/README.md) — commands, model work, human +5. [Learn the primitives](primitives/README.md) — commands, model work, human input, gates, and honest outcomes. -5. [Follow a complete tutorial](tutorials/README.md) — review, approval, +6. [Follow a complete tutorial](tutorials/README.md) — review, approval, environment repair, bounded debugging, and migration. -6. [Browse the examples](examples.md) — working skill workflows in Go, +7. [Browse the examples](examples.md) — working skill workflows in Go, TypeScript, Python, and Rust. -7. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's +8. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's verified converter after you understand one ordinary workflow. ## The split to remember @@ -52,7 +60,6 @@ response and resumes from the next unanswered operation. - [Skill workflow concepts](skill-workflows.md) - [CLI commands](reference/cli.md) - [Coding-agent registration](agent-setup.md) -- [Agent Plugins and Yield](agent-plugins.md) - [Run, pause, resume, and replay](reference/execution-model.md) - [The four SDKs](reference/sdk-parity.md) - [Guarantees and limits](reference/guarantees.md) diff --git a/docs/agent-setup.md b/docs/agent-setup.md index 8413a72..9d27bb5 100644 --- a/docs/agent-setup.md +++ b/docs/agent-setup.md @@ -51,6 +51,24 @@ workflow. Yield refuses to overwrite a user-owned skill with the same name. Names must also be unique across languages because coding agents use one project-level skill namespace. +## Run the registered skill + +Start a new coding-agent session after registration. Where slash skills are +supported, run the generated skill by name: + +```text +/review +``` + +Otherwise, ask the agent to use it: + +```text +Use the review skill to check the current branch. +``` + +The host owns how the request is presented. The generated adapter starts the +canonical workflow under `skills/review`; it does not contain a second copy. + ## Copy this to your agent Replace the bracketed values, then paste this into the coding agent already diff --git a/docs/quickstart.md b/docs/quickstart.md index 6d5bc86..f8c1d26 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -12,8 +12,7 @@ You need Node.js 24 or newer. mkdir yield-example cd yield-example npm init -y -npm install --save-exact @operatorstack/yield@0.1.29 \ - --registry=https://get.operatorstack.systems/npm/ +npm install --save-exact @operatorstack/yield npm exec -- yskill --version ``` @@ -125,9 +124,6 @@ Yield keeps one canonical skill workflow and writes only generated adapters: .claude/skills/review/SKILL.md # Claude Code ``` -Start a new agent session after registration, then invoke `/review` or ask for -the task described by the skill. - Check the generated adapters: ```bash @@ -135,6 +131,24 @@ npm exec -- yskill doctor skills/review \ --agent cursor,codex,claude-code ``` +## 6. Run the skill + +Start a new coding-agent session so it discovers the generated adapter. Where +slash skills are supported, run: + +```text +/review +``` + +Otherwise, ask the agent in plain language: + +```text +Use the review skill to check the current branch. +``` + +The agent starts the canonical workflow in `skills/review` and follows each +operation until the run completes, blocks, or is refused. + ## Run an existing workflow Initialization is only for creating or wrapping a workflow. For an existing diff --git a/scripts/readme.test.mjs b/scripts/readme.test.mjs index 11feb57..9a97e76 100644 --- a/scripts/readme.test.mjs +++ b/scripts/readme.test.mjs @@ -106,3 +106,20 @@ test("README uses the edge-cropped Yield mark", async () => { assert.match(mark, /viewBox="0 0 60 60"/); assert.match(mark, / { + const [readme, docsIndex, quickstart, agentSetup] = await Promise.all([ + text("README.md"), + text("docs/README.md"), + text("docs/quickstart.md"), + text("docs/agent-setup.md"), + ]); + + assert.match(readme, /href="https:\/\/yield\.operatorstack\.systems\/docs\/">Documentation<\/a>/); + assert.match(docsIndex, /\[public documentation\]\(https:\/\/yield\.operatorstack\.systems\/docs\/\)/); + assert.match(quickstart, /npm install --save-exact @operatorstack\/yield/); + assert.doesNotMatch(quickstart, /get\.operatorstack\.systems\/npm|@operatorstack\/yield@0\./); + assert.match(quickstart, /^## 6\. Run the skill$/m); + assert.match(quickstart, /^\/review$/m); + assert.match(agentSetup, /^## Run the registered skill$/m); +});