spb/ultra-sharp-agent-skills Public

1---2name: writing-blog-posts3description: Writes technical blog posts built on one specific claim, a three-sentence hook, and real code, numbers, and failures. Use when the user asks to write a blog post, an engineering blog article, a technical write-up of a project or incident, or a dev.to/Medium-style post. Do not use for documentation, tutorials, or marketing landing-page copy — separate skills cover those.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Writing Blog Posts1213## When to use / when NOT to use14- **Use for:** technical blog posts, engineering write-ups, postmortem narratives for a public audience, "how we built X" articles.15- **Do NOT use for:** documentation (writing-technical-documentation), tutorials (writing-tutorials), API reference (writing-api-documentation), or landing-page copy (frontend-skills/creating-landing-pages).1617## House rules18191. **One idea per post, stated as a specific claim in the title.**20   - ✅ "We cut our CI bill 60% by deleting half our integration tests"21   - ❌ "Thoughts on testing"22232. **Hook in the first 3 sentences** — the problem, a surprising fact, or the result. No throat-clearing.24   - ✅ "Our CI bill hit $40k/month. The fix wasn't caching or bigger runners — it was deleting 4,000 tests. Here's how we decided which ones."25   - ❌ "Testing is a very important topic in software engineering. In this post, I will share some thoughts…"26273. **Real code, real numbers, real failures.** Specifics earn trust; sanitize secrets, keep the mess.28   - ✅ "The first attempt shaved 4% — nowhere near worth the two weeks it took."29   - ❌ "After some optimization, performance improved significantly."30314. **Subheadings tell the story alone.** A skimmer reading only headings gets the arc.32   - ✅ "The $40k bill → What the tests actually covered → Deleting with a safety net → Results after 90 days"33   - ❌ "Introduction → Background → Discussion → Conclusion"34355. **Personal experience over generic advice.** "We did X and Y happened" beats "you should X".36   - ✅ "We tried contract tests first; they caught 2 of the 17 regressions."37   - ❌ "Consider using contract tests, which can catch regressions."38396. **Honest limitations section** — where this wouldn't work, what you'd do differently.40   - ✅ "This only worked because our unit coverage was already strong; with flaky units, deleting integration tests would be reckless."41   - ❌ Presenting the approach as universal.42437. **At most one call-to-action**, at the end.44   - ✅ One "we're hiring" or one "try the tool" link.45   - ❌ Newsletter box, three product links, and a webinar pitch mid-article.4647## Workflow48491. Write the claim as one sentence; if it needs "and", split into two posts.502. Collect the evidence: numbers, code snippets, timelines, failed attempts. No evidence → no post yet.513. Outline as story-telling subheadings (rule 4); check the headings alone carry the arc.524. Draft: hook first (rule 2), then the story, then limitations, then the single CTA.535. Self-review pass: delete every sentence that could appear unchanged in anyone else's post on the topic; verify every number has a source; confirm exactly one CTA. Fix and re-check.5455## Edge cases56- **No hard numbers available** → use concrete qualitative specifics (timeline, error messages, before/after code); never invent or round up.57- **Company-sensitive details** → replace absolute revenue-like numbers with ratios/percentages, and say you did.58- **Post is really a tutorial in disguise** (reader follows steps) → switch to writing-tutorials.5960## References61Extended before/after examples: see [references/examples.md](references/examples.md).62