devops.rohitnb.com — Blog Post Skill

Produces correctly structured, publication-ready Markdown drafts for devops.rohitnb.com. Two post types exist: Concept and PoC. The rules for each differ significantly — read the right section before writing.

Step 0: Clarify if needed

Before writing, confirm:

  1. Post type — Concept or PoC? If unclear from context, ask.
  2. Topic / title — exact title or working title.
  3. Key points or outline — if the user has notes, take them as input. If not, proceed with the topic alone and make reasonable practitioner assumptions. Do not ask for information that isn’t needed to start writing.

Jekyll Front Matter

Every post gets front matter in this format:

1
2
3
4
5
6
7

---
title: "Post Title Here"
date: YYYY-MM-DD 00:00:00 +0000
categories: [<top-level>, <theme-cluster>]
tags: [Tag1, Tag2, ...]
mermaid: true   # only if the post contains a Mermaid diagram
---

Categories:

Use today’s date unless the user specifies otherwise.

Concept Posts

Target length

600–1000 words in the body. If it’s running over, it’s probably two posts.

Tone

Practitioner voice. Write as someone who has done the thing and is explaining it to a peer. No marketing language. No hedging. State the idea, defend it, move on.

Required structure

  1. Open with the problem or tension — not the solution, not a restatement of the title. The reader should feel the friction before you name the answer.
  2. State the concept clearly in the first third — once the tension is established, name the concept directly. Don’t make the reader wait.
  3. One concrete example — ground the concept in something real and specific. A scenario, a failure mode, a system the reader would recognise.
  4. Close — end with a natural conclusion that stands alone. Do not add cross-link placeholders or “coming soon” notes.

    Diagrams

    Use a Mermaid diagram when the concept involves system relationships, data flow, or sequencing. One diagram per post, placed where it replaces the most prose. Set mermaid: true in front matter. If the concept is purely argumentative (no system structure to show), skip the diagram.

What to avoid

PoC Posts

Target length

As long as it needs to be. Do not truncate to save space — a truncated PoC breaks the reader’s flow. Every step the reader needs to replicate the work must be present.

Tone

Step-by-step but not robotic. Narrate decisions, not just commands. When a choice was made — why that image, why that config, why that approach — say so briefly. That’s what separates a PoC from a tutorial transcript.

Required structure

  1. Opening paragraph — what you’re building and what the reader will have at the end. One short paragraph, no fluff.
  2. Prerequisites — explicit list. Do not assume. Include versions where they matter.
  3. Walkthrough — broken into logical phases, not just sequential numbered steps. Name the phases (e.g. “Setting up the worker”, “Wiring the step template”, “Running your first agent task”). Within each phase, use numbered steps only when sequence is critical; otherwise prose.
  4. Known limitations / what I’d do differently — required closing section. This is the highest-credibility section in any PoC. Be honest about rough edges, things that surprised you, and what a production version would need.

    Code blocks

    Always syntax-highlighted. Always complete enough to copy-paste without guessing. Never use a code block for output that belongs in a screenshot placeholder, and never use a screenshot placeholder for output that belongs in a code block.

Visual content placeholders

PoC posts often need screenshots, GIFs, or video. Since you’re drafting text, insert clearly labelled placeholders where visuals belong:

1
2
3
4
5
6

<!-- SCREENSHOT: Octopus step template configuration panel, showing the AI agent
     parameter fields filled in -->
 
<!-- GIF: Terminal showing the agent running non-interactively, stdout streaming -->
 
<!-- VIDEO: Full end-to-end run from triggering the runbook to artifact attached -->

Rules for placeholder types:

Output

Save the post as a Markdown file named:

1

YYYY-MM-DD-slugified-title.md

Use today’s date. Slugify the title: lowercase, hyphens for spaces, no special characters.

Write the complete post in the file. Present it to the user with present_files so they can download and iterate on it directly.

After presenting, note in one sentence whether you’d suggest any structural changes (e.g. “The prerequisites section could be split if you add more tooling context”). Keep the note short — the user will drive iteration.