fern-docs

Fern のドキュメント作成

Fern サイトのドキュメントを作成、編集します。SKILL.md は索引です。以下の原則に従い、執筆前にタスクに合った references/ ファイルを読んでください。該当するリファレンスがある場合、このページだけを参考にして作業しないでください。

対象範囲：このスキルが適用されるのは Fern のドキュメントコンテンツのみです — MDX ページ、ナビゲーション、docs.yml と関連する設定、スニペット、変更履歴のエントリー、カスタムコンポーネント、ランディングページが対象です。同じリポジトリにある CLAUDE.md、AGENTS.md、STYLE-GUIDE.md、コントリビューターガイドなど、リポジトリのガバナンスやツール関連のファイルには適用されません。以下の「正規の置き場所を一つにする」「新規作成より編集を優先する」「統合する」という原則を、それらのファイルに適用しないでください。ユーザーから明示的に編集を依頼されない限り、変更しないでください。

Fern のリソース

Fern の設定は変化します。推測せず、調べてください。

• ドキュメント： https://buildwithfern.com/learn/docs/getting-started/overview.md （取得するドキュメント URL の末尾に .md を付けると、Markdown を取得できます）

• ページ索引： https://buildwithfern.com/learn/llms.txt

• MCP サーバー — エージェントを Fern の最新ドキュメントに接続し、不確かな構文や動作について問い合わせることができます。このエンドポイントは任意の MCP クライアントで動作します。Claude Code の場合：

  claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server
  

タスク別の参照先

タスク	参照先
変更履歴のエントリーの作成または編集	references/changelog.md
製品切り替え機能の設定、製品の追加、またはナビゲーションの製品別への再構成	references/products.md
ページの移動、名前変更、削除、または公開 URL を変更する編集	references/redirects.md
ロールによるページやコンテンツの制限（RBAC）、またはドキュメントと認証方式（パスワード、SSO、JWT、OAuth）の連携	references/authentication.md
複数のページにわたる同じコンテンツの編集、または汎用的な定型コンテンツ（例：「サポートへのお問い合わせ」）の追加	references/snippets.md
ページの別言語への翻訳、言語の追加、または既存の翻訳の更新（多言語対応の Fern リポジトリ）	references/translations.md

基本原則

• リポジトリ独自の規則に従ってください。 ドキュメントリポジトリに確立されたパターン、文体、構成がある場合 — CLAUDE.md やスタイルガイドがある場合、または周囲のページで一貫した慣例が見られる場合 — ここでのガイダンスよりもそちらを優先してください。このスキルは既定の方針であり、上書きするものではありません。
• 読者が目的を達成するために必要な内容だけを書いてください。 すべての文に役割が必要です。
• 新規作成より編集を優先してください。 リポジトリ内でトピックをすでに扱っているページを探し、重複ページを追加するのではなく、そのページを更新してください。
• 変更は最小限かつ正確にしてください。 段落の修正で済む場合に、ページ全体を書き直さないでください。
• 問題がありそうな場合は、そのまま従わず指摘してください。 黙って従うのではなく、理由を説明してください。
• 不明な点があれば質問してください。 憶測で不足を補わないでください。
• 決して捏造しないでください。 設定キーや動作がわからない場合は、（MCP サーバーまたはドキュメントで）調べるか、不明であると伝えてください。フロントマターや YAML のフィールドを作り出さないでください。
• 相互参照を追加してください。 別の場所で説明されている概念に触れる場合は、読者が見つけられるようリンクしてください。
• URL を変更する場合は、元の URL を維持できるようにしてください。 ページの移動、名前変更、削除、またはスラッグ、セクション、製品の変更を行うと、公開 URL が変わる場合があります。その場合は、元のパスからのリダイレクトを設定し（references/redirects.md を参照）、外部リンクと検索順位を維持してください。

リンク

内部リンクは、ファイルシステム上のパスや相対パスではなく、このリポジトリ独自の docs.yml とページのフロントマターから導き出される URL パスです。編集のほとんどでリンクを扱うため、毎回正しく設定してください。

ページ URL は <base-path>/<product-slug>/<rest> です。

• ベースパス — ドキュメント URL のプレフィックスです（例：/learn、/docs。空の場合もあります）。
• 製品スラッグ — fern/docs.yml にある製品の slug です。slug: がない製品（デフォルトの単一 Home 製品など）では省略します。
• <rest> — 以下の手順 1 または 2 で確認します。

