📖 howto

Easy:

1. Open the fridge. 2. Put the elephant in. 3. Close the fridge.

That is how most datasets think tasks work. Here is how howto writes it:

## Steps
1. **Open the fridge.** → *Expect:* door open, shelves visible, light on.
2. **Insert the elephant.** [BRANCH: elephant does not fit → F1]
3. **Close the fridge.** → *Expect:* door latched; no trunk protruding.

## Failure modes & recovery
- **F1 Elephant exceeds fridge capacity:** acquire a larger fridge, or a smaller elephant.

## Verification
Opening the fridge reveals one chilled elephant.

Things are always more complicated than "open, put, close", and the complications are exactly the knowledge agents are missing. Every human knows the real steps, the expected observations, the branches, the failure modes. No corpus writes them down. This one does.

And here is a real one, from transit/ride-a-subway.md:

3. **Obtain or validate fare.** [BRANCH: tap-to-pay bank card | transit card with
   balance | ticket machine | transit app QR] At a machine: select destination or fare
   type, pay, take the ticket. ⚠️ *Irreversible:* multi-day passes and non-refundable
   tickets — confirm fare type before paying. → *Expect:* you hold a valid fare medium.
4. **Pass the fare gate.** Tap or insert; walk through on green/open. → *Expect:* gate
   opens and (on card systems) displays balance or fare; if rejected, F1.
...
- **F2 Boarded the wrong direction:** exit at the next station, cross to the opposite
  platform (may require staying inside the paid area), reverse.

Web agents, computer-use agents, and household robots fail at everyday tasks less from weak reasoning than from missing grounded procedural knowledge: canonical step order, the observation that confirms each step worked, the decision branches, the recovery paths, and which steps are irreversible.

agency-agents (134k stars) covers who an agent is. howto is the complement: what an agent knows how to do. Ride a subway, buy and return a product, create an account, make coffee, load a dishwasher, wait in line, pay at a cashier.

The schema turns prose into training substrate. One corpus yields, simultaneously:

git clone https://github.com/ShirleyHuang11/howto.git && cd howto
pip install pyyaml                       # the only dependency

./scripts/validate.sh                    # validate every recipe against the schema
python3 scripts/stats.py                 # per-domain coverage dashboard
python3 scripts/export.py --format sft   # instruction-tuning pairs (JSONL)
python3 scripts/export.py --format eval  # task specs with success criteria (JSONL)
python3 scripts/export.py --format json  # full structured recipes

Or just read one: transit/ride-a-subway.md · embodied/kitchen/load-a-dishwasher.md · daily/social/pay-at-a-cashier.md

One task = one markdown file, separated by domain (domains.json is the registry, INDEX.md is the full linked index, and the frontmatter is formally specified in schema/recipe.schema.json). Every recipe shares one skeleton:

Goal → Preconditions → Steps (every step ends with → *Expect:* …)
→ Decision points → Failure modes & recovery → Verification
→ Variations (locale/platform) → Safety & privacy (⚠️ irreversible steps inline)

objects: [dishwasher, plates, cutlery, detergent-pod]
affordances: [door-open, rack-slide, grasp, place]
workspace: kitchen
safety: {sharp_objects: true, fragile: [glasses], human_proximity: pause}

📊 Live coverage anytime: python3 scripts/stats.py

1. Every step states its expected observation. A step list without expectations is prose; the Expect: clause is what makes a recipe executable and trainable.
2. Verification is a predicate, not a vibe. "You are done when…" must be checkable by a program or a stranger — it compiles into a reward function.
3. Irreversible steps are marked ⚠️ inline — payments, deletions, hot liquids, handed-over packages. Agents must learn where to stop and confirm, and that signal lives in the data.
4. Failure modes are first-class. Real procedures go wrong in known ways; the recovery paths are half the knowledge.
5. Generic first, locale variants second. The generic recipe stands alone; us-nyc / jp-tokyo / cn-beijing variants layer on top.
6. Multimodal, with text as the floor. Recipes can attach diagrams, photos, and clips per step via the media frontmatter (roles: action-demo, expected-observation, diagram, warning, overview), each with a full alt description so every recipe still trains text-only models. See the fare-gate diagram in transit/ride-a-subway.md and the rack layout in embodied/kitchen/load-a-dishwasher.md.

The corpus spans 1137 recipes across all 12 domains and keeps growing. Where help lands hardest:

• Locale variant packs: jp-tokyo, cn-beijing, de-berlin, and yours
• reviewed and verified promotions (agent-executability evidence; see CONTRIBUTING)
• Embodied recipes → simulator task compiler
• Multimodal coverage: a diagram for every embodied recipe
• Pre-built SFT/eval exports as tagged releases

One recipe = one markdown file = one PR.

1. Copy TEMPLATE.md into the right domain directory
2. Write the procedure you actually know (original content only)
3. ./scripts/validate.sh until green ✅
4. Open the PR

The short rules: every step needs an Expect: · verification must be checkable · irreversible steps get ⚠️ · embodied recipes need the robot frontmatter. Full rules in CONTRIBUTING.md.

🌍 Locale expertise is especially welcome. Recipes for how things work in your city make agents useful beyond the defaults.

Recipe content is CC-BY-4.0: training (including commercial) is fine with attribution; see LICENSE. Export formats are documented in scripts/export.py's header, and each JSONL record carries the recipe id for attribution. If you use the corpus in research:

@misc{howto2026,
  title  = {howto: an open library of everyday procedural knowledge for training agents and robots},
  author = {{howto contributors}},
  year   = {2026},
  url    = {https://github.com/ShirleyHuang11/howto}
}