authoring-recipes

レシピの作成

fullstackrecipes のコンテンツを作成するためのガイドラインです。このスキルは、スタックを利用する開発者向けではなく（その場合は use-fullstackrecipes を参照してください）、fullstackrecipes プロジェクト自体を拡張するメンテナー向けです。

fullstackrecipes は、意見のあるスタックとセットアップ手順、ベストプラクティス、すぐにクローンできる出発点を提供することで、開発者やエージェントによるより優れたフルスタックアプリの構築を支援するサイトです。提供するリソースは、セットアップレシピ、スキル、クックブック、テンプレートの 4 種類です。

2 つのスキルディレクトリ — 混同しないでください

このリポジトリには、互いに別の skills/ ツリーが 2 つあります。対象とする読者は正反対です。

• ./skills/ — このリポジトリが利用者向けに公開・提供するスキルです。日常的に使う、エージェント向けのワークフローガイド（drizzle-queries、authentication-best-practices、workflow-best-practices など）であり、ウェブサイトが読み込み（.md エンドポイントを通じて Markdown として提供し）、利用者が bunx skills add でインストールします。このスキルで「スキル」と言う場合は、これらを指します。
• ./.agents/skills/ — fullstackrecipes プロジェクトを構築するために、このワークスペース内部で使うスキルです。この authoring-recipes スキルもここにあります。これらは利用者には公開されず、リソースカタログにも含まれません。

公開するスキルを作成または編集する場合は、./skills/<slug>/SKILL.md で編集してください。利用者向けのスキルコンテンツを .agents/skills/ に置かないでください。

レシピのティア

カタログの各項目は、3 つのティアのいずれかに属します。加えて、クックブックにはオプションでテンプレートを関連付けられます。ティアによって、インストールするものと、説明文で前提としてよい内容が決まります。カタログ（スラッグ、タイトル、説明、タグ、requires、テンプレートへのリンク）の唯一の信頼できる情報源は src/lib/recipes/data.tsx です。

ティア 1 — セットアップレシピ（type: "setup"）

単一の関心事に関するファイル、依存関係、設定をインストールする一度限りのセットアップです（例：neon-drizzle-setup、better-auth-setup）。

• インストール範囲は分割可能なままにします。 セットアップレシピは独自の部分だけをインストールし、依存関係グラフの合成可能性と、各レシピを単独で採用できる状態を保ちます。
• 前提条件は requires に宣言し、最初に明記します。 前提条件を参照し、改めて説明し直さないでください。不足している前提条件が 1 つか 2 つの場合は、最低限の代替手順を示してもかまいません。単独での利用しやすさを担うのは、スキルのティアではなくこちらです。

Tier 2 — スキル（type: "skill"）

設定済みのツール向けの日常的なエージェント向けワークフローガイドです（例：drizzle-queries、authentication-best-practices）。このリポジトリが公開するスキルは ./skills/ の下にあります（.agents/skills/ ではありません。上記を参照してください）。

