goose-blog-post

Goose ブログ記事

Docusaurus を利用したオープンソースプロジェクト block/goose のブログ記事を作成します。

前提条件

• goose リポジトリがローカルにクローンされていること
• ブログディレクトリが <goose-repo>/documentation/blog/ にあること
• 作業を進める前に、authors.yml とブログディレクトリが存在することを確認してください

リポジトリがクローンされていない場合は、クローンします。

gh repo clone block/goose

ワークフロー

ステップ 1：執筆モードを決める

どのように作業を進めたいか、ユーザーに尋ねます。モードは 3 つあります。

1. 「下書きがあります」 — 執筆者が自身のコンテンツを作成済み（または作成予定）です。エージェントはディレクトリ、フロントマター、画像の設定を準備し、執筆者のコンテンツを適切な形式に整えて、ブログの慣例に沿っているか確認します。

2. 「メモ／アウトラインがあります」 — 執筆者に大まかなアイデア、箇条書き、またはアウトラインがあります。エージェントは執筆者の語り口と重要なポイントを保ちながら、これらを記事の下書きにまとめます。仕上げる前に、執筆者が確認できるよう下書きを提示します。

3. 「代わりに書いてください」 — 執筆者がトピックと重要なポイントを提示します。エージェントは記事全体を執筆します。仕上げる前に、執筆者が確認できるよう下書きを提示します。

重要： モード 1 と 2 では、執筆者の語り口と意図を優先します。内容を不必要に書き換えないでください。執筆者の言葉を置き換えるのではなく、構成、慣例、推敲に重点を置きます。

ステップ 2：ブログ記事の詳細を確認する

以下の内容をユーザーに尋ねます（いずれも推測しないでください）。

1. トピック：ブログ記事のテーマは何ですか？
2. 執筆者：執筆者は誰ですか？（authors.yml のキーと一致する必要があります）
3. 対象読者：誰に向けた記事ですか？（開発者、初心者、コミュニティなど）

モード 2 と 3 では、次の点も尋ねます。 4. 重要なポイント：記事で取り上げるべき主な内容は何ですか？ 5. トーン：技術的な詳細解説、気軽な手順紹介、告知など、どのようなトーンですか？

モード 1 では、次の点を尋ねます。 4. 下書きの場所：ファイルパスを尋ねるか、下書きを貼り付けてもらいます。

ステップ 3：執筆者の存在を確認する

<goose-repo>/documentation/blog/authors.yml で執筆者のキーを確認します。

執筆者が存在しない場合は、新しいエントリを作成します。形式は次のとおりです。

authorkey:
  name: Full Name
  title: Job Title
  image_url: https://avatars.githubusercontent.com/u/<github-id>?v=4
  page: true
  socials:
    github: github-username
    x: x-username
    linkedin: linkedin-username

不足している情報（名前、肩書き、GitHub ユーザー名、ソーシャルメディアのアカウント名）をユーザーに尋ねます。image_url は GitHub プロフィールから取得できます：https://avatars.githubusercontent.com/u/<id>?v=4。必要に応じて、GitHub のユーザー ID を調べます。

gh api users/<username> --jq '.id'

ステップ 4：ブログ記事のディレクトリを作成する

ブログ記事の命名規則は次のとおりです。

YYYY-MM-DD-slug-title/
  index.md
  banner.png

ルール：

• 今日の日付を使用します（日付を取得するには date +%Y-%m-%d を実行します）
• スラッグは小文字にし、単語をハイフンで区切って、簡潔で内容が伝わるものにします
• ディレクトリは <goose-repo>/documentation/blog/ 内に作成します

mkdir -p documentation/blog/YYYY-MM-DD-slug-title

ステップ 5：ブログ記事を組み立てる

新しいディレクトリ内に index.md を作成します。ファイルの構成は次のとおりです。

1. フロントマター

---
title: "Your Blog Post Title"
description: "A concise summary of the post (1-2 sentences). Used in social previews and SEO."
authors:
  - authorkey
---

フロントマターのルール：

• title — 引用符で囲み、タイトルケースを使用します
• description — 引用符で囲み、1～2 文にまとめ、ソーシャルメディアで共有したくなる内容にします
• authors — authors.yml にある執筆者キーの YAML リスト（複数の執筆者に対応）
• date フィールドは含めないでください — Docusaurus はディレクトリ名から日付を取得します
• フロントマターに tags を含めないでください — このブログでは Docusaurus のタグを使用しません

