authoring-recipes

name	authoring-recipes
description	Guidelines for authoring fullstackrecipes content - setup recipes, exposed skills (in ./skills/), cookbooks, templates, and installable registry utilities. Use when creating or editing any catalog content. For maintainers building the fullstackrecipes project, not developers consuming the stack.

Authoring Recipes

Guidelines for writing fullstackrecipes content. This skill is for maintainers building out the fullstackrecipes project itself, not for developers consuming the stack (see use-fullstackrecipes for that).

fullstackrecipes is a site that helps developers and agents build better full stack apps by shipping an opinionated stack with setup instructions, best practices, and ready-to-clone starting points. It exposes four kinds of resources: setup recipes, skills, cookbooks, and templates.

Two Skill Directories — Don't Confuse Them

This repo contains two separate skills/ trees. They serve opposite audiences:

• ./skills/ — the skills this repo exposes/ships to consumers. These are the day-to-day, agent-facing workflow guides (drizzle-queries, authentication-best-practices, workflow-best-practices, etc.) that the website reads (and serves as Markdown via the .md endpoints) and that consumers install via bunx skills add. When this skill says "a skill," it means one of these.
• ./.agents/skills/ — the skills used internally by this workspace to build the fullstackrecipes project. This very authoring-recipes skill lives here. These are not exposed to consumers and are not part of the resource catalog.

When authoring or editing an exposed skill, you edit it under ./skills/<slug>/SKILL.md. Never put consumer-facing skill content in .agents/skills/.

Recipe Tiers

Every catalog item is one of three tiers, plus an optional template attached to a cookbook. The tier determines what it installs and what its prose may assume. The single source of truth for the catalog (slugs, titles, descriptions, tags, requires, and template links) is src/lib/recipes/data.tsx.

Tier 1 — Setup recipes (type: "setup")

One-time setup that installs files, dependencies, and config for a single concern (e.g. neon-drizzle-setup, better-auth-setup).

• Install surface stays atomic. A setup recipe installs only its own slice so the dependency graph stays composable and individual recipes can be adopted standalone.
• Declare prerequisites in requires and state them up front. Reference the prereq; do not re-teach it. A minimal fallback for one or two missing prereqs is fine. Standalone usability lives here, not in the skill tier.

Tier 2 — Skills (type: "skill")

Day-to-day, agent-facing workflow guides for an already-configured tool (e.g. drizzle-queries, authentication-best-practices). These are the skills this repo exposes; they live under ./skills/ (not .agents/skills/ — see above).

