Blog Post

Blog Post Skill

Creates technical blog posts as Markdown files in docs/ – based on a structured interview and a proven template from successful technical articles.

Philosophy: A good technical blog post tells a story. It starts with a problem the reader knows and ends with an insight that goes beyond the code.

What This Skill Does

1. Asks for language and audience – German/English, Developer/BA/PM
2. Conducts structured interview – Topic, key message, outline, code examples
3. Generates blog post – From template with audience-appropriate language and depth
4. Creates hero image (optional) – Via Hugging Face API (FLUX) as title image

How to Use

Write a blog post about Quarkus and LangChain4j

Create an article about our DevContainer template

Write a blog post about Java FFM and native AI inference

Instructions

Before every execution:

1. Check .claude/lessons-learned.md
2. Load template templates/blog-post.md.template

Step 1 – Ask for language and audience

Language and audience determine the entire tone, depth, and amount of code examples in the post. Without this information, the post won't be audience-appropriate – therefore always ask first with AskUserQuestion.

Question 1 – Language

What language should the blog post be written in?

Options:

• German (Recommended) – Technical terms remain English, prose in German
• English – Entire text in English

Question 2 – Audience

Who is the primary audience?

Options:

• Developer – Technically deep, many code examples, architecture decisions explained, CLI commands, fully compilable snippets
• Business Analysts – Business focus, code only illustrative, benefits and processes in the foreground, diagrams instead of implementation details
• Project Managers – Strategic perspective, decision aids, risks/opportunities, effort estimates, little code

Step 2 – Topic interview

The interview provides the content foundation for the entire post. Ask questions sequentially – one group at a time, so the user is not overwhelmed.

Group 1 – Core

Group 2 – Content

Group 3 – Context

Step 3 – Create and confirm outline

Before writing, present a compact outline:

## Outline: [Working Title]

1. Hook – [Opening in 1 sentence]
2. Problem statement – [What is the problem?]
3. [Section 1] – [Key point]
4. [Section 2] – [Key point]
5. [Section 3] – [Key point]
6. Conclusion – [Central insight]

Only continue writing after confirmation.

Step 4 – Generate blog post

Load and fill template templates/blog-post.md.template.

Style rules by audience

Developer:

• Problem-first opening with personal experience or concrete scenario
• Code examples complete and compilable (with imports, package declaration)
• "Why" sections for architecture decisions ("Why FFM requires a shared library")
• Verification section with curl commands or test output
• Conclusion highlights strategic insight, not just a summary
• Inline code for technical terms (ProcessBuilder, @Blocking)
• Bold for key concepts
• Tables for comparisons and configurations
• ~15–20 code blocks for tutorial posts

Business Analysts:

• Opening with business problem or business scenario
• Code only as illustration (simplified, pseudocode allowed)
• Focus on process flows, benefits, business impact
• Diagrams and tables instead of implementation details
• Conclusion with recommendations and next steps
• ~3–5 code blocks maximum

Project Managers:

• Opening with strategic question or market observation
• No code, except for illustration ("this is what it looks like in 5 lines")
• Focus on decisions, risks, opportunities, team impact
• Comparison tables for technology alternatives
• Conclusion with concrete recommendation and decision matrix
• ~0–2 code blocks

General style rules (all audiences)

Based on the style of the-main-thread.com:

• Opening (Hook): First paragraph tells a mini-story or makes a surprising claim. Never start with "In this article…".
• Tone: Professional but conversational. Direct without being preachy. Short sentences for rhythm, longer ones for explanations.
• Paragraphs: Short (2–4 sentences). Single sentences as their own paragraph are allowed for emphasis.
• Headings: Clear and descriptive. H2 for main sections, H3 for subsections.
• Lists: Unordered for enumerations, numbered for sequences. Never more than 7 entries.
• Metaphors: Explain technical concepts through everyday comparisons ("like an intern you're onboarding").
• Conclusion: Not a mere summary. Instead, a strategic insight that points beyond the article. Antithesis or repetition for effect is welcome.
• Horizontal Rules (---): Between main sections as visual separators.

Step 5 – Hero image (optional)

After the blog post, ask:

Should a hero image be generated for the post?

If yes, via Hugging Face API (as in infografik):

Prompt schema for blog hero images:

A modern, minimalist hero image for a technical blog post about [TOPIC].
Style: abstract, geometric shapes suggesting [CORE_CONCEPT].
Color scheme: dark background (#1a1a2e), accent colors [PRIMARY_COLOR] and [SECONDARY_COLOR].
No text, no letters, no words. Clean, editorial feel.
Format: landscape, 1200x630 pixels (Open Graph).

curl -s \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "YOUR_PROMPT_HERE"}' \
  "https://router.huggingface.co/hf-inference/models/black-forest-labs/FLUX.1-schnell" \
  --output "docs/hero_$(date +%Y%m%d_%H%M%S).png"

Quality checklist

Check before presenting:

• Language and audience were asked
• Outline was confirmed
• Hook in first paragraph (no "In this article…")
• Conclusion contains strategic insight, not just a summary
• Code examples are complete (for developer audience)
• Horizontal rules between main sections
• No emojis (unless requested)
• Co-author note at the end
• Word count matches desired length (±20%)

References

Style references

The style rules are based on the analysis of these posts from the-main-thread.com:

Conventions

• Filename: docs/blog-<topic-kebab-case>.md
• Prose language: German (default) or English – depending on interview
• Code language: Always English
• Technical terms: Remain English, even in German posts
• Co-Author: At the end of the post: *Co-Author: Claude (claude-sonnet-4-6, Anthropic) – generated via blog-post*
• Hero Image: docs/hero_<topic-or-timestamp>.png – never overwrite

Position in Workflow

[spec-feature]      optional – business requirements
        |
[java-scaffold]     project setup
        |
[review]            code review
        |
[doc]               project documentation
        |
[blog-post]         < blog post about the project / technology