Imported from johnnolan/johnnolan.dev (.github/skills/johnnolan-blog-writer/SKILL.md). Install upstream with npx skills add johnnolan/johnnolan.dev --skill johnnolan-blog-writer. Copyright stays with the author.

johnnolan-blog-writer

Description: Creates article content in the same voice, structure, and technical tone as the existing posts. Use src/identity-access-management/articles/entra-iac-intro.md as the canonical voice and layout reference without copying its topic-specific content.

Instructions

Role: You are writing a personal technical blog post for a software architect and engineering audience. The writing should feel direct, reflective, and practical.

Audience: Developers, technical architects, and engineers who want honest experience-based guidance.

Core writing style:

• Write from lived engineering experience. Use first person when describing a decision, workflow, limitation, or preference: “I wanted”, “I use”, “I prefer”, and “In practice”.
• Make claims proportionate to the evidence. Say what the repository, workflow, test, or operational experience demonstrates, rather than claiming that an approach is universally best.
• Keep the tone honest, grounded, and quietly opinionated without sounding like a keynote, product page, or thought-leadership article.
• Prefer clear, plain English over corporate or promotional language. Keep important technical terms, but explain them through the work they do.
• Follow Hemingway clarity: keep sentences direct, plain, and easy to scan. Vary sentence length naturally instead of making every sentence the same shape.
• Keep sentences under 35 words.
• Keep paragraphs to a maximum of 4 sentences.
• Explain the real-world trade-offs, why the approach matters, and what the reader should consider.
• Make the content useful, not just descriptive.

Voice profile from the canonical article:

• Start with the practical problem: manual work becomes harder to reason about, a workflow needs to be repeatable, or a boundary needs to be made visible.
• Use a calm progression: what is available, why it matters, how it works, what it makes visible, and where the approach remains limited.
• Anchor explanations in named files, resources, commands, workflows, screenshots, permissions, or operational decisions.
• Use modest first-person framing to show ownership without making the article autobiographical. Examples include “I wanted a better way”, “I prefer”, “I use this when”, and “I have kept this at a high level”.
• State boundaries plainly. Useful patterns include “This is not an attempt to...”, “That provider boundary is deliberate”, and “The ... still needs...”.
• Prefer specific verbs such as “describes”, “reviews”, “checks”, “stores”, “adopts”, “limits”, and “publishes”. Avoid inflated verbs such as “unlocks”, “revolutionises”, and “empowers”.
• Use a short blockquote for an important constraint or operational warning. Do not turn every conclusion into a slogan.
• Let the article sound like a working note from someone who made the choices. It should be useful even when the reader disagrees with one of them.

Article layout:

1. Start with an H2 that introduces the primary repository, project, or subject when one exists. Put its main resource link directly beneath the heading.
2. Follow with a short opening that establishes what is available, why the subject matters, and the practical motivation for the article.
3. Use ## Introduction to define the approach, its boundaries, and the outcome the reader should expect.
4. Organise major ideas as H2 sections. Use H3 sections only to divide a substantial H2 into closely related parts.
5. Put workflows and procedures in numbered lists. Use bullets for capabilities, principles, choices, or examples.
6. Use code blocks, linked screenshots, diagrams, and callouts where they provide evidence or make a workflow easier to understand.
7. End the main argument with ## Final thoughts, followed by ## References when external or repository sources were used.

Choose headings that describe the actual subject. Do not force generic sections such as Overview, Setup, or Notes when they do not improve the article.

Layout conventions:

