---
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.
title: authoring-recipes
canonical_url: https://skilld.dev/gh/andrelandgraf/fullstackrecipes/authoring-recipes
last_updated: 2026-11-01T08:03:20.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install andrelandgraf/fullstackrecipes/authoring-recipes`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/authoring-recipes`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/andrelandgraf/fullstackrecipes/authoring-recipes) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/authoring-recipes`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/authoring-recipes --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/authoring-recipes --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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:

```markdoc
{% 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:

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

Install via the registry above, or create manually:

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

Good:

```markdoc
{% 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](https://fullstackrecipes.com) - Browse all recipes and cookbooks
- [Index](https://fullstackrecipes.com/llms.txt) - Every recipe and cookbook with its slug (append `.md` to any page URL for its Markdown)
