| name | blog-post |
| description | Transforms Java/Quarkus projects into engaging technical blog posts. Use this skill when a blog article, tutorial, or technical introduction should be created from a project. |
Blog-Post Skill
Purpose
Create developer-focused blog posts that present technical projects honestly, concisely, and with actionable takeaways. Covers project analysis, writing, bilingual output, and cover image prompt generation.
Post Types
Choose the type before writing:
| Type | Structure | Word count |
|---|
| Architecture / System Design | Problem → Architecture → Implementation → Trade-offs → Results | 2000–3500 |
| Tutorial / How-To | End result first → Prerequisites → Steps → Complete code → Next steps | 1500–3000 |
| Deep Dive / Explainer | What + why → Mental model → Mechanics → Example → Trade-offs | 2000–4000 |
| Benchmark / Comparison | What + why → Methodology → Results → Analysis → Recommendation | 1500–2500 |
Default for Quarkus/agentic projects: Architecture / System Design.
Required Sections
Every post must include all of these:
- TL;DR — 2–3 sentences at the very top. If it's a local LLM pipeline, include "code never leaves your machine."
- The Problem — Specific and relatable. Skip generic openers.
- Core content — Architecture, code snippets, key decisions.
- Trade-offs and Limitations — Non-negotiable. Honest downsides build trust. Skipping this reads as marketing.
- Next Steps — Concrete roadmap items, not vague promises.
- Further Reading — 3–5 links.
Code Example Rules
- Every code block must be runnable as shown — broken examples destroy credibility
- Language identifier in every fenced block:
```java, ```yaml, ```bash
- Pin versions explicitly:
// Quarkus 3.35.1, Java 25
- Show output after the code where useful
- Realistic names — never
foo, test, myMethod
- Include error handling where it matters
Agent / Pipeline Table Template
For agentic pipeline posts, always include a table of agents and scope keys:
| Agent | Role | Scope key |
|---|---|---|
| `Coder` | Writes initial code from the spec | `code` |
| `Reviewer` | Quality check — `APPROVED` or `FAILED: <reason>` | `review_status` |
| `Editor` | Rewrites code on failure | `code` |
| `SecurityReviewer` | OWASP-style security pass | `security_status` |
| `SecurityEditor` | Patches security issues | `code` |
Also describe loop structure explicitly:
**Review loop** (`Reviewer ↔ Editor`) — runs up to N iterations until `APPROVED`.
**Security loop** (`SecurityEditor ↔ SecurityReviewer`) — runs until `APPROVED`.
GDPR / DSGVO Paragraph Template
Include when the pipeline runs on a local LLM (Ollama, LM Studio, etc.):
English (BLOG.md):
Because the pipeline runs entirely on local hardware with Ollama, no code ever leaves your machine. For teams working with proprietary code, client data, or under GDPR constraints, that's not a nice-to-have — it's a requirement.
German (BLOG_DE.md):
Weil die Pipeline vollständig auf lokaler Hardware mit Ollama läuft, verlässt kein Code die eigene Maschine. Für Teams, die mit proprietärem Code, Kundendaten oder unter DSGVO-Anforderungen arbeiten, ist das keine Komfortfunktion — sondern eine Voraussetzung.
Output Format
Always produce two files in the project root:
| File | Language | Notes |
|---|
BLOG.md | English | Substack-ready Markdown |
BLOG_DE.md | German | Natural translation — not literal; adapt idioms |
After both files are written, print a cover image prompt to the terminal (see the agent for the template).
What Developers Hate
Avoid these unconditionally:
❌ "In today's fast-paced world of technology..."
❌ "Simply do X" / "Just add X" / "It's easy to..." / "Obviously..."
❌ "As we all know..."
❌ Unpinned dependency versions in code examples
❌ Broken or incomplete code snippets
❌ No trade-offs section (reads as vendor marketing)
❌ 3-paragraph introduction before getting to the point
❌ Abstract descriptions where a diagram would do the job