2. バナー画像

すべての記事に、フロントマターの直後にバナー画像を含める必要があります。

![blog banner](banner.png)

バナー画像の要件：

• 寸法： 1200×600 ピクセル
• 場所： index.md と同じディレクトリ
• ファイル名： banner.png（または .jpg、.webp）
• この画像はソーシャルメディアでの共有にも使用されます（Open Graph／Twitter カード）— 個別のソーシャル画像はありません

ユーザーが画像を用意していない場合は、画像の参照をプレースホルダーとして追加し、公開前にファイルを追加するよう伝えます。画像生成ツールを利用できる場合は、画像の生成を提案することもできます。

3. はじめに＋切り捨てマーカー

はじめにの段落は、切り捨てマーカーより前に記述します。ブログのインデックスページに表示されるプレビューを制御します。

![blog banner](banner.png)

Your compelling introduction paragraph that hooks the reader.

はじめには、次の点を満たすようにします。

• 読者の関心を引く — なぜ読む価値があるのでしょうか？
• 最大1〜3段落にする
• 続きを読むかどうかを判断できるだけの背景情報を示す

4. 本文

モード1（著者の原稿）の場合： 著者のコンテンツをここに配置します。以下の書式規則に合わせるために必要な箇所のみ調整します。問題があれば、黙って書き換えずに著者に伝えてください。

モード2および3の場合： 以下のガイドラインに沿ってコンテンツを作成し、原稿全体を著者に提示してレビューしてもらいます。

書式規則：

• 大見出しには ##、小見出しには ### を使用します
• 本文では #（h1）を使用しないでください — frontmatter のタイトルが h1 です
• 言語識別子付きのコードブロックを含めます（```python、```bash など）
• 箇条書きと番号付きリストを使用して、情報量の多い内容を整理します
• 読みやすさを考慮し、段落は短く（2〜4文）します
• 明確な要点、行動喚起、または次のステップで締めくくります

文体とトーン：

• 個人的な体験を共有する場合は一人称で、告知の場合は三人称で書きます
• 親しみやすく、それでいて技術的に正確な文章にします
• goose のブログ読者は開発者です。読者の知性を尊重してください
• 宣伝めいた表現は避け、率直かつ具体的に書きます
• 抽象的な説明より、具体例やコードスニペットを優先します

goose 固有の規則：

• ツールを指す場合、プロジェクト名は「goose」（小文字）と表記します
• goose のドキュメントへのリンクには https://block.github.io/goose/ を使用します
• リポジトリへのリンクには https://github.com/block/goose を使用します
• 拡張機能へのリンクには https://block.github.io/goose/extensions を使用します

5. ソーシャルメタデータ（<head> セクション）— 必須

すべてのブログ記事は、Open Graph と Twitter カードのメタタグを含む <head> セクションで必ず終わる必要があります。これは、すべてのコンテンツの後、index.md ファイルの末尾に配置します。

<head>
  <meta property="og:title" content="YOUR TITLE HERE" />
  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://block.github.io/goose/blog/YYYY/MM/DD/slug-title" />
  <meta property="og:description" content="YOUR DESCRIPTION HERE" />
  <meta property="og:image" content="https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta property="twitter:domain" content="block.github.io" />
  <meta name="twitter:title" content="YOUR TITLE HERE" />
  <meta name="twitter:description" content="YOUR DESCRIPTION HERE" />
  <meta name="twitter:image" content="https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png" />
</head>

重要： og:image と twitter:image の URL には、コンテンツハッシュを含む Docusaurus 生成のファイル名が必要です。このファイル名を推測することはできません。ローカルプレビューで確認する必要があります。取得方法についてはステップ6を参照してください。

各フィールドの説明：

• og:title / twitter:title — frontmatter の title と同じ値
• og:description / twitter:description — frontmatter の description と同じ値
• og:url — 本番環境の URL：https://block.github.io/goose/blog/YYYY/MM/DD/slug-title
• og:image / twitter:image — ローカルプレビューで取得した静的画像の URL（ステップ6を参照）
• twitter:card — 常に summary_large_image
• twitter:domain — 常に block.github.io

記事を最初に作成するときは、og:image と twitter:image のプレースホルダーとして https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png を使用します。BANNER_FILENAME_WITH_HASH の部分は、ステップ6の後に実際のファイル名に置き換えます。

ステップ6：ローカルでプレビューし、画像 URL を取得する

著者はブログ記事をローカルでプレビューして、次のことを行う必要があります。

