Have an idea but don't want to write it yourself? Ask your AI. Paste this:

Write a promptbai recipe for [describe what you want built] by following the guide at https://promptbai.bonq.foo/recipe-format.md. Test it with a fresh agent if you can, show it to me, and submit it once I'm happy.

Already have a recipe file? Submit it here. This guide is also available as Markdown at /recipe-format.md.

Writing a recipe for promptbai

This guide is for AI agents (and people) who want to write a recipe for promptbai (https://promptbai.bonq.foo) and submit it. Read all of it before you start. A submission that follows it is far more likely to be published.

What a recipe is

A recipe is one Markdown file that another AI agent follows to build a small app or tool for a person who usually can’t code. That person finds the recipe on the site, copies one sentence, and pastes it into their agent. From then on, the recipe is all the agent has to go on.

So a recipe has two readers:

  • The person, who sees the frontmatter as an app-store page: name, tagline, description, what they get, what they need, how much effort it takes.
  • The building agent, who reads the body and does the work, often without anyone available to answer questions.

When the site publishes a recipe, it adds a standard preamble that tells the building agent how to behave: talk plainly, ask one question at a time, use defaults when nobody answers, write promptbai.json, check its work, and hand off clearly. Don’t repeat that in your recipe.

What makes a good recipe

  1. Useful to an ordinary person. It solves a real, everyday problem: a household, hobby, small business, school or personal one. “A tracker for my plants’ watering” beats “a REST API boilerplate”.
  2. Runnable without programming knowledge. Prefer a single index.html that opens by double-clicking, works offline, needs no account, no server, no build step, and keeps data on the person’s machine. If you need more (an installed app, a script, a hosting step), say exactly why and make the agent do the hard parts.
  3. Decided, not vague. Every question you list has a default. Every rule an agent could read two ways is spelled out with its edge cases: what counts as a streak, how rounding works, which week day comes first, what happens to data on restore. Test agents consistently stumble on unstated rules.
  4. Checkable. Acceptance checks are concrete, map to features, and can mostly be verified by an agent: pure logic in functions it can test with node, browser behaviour with a headless browser. In a single-file app, suggest keeping the logic in a <script id="core"> block.
  5. Safe and honest. Nothing is sent anywhere the person didn’t agree to. Personal data stays local. The person’s data survives updates. Nothing pretends to be something it isn’t.
  6. Kind to beginners. The hand-off tells the person, in plain words, where their thing is, how to open it, how to back up their data, and which choices were made for them.

The file

A recipe is UTF-8 Markdown with YAML frontmatter. The file name is the slug and becomes the address: habit-tracker.md is published at /r/habit-tracker. Slugs use lowercase letters, digits and hyphens.

Frontmatter

---
title: Habit Tracker                      # 2–40 characters
tagline: Tick off daily habits and watch your streaks grow   # 10–90 characters, one line
description: >                            # at least 40 characters; 2–4 sentences for people, no jargon
  A calm, good-looking page where you list the habits you want to build and tick them off
  each day. It shows your streaks and a calendar, and everything stays on your computer.
category: productivity                    # productivity | money | home | learning | fun | websites | computer-tools
icon: "✅"                                 # one emoji (at most 4 UTF-16 code units)
color: "#22c55e"                          # tile color, #rrggbb
you_get: A page that opens in your web browser. Works offline, no account.   # at least 10 characters
you_need:                                 # at least one item, in plain words
  - An AI assistant that can create files (Claude, Codex, Cursor or similar)
  - A web browser
effort: easy                              # easy | medium | advanced, from the person's point of view
build_time: About 15 minutes
works_with: [Claude Code, Codex, Cursor, ChatGPT]   # at least one
author: Your name or handle               # optional; shown as "By …" on the recipe page
version: 1.0.0                            # semantic version
updated: 2026-10-20                       # YYYY-MM-DD
changelog:                                # newest first; the first entry's version must equal `version`
  - version: 1.0.0
    date: 2026-10-20
    note: First release
---

effort in human terms: easy means the agent does almost everything and the person answers a few questions. medium means the person clicks through a couple of things themselves, like downloading a file from their bank. advanced means installing software or setting up an account.

The published .md carries a short frontmatter for agents (title, slug, version, updated, sha256, category, and the source and check URLs). The human-facing fields are in /r/<slug>.json.

Body

Use these sections, with these exact ## headings, in this order. You may add extra sections (for example ## Technical specification for a long, detailed spec) between Build steps and Acceptance checks.

  1. ## Goal: what is being built and for whom, in two or three sentences.
  2. ## Before you start, ask the person: a numbered list of the few choices that matter to the person, each with (Default: …). Three to five questions is plenty.
  3. ## Features: what it must do, as a bulleted list with bold lead-ins. Be concrete about behaviour, and spell out rules and edge cases.
  4. ## Constraints: technology and scope limits: file layout, storage (with a schemaVersion so updates can migrate data), no external requests, accessibility, light and dark mode, small screens.
  5. ## Build steps: an order of work that keeps something working at every step.
  6. ## Acceptance checks: what the agent must verify before calling it done. Each check should be concrete and map to a feature.
  7. ## Hand-off to the person: what to tell them at the end, in plain words.

Template

Copy this and fill it in:

---
title:
tagline:
description:
category:
icon: ""
color: "#"
you_get:
you_need:
  - An AI assistant that can create files (Claude, Codex, Cursor or similar)
effort: easy
build_time: About 20 minutes
works_with: [Claude Code, Codex, Cursor]
author:
version: 1.0.0
updated: YYYY-MM-DD
changelog:
  - version: 1.0.0
    date: YYYY-MM-DD
    note: First release
---

## Goal

## Before you start, ask the person

1. … (Default: …)

## Features

- **…:** …

## Constraints

- One self-contained `index.html` with no external requests. It works offline when opened from the file system.
- Data in `localStorage` (or IndexedDB for larger data) under one key, with a `schemaVersion`. Wrap reads and writes in try/catch.
- Light and dark mode, accessible, and comfortable at 360px wide.

## Build steps

1. …

## Acceptance checks

- …

## Hand-off to the person

Tell them:
- Where the file is and how to open it.
- Where their data lives and how to back it up.
- Which choices you made for them and how to change them.

Test it before you submit

The best recipes have been built at least once by an agent that had nothing but the recipe:

  1. Give a fresh agent (one with no memory of writing the recipe) only the recipe, and tell it the person is unavailable, so it must use the defaults.
  2. Let it build in an empty folder and run every acceptance check it can.
  3. Ask it what was ambiguous, contradictory or impossible, and what it had to decide for itself.
  4. Fix the recipe so the next agent doesn’t have to guess. Repeat if the fixes were large.

Mention in your submission’s note how you tested it.

Submitting

Check your recipe first. Validation returns a list of exact problems to fix, and changes nothing.

  • MCP (https://promptbai.bonq.foo/mcp): call validate_recipe(markdown), then submit_recipe(markdown, slug?, author?, contact?, note?).
  • HTTP: POST https://promptbai.bonq.foo/api/recipes/validate with JSON {"markdown": "…"}, then POST https://promptbai.bonq.foo/api/recipes with {"markdown": "…", "slug": "…", "author": "…", "contact": "…", "note": "…"}. Only markdown is required. The slug defaults to one made from the title.
  • People: paste or upload the file at https://promptbai.bonq.foo/submit.

Only submit with the person’s agreement, and never include their personal details unless they asked to be credited or contacted. Recipes are at most 200 KB.

Every submission is read by an editor, who decides whether it is published, usually with small edits for consistency. Submitting with an existing recipe’s slug proposes an update to that recipe. By submitting, you agree that promptbai may publish, edit and share the recipe for free, credited to author if you give one.

Versioning

  • Patch (1.0.0 → 1.0.1): wording, clarifications and better defaults.
  • Minor (1.0.0 → 1.1.0): adds or improves features without breaking what someone already built.
  • Major (1.0.0 → 2.0.0): changes that need the person’s consent to apply, such as a new data format or removed features.

Add a changelog entry for every version and update updated.