goose-blog-post

What this skill does

# Goose Blog Post

Write blog posts for the [block/goose](https://github.com/block/goose) open source project blog powered by Docusaurus.

## Prerequisites

- The goose repo must be cloned locally
- Locate the blog directory at `<goose-repo>/documentation/blog/`
- Confirm the `authors.yml` and blog directory exist before proceeding

If the repo is not cloned, clone it:

```bash
gh repo clone block/goose
```

## Workflow

### Step 1: Determine the Writing Mode

Ask the user how they want to work. There are three modes:

1. **"I have a draft"** — The author has written (or will write) their own content. The agent scaffolds the directory, frontmatter, and image setup, then places the author's content into the correct format and reviews it against blog conventions.

2. **"I have notes/an outline"** — The author has rough ideas, bullet points, or an outline. The agent expands these into a full draft while preserving the author's voice and key points. Present the draft for the author's review before finalizing.

3. **"Write it for me"** — The author provides a topic and key points. The agent writes the full post. Present the draft for the author's review before finalizing.

**Important:** For modes 1 and 2, the author's voice and intent take priority. Do not rewrite their content unnecessarily. Focus on structure, conventions, and polish — not on replacing their words.

### Step 2: Gather the Blog Post Details

Ask the user for the following (do not assume any of these):

1. **Topic**: What is the blog post about?
2. **Author**: Who is the author? (needs to match a key in `authors.yml`)
3. **Target audience**: Who is this for? (developers, beginners, community, etc.)

For modes 2 and 3, also ask:
4. **Key points**: What are the main things the post should cover?
5. **Tone**: Technical deep-dive, casual walkthrough, announcement, etc.?

For mode 1, ask:
4. **Where is the draft?** A file path, or ask them to paste it in.

### Step 3: Verify Author Exists

Check `<goose-repo>/documentation/blog/authors.yml` for the author key.

If the author does **not** exist, create a new entry. The format is:

```yaml
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
```

Ask the user for any missing details (name, title, GitHub username, social handles). The `image_url` can be derived from their GitHub profile: `https://avatars.githubusercontent.com/u/<id>?v=4`. Look up their GitHub user ID if needed:

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

### Step 4: Create the Blog Post Directory

Blog posts use the naming convention:

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

Rules:
- Use **today's date** (run `date +%Y-%m-%d` to get it)
- The slug should be lowercase, hyphen-separated, concise, and descriptive
- The directory lives inside `<goose-repo>/documentation/blog/`

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

### Step 5: Assemble the Blog Post

Create `index.md` inside the new directory. The file structure is:

#### 1. Frontmatter

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

Frontmatter rules:
- `title` — wrap in quotes, use title case
- `description` — wrap in quotes, keep to 1-2 sentences, make it compelling for social sharing
- `authors` — a YAML list of author keys from `authors.yml` (supports multiple authors)
- Do **not** include a `date` field — Docusaurus extracts the date from the directory name
- Do **not** include `tags` in frontmatter — the blog does not use Docusaurus tags

#### 2. Banner Image

Every post **must** include a banner image immediately after the frontmatter:

```markdown
![blog banner](banner.png)
```

Banner image requirements:
- **Dimensions:** 1200×600 pixels
- **Location:** Same directory as `index.md`
- **Filename:** `banner.png` (or `.jpg`, `.webp`)
- **This same image is also used for social sharing** (Open Graph / Twitter cards) — there is no separate social image

If the user does not have an image ready, add the image reference as a placeholder and remind them to add the file before publishing. You can also offer to generate one if image generation tools are available.

#### 3. Introduction + Truncate Marker

The intro paragraph(s) appear before the truncate marker. This controls the preview on the blog index page:

```markdown
![blog banner](banner.png)

Your compelling introduction paragraph that hooks the reader.

<!--truncate-->
```

The intro should:
- Hook the reader — why should they care?
- Be 1-3 paragraphs max
- Give enough context to decide whether to click through

#### 4. Content Body

**For mode 1 (author's draft):** Place the author's content here. Adjust only what's needed to match the formatting conventions below. Flag any issues for the author rather than silently rewriting.

**For modes 2 and 3:** Write the content following the guidelines below, then present the full draft to the author for review.

**Formatting Conventions:**
- Use `##` for major sections and `###` for subsections
- Do **not** use `#` (h1) in the body — the title from frontmatter is the h1
- Include code blocks with language identifiers (` ```python `, ` ```bash `, etc.)
- Use bullet points and numbered lists to break up dense information
- Short paragraphs (2-4 sentences) for readability
- End with a clear takeaway, call-to-action, or next steps

**Voice & Style:**
- Write in first person when sharing personal experience, third person for announcements
- Be conversational but technically accurate
- The goose blog audience is developers — respect their intelligence
- Avoid marketing fluff; be genuine and specific
- Use concrete examples and code snippets over abstract explanations

**goose-Specific Conventions:**
- Refer to the project as "goose" (lowercase) when referencing the tool
- When linking to goose docs: `https://block.github.io/goose/`
- When linking to the repo: `https://github.com/block/goose`
- When linking to extensions: `https://block.github.io/goose/extensions`

#### 5. Social Metadata (`<head>` Section) — Required

Every blog post **must** end with a `<head>` section containing Open Graph and Twitter card meta tags. This is placed at the very end of the `index.md` file, after all content:

```html
<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>
```

**Important:** The `og:image` and `twitter:image` URLs require a Docusaurus-generated filename that includes a content hash. You **cannot** guess this filename — it must be obtained from the local preview. See Step 6 for how to get it.

Field reference:
- `og:title` / `twitter:title` — same as the frontmatter `title`
- `og:description` / `twitter:description` — same as the frontmatter `description`
- `og:url` — the production URL: `https://block.github.io/goose/blog/YYYY/MM/DD/slug-title`
- `og:image` / `twitter:image` — the static image URL obtained from local preview (see Step 6)
- `twitter:card` — always `summary_large_image`
- `twitter:domain` — always `block.github.io`

When first creating the post, use `https://block.github.io/goose/assets/im