Understand ingredients, recipes, and cookbooks

A recipe is the complete page someone follows to finish a task. An ingredient is a reusable piece of source documentation used to write that page. A cookbook is a page that helps readers choose a recipe.

Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.

Use recipes for task-oriented how-tos

Use the built-in how-to template for a task page, or recipe when the page should participate in Shoalrun's recipe and cookbook features. Both take a reader from a known starting state to a verifiable result. Give it prerequisites, ordered actions, failure guidance, and a final success check. A recipe can be a short, directly authored page; it does not require ingredients, a YAML composition spec, or a cookbook.

Use the built-in explanation template to explain a concept or help readers understand a system. Use a reference page to describe fields, commands, or API behavior. Existing how-tos can keep their current type, stable ID, and route until a deliberate content revision calls for a change. A page's type does not prove its instructions have been tested.

Writing task	Starting format
Build this site and verify its output	A recipe.
Explain how the compiler produces HTML and Markdown	An explanation page.
Look up CLI flags or configuration fields	A reference page.
Reuse the same build instructions across several recipes	An ingredient included by those recipes.
Help a reader choose build, audit, or preview	A cookbook pointing to complete recipes.

The bundled shoalrun-recipes skill follows these choices. See use the agent skills for a copyable authoring request.

One example from Shoalrun

Suppose you need two sets of instructions:

Build and check a page. Compile the CLI, build the docs, and check the HTML and Markdown files.
Build and audit the site. Do those same three steps, then run the project audits.

Both recipes need the same build instructions. We keep those instructions in ingredient files and use them in both recipe specs:

Two recipes reuse the same source instructions — The compile, build, and artifact-check ingredients are used in both recipes. The build-and-audit recipe also includes the audit ingredient. These arrows describe authoring reuse; they do not run commands.

The Site workflows cookbook offers these two finished recipes. Choosing the audit path displays all four steps. The reader does not have to find or assemble the ingredients.

What each file does

These are real files in this checkout:

File	What the author puts there	What it contributes
`docs/content/ingredient-build-site.mdx`	The build command, explanation, required inputs, expected outputs, and a success check.	Reusable source instructions for one step.
`docs/recipe-specs/audit-docs.yaml`	An ordered list of ingredient files, starting inputs, and the final goal.	Instructions to the recipe assembler about which steps to copy and how to order them.
`docs/content/recipe-audit-docs.mdx`	The assembled, reviewed recipe.	The complete page a person or agent follows.
`docs/config/cookbooks.yaml`	Choice labels and the published recipe ID for each option.	The chooser's options and descriptions.
`docs/content/cookbook-site-workflows.mdx`	An introduction and `<CookbookChooser id="site-checks" />`.	The page where readers choose their task.

What happens, and when

An author prepares ingredients and a recipe spec. Ingredients contain prose and commands. Their optional workflow metadata names the values or artifacts each step needs and produces.
The author runs recipe draft. The assembler copies ingredient bodies into a new MDX draft, combines identical prerequisites, and writes the declared handoffs and checks. It checks that each named input is available from setup or an earlier step.
The author reviews and tests the recipe, then publishes it. A normal site build turns the recipe page into HTML and Markdown. It also builds the cookbook page and its choice list.
A reader chooses a recipe in the cookbook. The browser fetches the already-published recipe and displays its instructions. The reader or their agent runs the commands and checks the results.

Selecting a cookbook option does not assemble ingredients or run a task. It loads finished recipe content. The cookbook's own introduction and choice descriptions come from its page and configuration.

What changing an ingredient updates

A generated recipe is a snapshot of its ingredients. Editing an ingredient does not immediately change a published recipe. Regenerate the affected recipe, review the changes, and rebuild the site.

Shoalrun's five repository recipes have a maintenance script that updates their snapshots together and a test that detects stale snapshots. The composition guide shows that workflow. Other projects can keep generated recipes as drafts and edit them independently.

For example, if the docs build command changes, update the build ingredient once and regenerate the recipes that use it. The cookbook continues pointing to the same published recipe IDs.

How agents use this

Give an agent the source material that matches its task and the outcome you want.

Agent task	What to give it	What these files help it do
Write or maintain documentation	Ingredient source files, the recipe spec, and project evidence.	Reuse instructions and prepare consistent recipe drafts.
Complete a task	The finished recipe's Markdown.	Follow the commands, pass values between steps, and evaluate the stated success checks.
Choose a task	The cookbook's Markdown.	Read each option's purpose and follow the appropriate recipe link.

The recipe assembler does not call a model. It does not execute commands, validate data types, or prove that a task succeeded. A declared output such as builtSite is a name and description; it does not create a directory or a shell variable. The recipe's commands produce the actual result.

A recipe's Read as Markdown link contains its complete published instructions. A cookbook's Markdown lists the choices and recipe links. The browser selection has no separate published Markdown endpoint. Download Markdown saves the selected recipes' instructions in a file you can give to an agent.

Try a complete workflow

Use the Authoring workflows cookbook to add a guide, preview a change, or refresh the agent bundle in this repository. Each choice is a complete recipe with its own setup and final check.

The email example demonstrates passing a returned message ID into a delivery check. It runs against a local simulator and sends no email.