• Skills are authored, not recipe docs. The source of truth is the hand-authored ./skills/<slug>/SKILL.md (YAML frontmatter + body). The website reads their body directly from that file (and serves it via the .md endpoints), so edits ship as soon as they land — there is no build step. They have no docs/recipes/<slug>.md.
• Lead with ### body sections. The loader (src/lib/recipes/loader.ts) strips the YAML frontmatter and everything up to the first ### heading, then re-derives the # Title, description, and a ## Prerequisites list from data.tsx metadata. So the authored file leads with # Title + description + prereqs for standalone reading, but the shipped body starts at the first ### section. Use ### for your top-level body sections.
• Name skills for what they teach, not the tool they wrap. Use a descriptive slug and title (drizzle-queries, testing-best-practices, ralph-loop-workflow), not a using-* prefix. The name: frontmatter and the slug (folder name) must match, and the # Title H1 must match the title in src/lib/recipes/data.tsx. When renaming a slug, add the old slug to recipeRedirects in data.tsx.
• The type is derived from the Skills tag. An item becomes a skill (type: "skill") when its tags include "Skills" in data.tsx; everything else is a setup recipe. There is no separate type field to set.
• Write for an agent, not a human tutorial. Lead with the pattern and the code; skip hand-holding prose, "step 1/2/3" walkthroughs, and motivation paragraphs the agent already understands. Imperative, concise, example-first.
• Assume the canonical stack. Do not hedge. Write to the exact world the setup recipes produce. Import from the real paths (@/lib/db/client, @/lib/auth/server, @/lib/logging/logger, @/components/ui/*, etc.). Never add "if you set this up differently" caveats — that defensive framing is what dilutes a skill's value.
• The canonical stack is defined by capability, not by cookbook name: a Postgres database via Drizzle, Better Auth sessions, structured logging, shadcn/ui components, and the test harness. A skill may assume any capability its requires chain provides.
• Never reference back to how the stack was set up. A skill only teaches how to do the thing at runtime. Do not name-drop the setup recipe ("set up by the X recipe", "configured in Y", "from the Z setup") — it adds nothing while the skill is running. The requires metadata already tracks the setup trail and is surfaced as a Prerequisites section, so the body never needs to.
• Skills are installed via the skills CLI, not pasted as content. They persist as agent skills for ongoing work.

Tier 3 — Cookbooks (isCookbook: true)

The canonical assembled reference: an ordered, two-phase setup artifact (see below).

Authoring Cookbooks

A cookbook is a setup artifact, not a reading bundle. Running a cookbook leaves the project with both the configured stack and the installed skills.

Two-phase model

1. Setup chain — the setup recipes, run in order, install files/deps/config.
2. Skill install — the skills are installed via bunx skills add so the agent retains the day-to-day patterns afterward.

Ordering

List each skill right after its setup recipe, not all skills at the end. The skill follows the thing it teaches you to use.

Rendering (handled automatically)

When a cookbook is assembled, the loader branches on type:

• Setup recipes inline their full content.
• Skill recipes render as a compact section: ## <title> + motivation (the description) + the bunx skills add ... -s <slug> command. Their content is not inlined — the cookbook installs them as skills.

So you do not duplicate skill content into a cookbook. Just include the skill slug in recipes in the right position; the install section is generated from its metadata.

Templates

Templates are clone-and-go starting points that ship the fully-assembled output of a cookbook, so a consumer can begin from working code instead of running every setup step by hand. They are not a separate catalog tier — a template is attached to a cookbook via two fields in data.tsx:

• template — the git clone path, built from TEMPLATE_BASE (e.g. `${TEMPLATE_BASE}/base-app#main`).
• githubUrl — the GitHub URL for browsing the template source, built from GITHUB_TEMPLATE_BASE.

The template source lives under templates/<name>/ at the repo root and is a real, runnable project. A cookbook that surfaces a clonable starter also carries the "Starter template" tag (see getStarterTemplates); base-app, auth, stripe-sync, and ai-workflow are the current ones.

Authoring rules:

• Keep the template in sync with its cookbook. A template must reflect the exact output of running its cookbook's recipes in order. When you change a setup recipe, update the matching template directory too, or the clone-and-go path drifts from the documented one.
• Templates are the assembled stack, not docs. Don't add tutorial prose or recipe markdown into a template — it ships as a working app (with its own agents.md, .agents/skills/, etc.), and the prose lives in the recipes/cookbook.
• Point at templates from the cookbook, don't duplicate them. Only set template / githubUrl on the cookbook; the website renders the clone command from that metadata.

Installable Utilities

When writing recipes that include installable utilities, use the {% registry %} tag to provide both CLI installation and source code viewing.

Registry Tag

The registry tag renders:

1. Install via shadcn CLI - A copy-able command to install the utility
2. Source code viewer - Collapsible code block showing the full source

Example usage:

{% registry items="assert" /%}

This renders the CLI command and source code from public/r/assert.json. Users can install via CLI or copy the code directly.

Avoid Code Duplication

When using a registry tag, do not duplicate the code in the recipe. The registry tag handles displaying the source code automatically.

Bad:

{% registry items="workflow-stream" /%}

Install via the registry above, or create manually:

\`\`\`typescript
// src/workflows/steps/stream.ts
// ... same code as registry item ...
\`\`\`

Good:

{% registry items="workflow-stream" /%}

Import and use the stream utilities in your workflow:

\`\`\`typescript
import { startStream, finishStream } from "@/workflows/steps/stream";
\`\`\`

The registry tag already provides the installation command and source code. Only add usage examples or explanations that aren't part of the installable code itself.

---

References

• fullstackrecipes.com - Browse all recipes and cookbooks
• Index - Every recipe and cookbook with its slug (append .md to any page URL for its Markdown)