# Blog

> Use when writing or revising developer-facing blog posts: technical articles, opinion pieces, project writeups, TILs, or learned-in-public posts that need one sharp angle/aha.

- Skill: `kriscard/blog` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kriscard/blog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kriscard/blog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kriscard (https://skillmd.com/u/kriscard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kriscard/blog

---


# Blog Post Writer

Writing for developers who've read too much mediocre content. The goal is one sharp **aha** the reader will actually share.

## Boundary

A blog post may teach, but it must still have an angle. If the user wants pure step-by-step instruction, use the tutorial skill instead. If they want a publishable article with a lesson, story, opinion, or project narrative, continue here.

## Philosophy

**One insight, clearly stated, well supported.** Not a survey. Not "here's everything I know about X."

The angle test:

> Readers think/do X, but they should think/do Y because Z.

If that sentence is weak, the post is not ready to outline.

## Workflow

When invoked with a structured receipt from `capture-receipt` or `close-day`, treat its proof as the starting evidence. Preserve receipt ID and daily/project/session backlinks as private draft metadata, run a public-safety gate, and never expose internal references in the article.

### 1. Find the angle

Identify the post's one-sentence angle before researching or outlining.

Complete when:
- the angle fits `Readers think/do X, but they should think/do Y because Z`
- the reader, misconception, and payoff are specific
- the post has one primary **aha**, not a pile of related points

If the angle is missing or mushy, ask follow-up questions before continuing.

### 2. Research only what the angle needs

Check current facts before drafting technical claims. Use available research tools for official docs, recent discussions, benchmarks, counterarguments, and examples.

Complete when:
- current docs or source material have been checked for any library/framework/API claims
- 2-3 concrete examples, data points, or counterarguments support the angle
- outdated or common-but-wrong advice is identified when relevant

Skip external research only when the post is explicitly personal, reflective, or based entirely on user-provided material.

### 3. Choose the post shape

Pick the smallest structure that serves the angle:

| Shape | Use when |
|-------|----------|
| Tutorial article | Teaching a process with a publishable lesson, not just instructions |
| Project writeup | Sharing what was built and what it proves |
| Opinion | Arguing for a clear technical judgment |
| TIL | Capturing one small useful discovery |
| Comparison | Helping readers choose between options |

Complete when the shape is named and every planned section supports the angle.

### 4. Draft the outline and wait

Present an outline before writing the full post. Do not draft the article until the user approves.

Outline format:

```markdown
Title: [specific and direct; avoid "A Guide to X" / "Everything about X"]
Angle: Readers think/do X, but they should think/do Y because Z.
Hook: [why this matters now]
Tension: [the common mistake or misconception]
Resolution: [the insight with evidence]
Example: [the concrete code/example/story that proves it]
Takeaway: [one sentence readers remember]
```

Complete when the user explicitly approves the outline or asks for changes and those changes are incorporated.

### 5. Write the draft

Follow the approved outline. Keep the reader moving toward the **aha**.

Rules:
- start with the interesting part, not "In this post..."
- write first-person and direct; avoid corporate hedging
- use short paragraphs, usually 1-3 sentences
- prefer concrete numbers, examples, and trade-offs over vague claims
- assume intermediate developer knowledge; do not explain basics unless the angle requires it
- show the wrong way before the right way when contrast teaches the insight
- keep code examples runnable, focused, and under 20 lines unless length is the point

Complete when the draft includes:
- suggested title
- body with evidence or examples
- code blocks with languages when code is present
- one-sentence ending that lands the insight

### 6. Review before delivering

Review the draft for technical correctness, voice, and angle discipline.

Complete when:
- every section supports the angle
- technical claims are sourced, verified, or clearly framed as experience/opinion
- filler phrases and AI-sounding transitions are removed
- the hook, tension, resolution, and takeaway are visible

### 7. Add publishing metadata only when needed

Run SEO checks only when the user intends to publish publicly, asks for SEO, or the post targets search traffic.

When SEO applies, include:
- meta description
- URL slug
- primary keyword
- 2-3 internal/external link suggestions

SEO must stay subordinate to the human reader.

### 8. Optionally save the approved artifact

After outline approval—or after a later full-draft approval—offer to append the artifact under `## ✍️ Drafts` in `1 - Projects/Public Technical Presence/Public Technical Presence.md` with receipt ID and private source backlinks. Show the exact write and require approval.

Use state `outline` or `draft`, never `published`. Only a user-confirmed public URL or explicit publication confirmation moves it to `## 🚀 Published`.

Complete when the approved artifact is saved with metadata or deliberately left in chat.

## Output

Default sequence:

1. Outline and approval request
2. Full draft after approval
3. Optional publishing metadata when SEO applies

Default length: 800-1500 words. Use shorter for TILs and longer only when the angle genuinely needs it.

## References

| Priority | Load when | Reference |
|----------|-----------|-----------|
| 1 | The angle needs a narrative arc, personal story, migration story, or before/after transformation | `references/story-circle.md` |
| 2 | A post shape has been chosen and a concrete section template is needed | `references/post-templates.md` |
| 3 | Revising a draft for voice, clarity, authenticity, or AI-slop removal | `references/voice-tone.md` |
| 4 | User wants SEO, public publishing metadata, or search traffic | `references/seo-checklist.md` |