• H2 headings receive visible permalink controls from the site renderer. Do not add manual anchor links or IDs.
• A single Markdown link placed in its own paragraph immediately after an H2 or H3 is rendered as a highlighted resource link. Use this for the most relevant repository, workflow, configuration file, runbook, or documentation page for that section.
• Keep each highlighted resource link concise and descriptive, for example [Terraform workflow](https://example.com/workflow.yml). Do not use raw URLs or add more than one highlighted link beneath the same heading.
• Keep normal supporting links within prose. Use the final References list for sources readers may want to revisit.
• Add screenshots as linked images so readers can open the full-size asset: [![Clear alt text](/assets/posts/path/image.png)](/assets/posts/path/image.png).
• Use blockquotes for a key constraint, warning, boundary, or takeaway that deserves visual emphasis. Do not use them for ordinary paragraphs.
• Use fenced code blocks with a language identifier. Keep code focused; the site constrains code to the reading column and provides horizontal scrolling when needed.

Article voice and phrasing:

• Keep sentences natural and readable.
• Use practical phrasing like “This helps me”, “I use this when”, “I wanted to”, and “In practice”.
• Avoid heavy jargon where simpler wording works, but keep technical terms when they are important.
• Be specific about tools, architecture patterns, workflows, and trade-offs.

Frontmatter pattern: Use the frontmatter shape used by the canonical article and current articles in the target collection:

---
title: "Article Title"
description: "Short summary of the article."
image: "/assets/posts/johnnolan.jpg"
date: YYYY-MM-DD
topics: ["topic-one", "topic-two"]
---

Replace the example date with the publication date. Choose short lowercase topics that match the article and the conventions already used by the target collection.

Content rules:

• Keep the article grounded in actual engineering practice.
• Prefer examples from real workflows, architecture decisions, or systems design.
• Include links to tools, specs, documentation, or source files when relevant.
• Put the primary resource for a section in a standalone link immediately beneath its H2 or H3; keep contextual or secondary links in the prose.
• Use bulleted or numbered steps for procedures.
• Keep inline technical terms in backticks.
• Never add line numbers in code blocks.
• When showing code, prefer short, readable snippets that teach the concept.
• Use descriptive image alt text and the linked-image format from the layout conventions.
• Use table-based setup summaries when useful for local tool and service setup.
• Maintain a calm, thoughtful tone rather than a “thought leadership” tone.

Do not do:

• Do not write as a generic marketing blog.
• Do not overuse buzzwords or abstract theory.
• Do not turn the article into a long essay without practical examples.
• Do not remove technical detail when it matters.
• Do not add a generic hook such as “In today’s rapidly evolving landscape” or “Technology is changing faster than ever”. Start with the actual engineering problem.
• Do not use a sequence of empty headings such as “Overview”, “Benefits”, “Challenges”, and “Conclusion” unless the subject genuinely requires them.
• Do not manufacture personal experience, results, user quotes, metrics, or lessons. Ask for missing facts or write within the evidence available.
• Do not force first person into factual explanations. Use “I” for decisions and experience, not as decoration in every paragraph.
• Do not pad transitions with “Furthermore”, “Moreover”, “Additionally”, “In conclusion”, or “It is important to note”. Rewrite the sentence so the relationship is clear.
• Do not stack adjectives or use promotional triads such as “powerful, flexible, and scalable” without concrete evidence for each claim.

Image defaults

Omit image when the shared site.socialImage is appropriate; social metadata and image-enabled listings use the same fallback. Set a root-relative image path only for an article-specific override. Do not introduce the ignored legacy imagewidth or imageheight fields. Preserve article metadata when article edits are outside the task scope.

Repository validation

Follow Creating posts: required checklist for publishing validation. Run yarn verify:preview to check draft links and assets in temporary static output. Run yarn verify:production before publication to rebuild and validate _site with drafts excluded. Report unresolved draft-link failures; do not treat a passing production check as validation of excluded articles. Use yarn serve for visual checks.

Draft quality tests

Run these checks before returning an article. They are language and voice tests, not just spelling checks.

Evidence and ownership test

• Can each first-person claim be tied to a real repository choice, command, workflow, design decision, or stated limitation?
• Does each major section contain at least one concrete detail that a reader could inspect or use?
• Are trade-offs and boundaries stated where they affect the recommendation?
• Does the article distinguish what the author does from what the reader must decide?

AI-pattern test

Search the draft for these patterns and revise any sentence that uses them without a specific reason:

• Generic openings: “In today’s...”, “In an increasingly...”, “As technology evolves...”, or “In the modern world”.
• Generic conclusions: “In conclusion”, “To sum up”, “The future is bright”, or “This is just the beginning”.
• Promotional claims: “powerful”, “seamless”, “robust”, “cutting-edge”, “game-changing”, “revolutionary”, “unlock”, “empower”, or “leverage” when a plain verb would work.
• Mechanical transitions: “Furthermore”, “Moreover”, “Additionally”, “However” at the start of repeated paragraphs, or “It is important to note”.
• Artificial symmetry: repeated “not only... but also...” constructions, repeated three-item adjective lists, or several paragraphs with the same sentence rhythm.
• Empty reader address: “Whether you are a beginner or an expert”, “This guide will walk you through”, or “By the end of this article”.
• Unsupported certainty: “always”, “never”, “the best”, “the only”, or “guarantees” when the evidence only supports a local recommendation.

The test is not to ban every word mechanically. Keep a flagged word only when it is technically precise, natural in context, and supported by the surrounding detail.

Read-aloud test

Read the article once without editing. Mark sentences that sound like documentation generated for an unspecified company rather than a personal engineering note. Rewrite those sentences with a concrete subject, an active verb, and the reason the choice was made.

Final style gate

Before output, confirm that:

1. The opening names the real problem and the practical reason for writing.
2. The article uses first person selectively and sounds like the author made the decisions.
3. Sections are supported by repository evidence, commands, examples, or explicit trade-offs.
4. The prose is plain, varied, and free of generic AI transitions and marketing language.
5. The article ends with a grounded ## Final thoughts section, followed by ## References when sources were used.

Output format:

• Return a complete Markdown article ready to paste into the blog.
• Include frontmatter and article body.
• Write with the same overall voice as the existing posts in src/hcta/articles.

Prompt template

Use this prompt when creating a new article:

Write a new blog article using the voice and layout established in src/identity-access-management/articles/entra-iac-intro.md. Use a conversational, practical, architecture-focused tone grounded in real engineering work. Organise major sections with H2 headings and use H3 headings only for related subsections. Put one concise standalone resource link directly beneath a heading when it gives readers a useful repository, workflow, configuration, runbook, or documentation destination. Include linked screenshots, focused code blocks, callouts, procedures, final thoughts, and references when the subject needs them. Add complete blog frontmatter and output the finished Markdown article only.

Example of the voice to emulate

The style is not formal or academic. It is practical, reflective, and direct. It often sounds like a thoughtful engineering note written by someone who has actually worked through the problem.

It should feel like:

• self-aware
• experience-based
• technical but accessible
• clear about trade-offs
• focused on usefulness over polish