Technical Blog Post Writer

What this skill does

This skill directs the agent to write a complete technical blog post on a given topic — from a strong hook through to a practical conclusion — targeting a developer audience. It produces content that is technically accurate, conversational without being sloppy, and structured for both skim-readers and deep-readers. It also outputs an SEO title and meta description.

Use this when you need to publish a tutorial, an opinion piece, a launch announcement, or a "how we solved X" post on your engineering blog.

How to use

Claude Code / Antigravity

Copy this file to .agents/skills/tech-blog-writer/SKILL.md in your project root.

Then ask:

• "Write a blog post about how we migrated from REST to GraphQL using the Technical Blog Post Writer skill."
• "Use the Technical Blog Post Writer skill to write a tutorial on using React Query for server state management."

Provide:

• The topic or title idea
• The target audience (junior devs, senior backend engineers, general developer audience, etc.)
• The tone (opinionated/personal vs neutral/tutorial-style)
• Any key points, code snippets, or conclusions you want included
• Target length if you have a preference (default: 800-1200 words)

Cursor / Codex

Paste the instructions below into your session along with your topic brief.

The Prompt / Instructions for the Agent

When asked to write a technical blog post, follow these steps:

1. Plan before writing

Before drafting, identify:

• The problem the post addresses (developers reading this have this pain point)
• The insight or solution the post delivers
• The reader's takeaway — what can they do differently after reading?
• The assumed skill level — calibrate vocabulary and explanation depth accordingly

2. Structure the post

Every post must follow this structure:

Hook (first 2-3 sentences) Open with a relatable scenario, a surprising stat, or a bold claim. Do NOT open with "In this post, I will...". Do NOT open with a definition ("Docker is a containerization platform..."). Make the reader feel the problem before you name it.

The Problem (1-2 paragraphs) Describe the situation that led to needing this solution. Be specific. Use concrete numbers and scenarios, not vague abstractions.

The Solution / Tutorial body The core content. For tutorials:

• Use numbered steps for sequential processes
• Use H2 headers for major sections, H3 for sub-sections
• Include code blocks with the correct language tag (``typescript, ``bash, etc.)
• Explain why before how — readers skip the "why" but they remember it
• Keep code examples minimal but complete enough to run

For opinion/analysis posts:

• Make a clear claim
• Support it with evidence (benchmarks, examples, experience)
• Acknowledge counterarguments briefly

Conclusion (1 paragraph) Summarize the key takeaway in one sentence. Tell the reader what to do next (try it, read this other post, open a GitHub issue, etc.).

3. Tone rules

• Write how a senior developer would talk to a junior colleague over Slack — friendly, direct, no corporate buzzwords
• Use "you" to address the reader
• Use contractions naturally ("you'll", "it's", "don't")
• Avoid: "leverage", "utilize", "seamlessly", "robust solution", "in conclusion, it is evident that"
• Short paragraphs (3-4 sentences max for body text)
• Use bullet points for lists of 3+ items, not inline commas

4. Code examples

• Show real, runnable code (not pseudocode unless the concept genuinely requires it)
• Include comments in code blocks to explain non-obvious lines
• When comparing before/after, show both blocks clearly labeled
• Do not show code that would require the reader to fill in 10 imports to run

5. Output format

---
title: [SEO-optimized title, 50-65 characters]
meta_description: [150-160 character description including the primary keyword]
---

# [Post Title]

[Post body in markdown]

After the post, add a short "Editorial notes" block (not part of the published post):

## Editorial Notes
- Primary keyword: [keyword]
- Suggested tags: [tag1, tag2, tag3]
- Estimated reading time: [X min]
- Suggested internal links: [topics to link to]

Example

Input to Agent:

"Use the Technical Blog Post Writer skill to write a post about using environment variables correctly in Node.js. Target: junior to mid-level Node.js developers. Tone: tutorial-style. Key points: dotenv, never commit .env, process.env validation with zod. ~800 words."

Output from Agent:

---
title: How to Manage Environment Variables in Node.js the Right Way
meta_description: Learn how to use dotenv, validate env vars with Zod, and avoid the mistakes that expose secrets in Node.js projects.
---

# How to Manage Environment Variables in Node.js the Right Way

You've seen it in a GitHub commit history: `remove API key oops`. Someone hardcoded a secret,
pushed it, and then panicked. It's more common than anyone admits.

Environment variables are how you keep secrets out of your codebase — but there's a right way
and a wrong way to use them. Here's how to get it right from the start.

## The basics: dotenv

...

Notes

• If you have a specific code example you want included, paste it when making the request. The agent will incorporate it naturally rather than inventing a different example.
• The skill writes a first draft. Technical accuracy of any code examples should be verified by the author before publishing.
• For posts involving benchmarks or specific version numbers, provide those numbers explicitly — the agent should not invent them.
• If the post is about a proprietary internal system, give the agent enough context about what the system does so it can write accurately without access to your codebase.