<rest> の確認方法：

1. 対象ページを開き、フロントマターに slug: があるか確認します。 フロントマターのスラッグは製品内で絶対的です。単独で <rest> となり、セクションやフォルダーの階層全体を置き換えます。セクションのスラッグは含まれません。ナビゲーションをたどらないでください。
2. それ以外の場合は、製品内の docs.yml をたどり、セクションからフォルダーを経てページまで確認します。 各階層からスラッグが 1 つずつ追加されます。
   • 明示的に slug: が設定されていれば、その値を使用します。
   • 設定されていない場合は、表示名から自動生成されます。小文字に変換し、スペースをハイフンに置き換え、特殊文字を削除します（そのため、v3 (Latest) は v-3-latest になります）。自動生成の結果は常に明らかとは限らないため、推測せずに確認してください。
   • フォルダーベースのナビゲーションでは、ページのスラッグは表示名ではなくファイル名から決まります（quick-start.mdx は quick-start）。
   • skip-slug: true が設定されている階層は省略します — セグメントは追加されません。

例 — ベースパスが /learn の製品 docs にあり、セクション「AI features」配下にあるページ ./pages/ai/overview.mdx：

• フロントマターが slug: ai-ai の場合 → /learn/docs/ai-ai（ai-features セクションのスラッグは省略）
• フロントマターにスラッグがない場合 → /learn/docs/ai-features/overview（セクションの自動生成スラッグ ai-features ＋ ページの自動生成スラッグ overview）

セクションのスラッグはフォルダー名と異なることがよくあります。そのため、ディレクトリ構造から URL を推測してはいけません。docs.yml とページのフロントマターからパスを特定できない場合は、推測せずにその旨を伝えてください。

アンカーは #heading を追加したもので、実際の ##／### Markdown 見出しに対してのみ有効です。<Step title>、<Tab title>、<Accordion title>、<Card title> などの JSX タイトルプロパティには対応していません。

内部リンクではないもの（そのままにします）：外部の https:// URL、画像パス（./images/...）、スニペットのインクルード（<Markdown src="/snippets/..." />）、同一ページ内のアンカー（#section）。

相互参照

新機能（新しいページや既存ページの新しい動作など）をドキュメント化したら、関連ページからもその機能へのリンクを追加するのが一般的です。そうしないと、読者が実際に読み始める場所から新しい内容を見つけにくくなります。これは新しいページだけでなく、小さな編集にも当てはまります。

• 説明の本拠地は1か所にする。 詳しい説明は1つのページにまとめ、トピックに触れている他のページでは説明を繰り返さず、そのページにリンクします。他のページに1～2文を超えてコピーする場合は、説明の本拠地に記載しましょう。

• リンク先を見つける。 ドキュメント内で機能名と関連キーワードを1～2個検索し、該当箇所をそれぞれ読んで、リンクを追加すべきか判断します。

  grep -rln "<feature>\|<keyword>" fern --include="*.mdx"
  

  よくあるリンク先：その機能の影響を受ける動作のページ、関連機能のページ、概要ページやランディングページ。

• 必要最小限の形式を使う： 既存の文中にインラインリンクを追加し、補足が必要なら <Note> を使い、さらに必要な場合は新しい ## セクションを追加し、最後の手段として新しいページを作成します。インラインリンクと Note はメンテナンス対象を増やしませんが、新しいページやセクションは増やします。

• インラインリンクは自然な表現にし、「[ページ]を参照してください」と書かないでください。 文中にすでにある名詞句にリンクを設定し、後付けの案内文は避けます。リンクを置くことだけが目的の <Tip> で、単独のリンクを囲まないでください。

  • 良い例：「各リクエストはレート制限の対象となり、1時間ごとにリセットされます。」
  • 悪い例：「リクエストにはレート制限があります。詳しくはレート制限のリファレンスを参照してください。」
  • 悪い例：単独の <Tip> に「詳細はレート制限を参照してください。」だけを記載する。

• 仕組みではなく機能を基準に説明する。 設定キーを共有していることや、同じディレクトリにあることではなく、それぞれの機能が何をするかを対比します（「X は A を決定し、Y は B を決定する」）。同じ YAML キーを使っていること以外に2つの機能を結び付ける要素がなければ、相互参照を追加する必要はありません。