1. 記事が正しく表示されることを確認する
2. <head> のソーシャルメタデータに必要な静的画像の URL を取得する

ユーザーに、別のターミナルで次のコマンドを実行するよう伝えてください（ターミナルがブロックされるため、このコマンドを直接実行しないでください）。

cd <goose-repo>/documentation
npm start

これにより、ホットリロードに対応したローカル開発サーバーが http://localhost:3000 で起動します。

プレビューが表示されたら、ユーザーに次の手順を案内してください。

1. ブラウザーでブログ記事を開く
2. バナー画像を右クリックして、画像アドレスをコピーを選択する
3. コピーした URL は、次のようになります。 http://localhost:3000/goose/assets/images/banner-a1b2c3d4e5f6.png
4. ファイル名を取り出す（例：banner-a1b2c3d4e5f6.png）
5. 本番環境の URL を作成する。 https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png

<head> セクションの og:image と twitter:image を、この本番環境の URL に更新します。

ステップ 7：下書きを提示してレビューを依頼する

このステップは重要です。 投稿が完成したと判断する前に、次のことを行います。

• 完全な index.md の内容を著者に提示します
• 行った判断（タイトルの表現、セクション構成、導入部の構成）を明示します
• 変更したい点があるか尋ねます
• モード 1 の場合：行った書式変更とその理由を伝えます

著者が納得するまで、フィードバックに基づいて修正を繰り返します。

ステップ 8：最終レビューのチェックリスト

このチェックリストに沿って確認し、問題があれば修正します。

• ディレクトリ名が YYYY-MM-DD-slug-title/ の命名規則に従っている
• ディレクトリ内に index.md がある
• フロントマターに title、description、authors が含まれている
• authors.yml に著者キーがある
• フロントマターの後にバナー画像（1200×600）が指定されている
• バナー画像ファイルがディレクトリ内にある（または必要なものとして明記されている）
• `` マーカーが導入部の後に配置されている
• 本文に #（h1）見出しがなく、見出しは ## 以下のみである
• コードブロックに言語識別子が指定されている
• goose のリソースへのリンクに正しい URL が使われている
• ファイル末尾に <head> セクションがある
• og:image と twitter:image の URL にローカルプレビューの値が設定されている
• スペルと文法に問題がない
• 投稿全体が最初から最後まで読みやすい

効果的なコンテンツの種類

著者のアイデア出しや方向性の選択を支援する際は、次の形式が goose ブログで特に効果的です。

• チュートリアルとハウツー — 「goose で X を構築した方法」
• 詳細な解説 — アーキテクチャ、機能、設計上の判断
• コミュニティの紹介 — 貢献者の体験談やユースケース
• 比較 — goose と他のツールの比較、率直な評価
• リリースのお知らせ — 新機能とその重要性
• ヒントとワークフロー — 上級ユーザー向けガイドや生産性向上の工夫
• オピニオンリーダーシップ — AI エージェント、開発者ツール、オープンソースに関する意見

例

ブログ投稿の完成例：

---
title: "Building a Custom MCP Server for Your Team"
description: "A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools."
authors:
  - ebony
---

![blog banner](banner.png)

If your team has internal tools that aren't covered by existing extensions, building a custom MCP server is easier than you think. In this post, I'll walk through how I built one for our team's deployment pipeline.



## Why Build a Custom MCP Server?

goose connects to tools through the Model Context Protocol (MCP). While there are hundreds of community extensions available, sometimes your team has unique internal tools that need a custom integration.

## Getting Started

First, scaffold a new MCP server project:

```bash
npx create-mcp-server my-server
cd my-server
```

## Defining Your Tools

The core of any MCP server is its tool definitions...

## Wrapping Up

Building an MCP server took about an hour and saved our team countless context switches. If you want to learn more, check out the [MCP documentation](https://modelcontextprotocol.io/introduction) and the [goose extensions directory](https://block.github.io/goose/extensions).

<head>
  <meta property="og:title" content="Building a Custom MCP Server for Your Team" />
  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://block.github.io/goose/blog/2025/07/01/custom-mcp-server" />
  <meta property="og:description" content="A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools." />
  <meta property="og:image" content="https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta property="twitter:domain" content="block.github.io" />
  <meta name="twitter:title" content="Building a Custom MCP Server for Your Team" />
  <meta name="twitter:description" content="A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools." />
  <meta name="twitter:image" content="https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png" />
</head>