shinyobjectz/workbook-standard

Latest recorded source activity: September 8, 2026 at 17:09

SkillsMP catalog refreshed: November 12, 2026 at 12:52

skills collected: 1

GitHub stars: 0
GitHub forks: 0

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/shinyobjectz/workbook-standard.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# The Workbook standard A **workbook** is a zip file that answers a machine-learning question in a form another agent can execute. It is three things at once, and the combination is the point: - a **notebook** — cell-delimited source in whatever language the answer needs; - a **skill** — `SKILL.md`, so an agent knows what this is and when to reach for it; - an **MCP server** — dependency-free, stdio, installs the environment and runs the cells. The hand-off it exists for: someone asks a question, gets an answer with citations, downloads a workbook, drops the folder in front of a coding agent, and says "set this up and run it". The agent reads `SKILL.md`, registers `mcp/server.py`, then calls `workbook_check`, `workbook_setup`, `workbook_run`. Nothing in that sequence asks it to guess a dependency, a model id, or a command. Read [SPEC.md](./SPEC.md) for the standard. It is the normative document; everything else here is an implementation of it. ## Why not just a notebook A notebook alone loses what made the answer correct. It does not say which file to take out of a repository that holds forty of them, what the download actually weighs, which packages the imports imply, what hardware the code assumes, or which paper the method came from. A workbook keeps that in `workbook.json`, and the runner reads it rather than inferring it. The manifest is also what makes this framework-agnostic. Nothing in it is Python. A runtime is a declaration — interpreter, dependency manager, setup commands, argv prefix — so a Rust workbook and a browser/WebGL workbook are the same shape as a PyTorch one, and one server drives all of them. ## What is in this repository | path | what it is | |---|---| | `SPEC.md` | the standard | | `manifest.ts` | schema, types, cell-marker parsing, and the nine completeness rules | | `runtimes.ts` | per-runtime defaults: setup, exec prefix, dependency file | | `templates.ts` | `SKILL.md`, `README.md`, `.mcp.json`, links, notebook scaffolds | | `pack.ts` | manifest plus notebook to zip | | `form.ts` | the intake form: how a workbook gets scoped before it is built | | `templates/server.py` | the MCP server that ships inside every workbook | | `conformance/` | a language-neutral validator and a live MCP handshake test | ## Conformance The validator works on an unpacked workbook directory, so it is not tied to this implementation. ```bash python3 conformance/run.py # the whole suite python3 conformance/validate.py path/to/workbook # validate any workbook, from any implementation python3 conformance/handshake.py path/to/workbook # drive its MCP server the way a client would python3 path/to/workbook/mcp/server.py --selfcheck ``` `run.py` closes the loop twice. It assembles the hand-written example in `conformance/example/`, validates it, and drives its server through seventeen protocol checks; then it packs a workbook with the TypeScript implementation and puts that one through the same three stages. It also asserts that each of the nine completeness rules actually rejects a workbook that breaks it, because a validator nobody has seen fail is not evidence of anything. The validator and the handshake need no packages installed, and the handshake speaks raw JSON-RPC rather than using a client library. That is deliberate: the tests have to run on the same bare machine the server is designed to start on. ## Using the TypeScript implementation ```ts import { normalize, pack, validate } from "workbook-standard"; const manifest = normalize(draftFromYourGenerator, notebookSource); const { zip, issues, files } = pack({ manifest, notebook: notebookSource }); ``` `pack` renders the environment file from the declared packages, the skill and readme from the manifest, and copies in the MCP server and the spec, then validates the result. A generator only has to supply what needs judgement: what to run, what it needs, and why. There is no build step and no bundler requirement. `templates/server.py` and `SPEC.md` are inlined into `generated/assets.ts` by `node tools/gen-assets.mjs`, which `--check` verifies has not drifted, so the packer works in a Worker, in Node, and under any bundler. Relative imports carry explicit `.ts` extensions so the sources run unbuilt under Node's type stripping; a TypeScript consumer needs `allowImportingTsExtensions`. ## Status Version 1. `workbook: "1"` in a manifest refers to `SPEC.md` in this repository. A reader that does not recognise the version must refuse rather than guess.

Loading the repository README…

Skills in this repository

Software Developers

1 occupation category · 100% classified

skill

occupation

description

updated

example-workbook

Software Developers

The smallest workbook that is still a workbook. Use it to check a runner against the standard.

2026-09-08

Showing 1 of 1 collected skill.