• スキルはレシピのドキュメントではなく、独自に作成するものです。 信頼できる唯一の情報源は、手作業で作成する ./skills/<slug>/SKILL.md（YAML フロントマター＋本文）です。ウェブサイトはこのファイルから本文を直接読み取り（.md エンドポイント経由でも配信するため）、変更は反映され次第公開されます。ビルド手順はありません。docs/recipes/<slug>.md は存在しません。
• 本文のセクションは ### から始めてください。 ローダー（src/lib/recipes/loader.ts）は、YAML フロントマターと最初の ### 見出しまでのすべてを削除し、data.tsx のメタデータから # Title、説明、## Prerequisites のリストを再生成します。そのため、スタンドアロンで読むための作成ファイルは # Title ＋説明＋前提条件から始まりますが、公開される本文は最初の ### セクションから始まります。本文の最上位セクションには ### を使ってください。
• ツール名ではなく、教える内容に基づいてスキルに名前を付けてください。 説明的なスラッグとタイトル（drizzle-queries、testing-best-practices、ralph-loop-workflow）を使い、using-* の接頭辞は使わないでください。フロントマターの name: とスラッグ（フォルダー名）は一致させ、# Title の H1 は src/lib/recipes/data.tsx の title と一致させてください。スラッグの名前を変更する場合は、古いスラッグを data.tsx の recipeRedirects に追加してください。
• type は Skills タグから導出されます。 data.tsx の tags に "Skills" が含まれている場合、その項目はスキル（type: "skill"）になります。それ以外はすべてセットアップレシピです。設定すべき独立した type フィールドはありません。
• 人間向けのチュートリアルではなく、エージェント向けに書いてください。 パターンとコードから始め、エージェントがすでに理解している手取り足取りの説明、「ステップ1／2／3」の手順、動機を説明する段落は省いてください。命令形で簡潔にし、例を先に示してください。
• 標準スタックを前提とし、曖昧な書き方は避けてください。 セットアップレシピが構築する正確な環境に合わせて書いてください。実際のパス（@/lib/db/client、@/lib/auth/server、@/lib/logging/logger、@/components/ui/* など）からインポートしてください。「セットアップ方法が異なる場合は」といった但し書きは追加しないでください。そうした防御的な表現はスキルの価値を損ないます。
• 標準スタックは、クックブックの名前ではなく機能によって定義されます。Drizzle 経由の Postgres データベース、Better Auth セッション、構造化ロギング、shadcn/ui コンポーネント、テストハーネスが含まれます。スキルでは、requires チェーンが提供する機能を前提にできます。
• スタックのセットアップ方法には決して言及しないでください。 スキルで教えるのは、実行時に 何をするか だけです。セットアップレシピの名前を出すこと（「X レシピでセットアップ」「Y で設定」「Z のセットアップから」など）は、スキルの実行中には何の役にも立ちません。requires メタデータがセットアップの履歴をすでに追跡し、前提条件セクションとして表示するため、本文で触れる必要はありません。
• スキルは skills CLI 経由でインストールします。コンテンツとして貼り付けるものではありません。エージェントスキルとして保持され、継続的な作業で利用できます。

Tier 3 — クックブック（isCookbook: true）

標準的な統合リファレンスです。順序付けられた2段階のセットアップ成果物です（以下を参照）。

クックブックの作成

クックブックはセットアップ成果物であり、ドキュメントをまとめたものではありません。クックブックを実行すると、プロジェクトには設定済みのスタックとインストール済みのスキルの両方が揃います。

2段階モデル

1. セットアップチェーン — セットアップレシピを順番に実行し、ファイル、依存関係、設定をインストールします。
2. スキルのインストール — bunx skills add 経由でスキルをインストールし、その後もエージェントが日常的なパターンを保持できるようにします。

順序

各スキルは、すべてのスキルを末尾にまとめるのではなく、対応するセットアップレシピの直後に記載してください。スキルは、使い方を教える対象の直後に続けます。

レンダリング（自動処理）

クックブックを組み立てると、ローダーはtypeに応じて処理を分岐します。

• セットアップレシピは、内容全体をそのまま挿入します。
• スキルレシピは、簡潔なセクションとして表示します。構成は## <title>＋動機（説明文）＋bunx skills add ... -s <slug>コマンドです。内容はそのまま挿入されません。クックブックはスキルとしてインストールします。

そのため、スキルの内容をクックブックに重複して含める必要はありません。適切な位置にあるrecipesへスキルのスラッグを追加するだけで、インストールセクションはメタデータから生成されます。

テンプレート

テンプレートは、クックブックの組み立て済みの出力一式を含む、クローンしてすぐ使える出発点です。利用者はすべてのセットアップ手順を手作業で実行せずに、動作するコードから始められます。テンプレートは独立したカタログ階層ではなく、data.tsxの2つのフィールドを使ってクックブックに紐付けます。

• template — TEMPLATE_BASEから構成されるGitクローンパスです（例：`${TEMPLATE_BASE}/base-app#main`）。
• githubUrl — テンプレートのソースを閲覧するためのGitHub URLです。GITHUB_TEMPLATE_BASEから構成されます。

テンプレートのソースはリポジトリルートのtemplates/<name>/にあり、実際に実行できるプロジェクトです。クローン可能なスターターを表示するクックブックには、"Starter template"タグも付いています（getStarterTemplatesを参照）。現在はbase-app、auth、stripe-sync、ai-workflowが該当します。

作成ルール：

• **テンプレートをクックブックと同期させてください。**テンプレートには、クックブックのレシピを順に実行したときの出力を正確に反映する必要があります。セットアップレシピを変更したら、対応するテンプレートディレクトリも更新してください。そうしないと、クローンしてすぐ使える手順が、ドキュメントの内容と食い違ってしまいます。
• **テンプレートはドキュメントではなく、組み立て済みのスタックです。**チュートリアルの説明文やレシピのMarkdownをテンプレートに追加しないでください。テンプレートは、独自のagents.mdや.agents/skills/などを含む、動作するアプリとして配布されます。説明文はレシピやクックブックに記載します。
• **テンプレートはクックブックから参照し、重複させないでください。**クックブックにのみtemplate／githubUrlを設定します。ウェブサイトはそのメタデータからクローンコマンドを表示します。

インストール可能なユーティリティ

インストール可能なユーティリティを含むレシピを作成するときは、{% registry %}タグを使って、CLIによるインストールとソースコードの閲覧の両方を提供してください。

Registryタグ

Registryタグは次の内容を表示します。

1. shadcn CLIによるインストール — ユーティリティをインストールするためのコピー可能なコマンド
2. ソースコードビューアー — ソース全体を表示する折りたたみ可能なコードブロック

使用例：

{% registry items="assert" /%}

このタグは、public/r/assert.jsonのCLIコマンドとソースコードを表示します。ユーザーはCLIからインストールするか、コードを直接コピーできます。

コードの重複を避ける

Registryタグを使用する場合、レシピ内でコードを重複させないでください。ソースコードの表示はRegistryタグが自動的に処理します。

悪い例：

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

Install via the registry above, or create manually:

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

良い例：

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

Import and use the stream utilities in your workflow:

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

Registryタグがすでにインストールコマンドとソースコードを提供します。追加するのは、インストール可能なコード自体に含まれていない使用例や説明だけにしてください。

---

参考資料

• fullstackrecipes.com - すべてのレシピとクックブックを閲覧できます
• インデックス - スラッグ付きのすべてのレシピとクックブック（Markdownを表示するには、任意のページURLの末尾に.mdを追加してください）