Blog Post

Blog Post

End-to-end workflow for creating and updating blog posts. Orchestrates multi-role collaboration: Agent(product-manager) (research, brief, quality gate), Agent(content-writer) (authoring), Agent(seo-engineer) (optimization). Includes a review loop until the post meets quality standards.

1. Define Scope

Ask the user (or extract from context):

• Action: Create new post / update existing / create series
• Topic: Subject, angle, or user-provided idea
• Target audience: Who reads this? (developers, decision-makers, general public)
• Goal: Educate, announce, promote, thought leadership, SEO traffic
• Constraints: Deadline, word count, related posts, brand guidelines

If updating an existing post — read it first, note what needs to change.

2. Research and Content Brief

Apply Agent(product-manager).

2a. Topic Research

Conduct research before writing:

1. Web search — find 3-5 top-ranking articles on the topic. Note their angle, depth, and gaps
2. Competitive analysis — what do competitors cover? What's missing in the market?
3. Data and statistics — find recent, citable data points (studies, surveys, benchmarks)
4. Keyword research — identify primary keyword, 2-3 secondary keywords, search intent (informational / commercial / transactional)
5. Existing content audit — scan the project's blog directory for related posts. Identify cross-link opportunities

2b. Content Brief

Produce a brief using the Blog Content Brief Template from content-creation skill (content-tools-guide.md → Content Research Workflows section). The brief must include at minimum:

• Working title and angle (what makes this post unique)
• Target audience and search intent (primary + secondary keywords)
• Outline (H2 sections with what each covers)
• Key data points (stats with sources from research)
• Cross-link opportunities (existing posts to link to/from)
• Visual needs (cover image, diagrams, screenshots)
• Word count target

Present the brief to the user. Wait for user approval before proceeding. Adjust outline based on feedback.

3. Write Draft

Apply Agent(content-writer). Use content-creation skill — Blog Post pattern from page-content-patterns.md.

3a. Create the Post File

1. Read project's CLAUDE.md — get blog file conventions (directory, frontmatter format, naming)
2. Create the file with correct frontmatter as defined in the project's conventions
3. If no project conventions exist — use kebab-case.md naming, ask the user about frontmatter format

3b. Write Content

Follow the approved outline. For each section:

• Hook introduction — surprising stat, question, or pain point in the first paragraph
• Structured body — short paragraphs (2-3 sentences), break up with lists, tables, code blocks, blockquotes
• Internal links — minimum 3 links to existing blog posts or pages (from brief's cross-link list)
• External links — 1-2 authoritative sources (cite data points from research)
• Key takeaways — bullet list summarizing the post
• CTA — natural, value-first call to action related to the topic

3c. Visual Direction

For each visual need identified in the brief:

• Specify alt text (descriptive, includes keyword where natural)
• Note image placement relative to content
• If cover image needed — describe desired style, mood, composition

4. Humanize Content

Apply @humanizer skill. This step is mandatory for all blog content.

1. Scan the draft for AI writing patterns (see @humanizer pattern catalog)
2. Rewrite problematic sections — remove AI-isms, add natural voice
3. Anti-AI audit — ask "What makes this obviously AI generated?", list remaining tells, revise
4. Verify the humanized text preserves accuracy, maintains the approved outline, and sounds natural when read aloud

Do NOT skip this step. The humanize-content rule enforces this for all public-facing text.

5. SEO Optimization

Apply Agent(seo-engineer).

Run an SEO pass on the draft:

4a. On-Page SEO

4b. Internal Link Audit

• Minimum 3 internal links with descriptive anchor text
• Check all internal links are valid (no broken references)
• Anchor text is descriptive (not "click here" or "read more")
• Links are contextually relevant (not forced)

4c. Structured Data

• Add BlogPosting JSON-LD schema (or verify the framework handles it automatically)
• Verify: headline, author, datePublished, description, image

4d. Discovery Assets

• New post URL will be included in sitemap (verify sitemap config)
• robots.txt does not block the blog path
• Update llms.txt if the project maintains one — add the new post entry
• Verify canonical URL is correct

6. Quality Review

Apply Agent(product-manager).

Review the complete post against the original brief:

6a. Review Checklist

6b. Decision Gate

Present review findings to the user. If issues found — list them explicitly with the routing decision. Repeat the loop until the review passes.

7. Publish

7a. Set Publish Status

Based on user intent:

7b. Final File Checks

• Frontmatter is complete (all required fields populated)
• File is in the correct directory
• File name follows project conventions
• No TODO or placeholder text remains in the content
• All images referenced exist or have clear generation instructions

7c. Discovery Assets Update

• llms.txt updated (if maintained)
• Sitemap will pick up new file automatically (verify config)
• No noindex on the new page

8. Summary

## Blog Post Summary

- **Title**: [post title]
- **File**: [file path]
- **Status**: [published / draft / scheduled for DATE]
- **Topic**: [one-sentence summary]
- **Target keyword**: [primary keyword]
- **Word count**: [count]
- **Roles applied**: Agent(product-manager) → Agent(content-writer) → @humanizer → Agent(seo-engineer) → Agent(product-manager)
- **Review rounds**: [number of iterations]
- **Cross-links added**: [count — list of linked posts]
- **Discovery assets**: [llms.txt updated: yes/no, sitemap: auto/manual]
- **Follow-ups**: [if any — e.g., create cover image, schedule social media]

Content Series Pattern

When creating a multi-part series:

1. Plan all parts upfront — titles, topics, publish order in the content brief (Step 2)
2. Cross-link between parts — each post links to previous and next in series
3. Teaser for upcoming parts — end each post with a preview: "In Part 2, we'll cover [topic]"
4. Draft all parts before publishing the first — ensures consistency and cross-links work
5. Stagger publishing — space parts 3-7 days apart for engagement
6. On publish day — update previous part's teaser to a real link, remove any "(coming soon)" notes

Integration

• Roles: Agent(product-manager) (research, brief, review), Agent(content-writer) (authoring), Agent(seo-engineer) (optimization)
• Skills: content-creation skill (Blog Post pattern, AI generation tools, content brief template), @humanizer (AI writing pattern removal — step 4)
• Rules: humanize-content (auto-enforces humanizer pass on all public-facing text)
• Follow-up: /seo-review (deep SEO audit if needed), /pre-commit, /create-pr
• Related: /docs (technical documentation), /ui-ux-design (visual design for blog assets)