Blog post writing guidelines for gkoreli.com. Use when writing, editing, or reviewing blog posts. Covers voice, structure, content format, sourcing rules, formatting balance, transparency, and technical writing standards for an engineering audience.
Instrucciones de origen · Vista previa de solo lectura
name
blog-writing
description
Blog post writing guidelines for gkoreli.com. Use when writing, editing, or reviewing blog posts. Covers voice, structure, content format, sourcing rules, formatting balance, transparency, and technical writing standards for an engineering audience.
license
MIT
metadata
{"author":"gkoreli","version":"2.2.0"}
Blog Writing — Agent Skill
Guidelines for writing blog posts on gkoreli.com — a builder's journal about agentic engineering, open source tools, and the craft of software.
When to Apply
Reference these guidelines when:
Writing a new blog post in packages/blog/posts/
Editing or reviewing existing posts
Drafting post outlines or structures
Cross-posting to dev.to or other platforms
Voice & Identity
Author: Goga Koreli — builder, not thought leader
Tone: Direct, technical, conversational. Write like explaining to a sharp colleague, not lecturing a classroom.
Perspective: First person. "I built this because..." not "One might consider..."
Honesty: Show failures and wrong turns, not just wins. "This didn't work because..." is more valuable than "Here's how to do it right."
No fluff: Skip intros like "In today's fast-paced world..." — lead with the thing.
Transparency: AI-assisted collaborative posts include the raw prompts that generated them. The author provides the substance — experience, perspective, lessons. The agent helps write. Exposed essays and OSS Radar issues do not ship prompts under their governing skills.
What Makes a Great Article
A great engineering blog post does several of these:
States a problem clearly — the reader should feel the pain before seeing the solution
Introduces novel ideas or perspectives — not rehashing what everyone already knows
Debunks myths — challenges popular but wrong assumptions with evidence
Showcases best practices AND anti-patterns — what to do and what to avoid, from experience
Highlights gotchas — the things nobody warns you about until you hit them
Shares personal growth — what changed in your thinking and why
Is transparent — about process, tools, trade-offs, and limitations
The goal: a reader finishes the post knowing something they didn't before, or seeing something familiar from a new angle.
Formatting Balance
Prose vs Structure
Not everything should be a paragraph. Not everything should be a bullet list. The rule:
Prose — for narrative, arguments that build, origin stories, personal reflections. When the reader needs to follow a thread of reasoning.
Bullet points — for enumerating distinct items, features, comparisons, lists of things. When each point is independent and the reader benefits from scanning.
Numbered lists — for sequences, ranked items, or when order matters.
Blockquotes — for strong opinion statements that deserve visual emphasis. The "quotable" lines. Always wrap the text in literal " quote characters inside the blockquote: > "The actual quote here."
Bold lead-ins — **Label:** followed by the point. Lets readers scan sections quickly.
Anti-pattern: Wall of Prose
If a section has 3+ paragraphs of continuous prose making distinct points, it probably needs restructuring. Break it up with:
A bullet list for the enumerable parts
A blockquote for the strongest claim
Shorter paragraphs (2-3 sentences max per paragraph)
Anti-pattern: Everything is Bullets
If the whole post reads like a slide deck, it loses voice and narrative. The personal sections — origin stories, reflections, arguments — need prose to land.
Hyperlinks
Use inline contextual links. Don't make readers go find things.
Link to repos, READMEs, npm packages, the blog itself
Link to specific pages when referencing tools or concepts
External links open in new tabs (handled by the markdown renderer)
Internal links (other posts, homepage) stay in same tab
Post Format
---
title: "Exact title — specific, not clickbait"
date: 2026-03-05
description: "One sentence that makes someone want to read it"
tags: [nisli, web-components, framework]
---
Content starts immediately. No preamble.
Frontmatter Rules
title — specific and descriptive. "A Reactive Web Component Framework in 660 Lines" not "My New Framework"
date — ISO format, publish date
description — one sentence, used for SEO meta and social cards
tags — lowercase, kebab-case, 2-5 tags
File Naming
NNN-slug-title.md — numbered prefix for ordering, slug for URL.
001-the-agentic-product-engineer.md
002-why-i-built-nisli-core.md
003-backlog-mcp-how-agents-manage-tasks.md
Prompt Files
Every AI-assisted collaborative post ships with its raw prompts — the human thinking that shaped the AI output. This is the blog's core transparency feature. Exposed essays have no prompt file because the author writes every word; OSS Radar issues are research-driven and also omit prompts.
Location: prompts/{slug}.prompts.md (matches the post slug, not the numbered filename)
Format: Raw ----delimited blocks. No frontmatter, no formatting. Stream-of-consciousness as written.
raw brain dump, corrections, direction for the first iteration...
---second prompt with more specific feedback...
---
third prompt pushing back on something...
How it renders (ADR-0003):
Article header: March 5, 2026 · 🔍 Prompted by human, generated by AI — 10 prompts (fingerprint icon, italic slogan, link to prompts page)
Article footer: Teaser card with slogan, preview of first prompt, "See behind the scenes →" link
Prompts page: /{slug}/prompts — standalone page with all prompts in numbered monospace blocks, own meta tags, independently shareable URL
Architecture: Prompts are a first-class route, not a widget. parsePrompts() is separate from parsePost(). The prompts page template evolves independently from the article template. Posts without a prompts file get no teaser and no prompts route — zero empty states.
Slogan: "Prompted by human, generated by AI" — appears in the article header, teaser card, and as the prompts page title.
Content Principles
Build in Public
Engineering posts and build logs should feel like chapters in an ongoing journey, not standalone tutorials.
Build in public is a growth practice. It invites a third-person eye into the projects and the person making them so the author can understand his own work and readers can grow alongside it. The material is broader than failure: architecture, methods, tenets, bets, plans, vision, ambition, and attempts to change the world all belong.
Use time according to the article's context:
Past: analyze experience, share lessons, and show growth.
Present: expose active judgment, ambiguity, bets, conditioning, pain, or uncertainty.
Future: state intent, vision, and what the project is trying to make possible.
One article may braid all three. Do not impose a tense, wound, lesson, or open loop as a house formula.
Show real decisions: "I chose X over Y because Z" with actual trade-offs
Show real numbers: bundle sizes, line counts, npm downloads, build times
Show real failures: "This approach failed because..." with what you learned
Open loops: when the governing form calls for one, end with what remains live or comes next
Complete the Engineering Lesson
A failure report is not yet a lesson. For every load-bearing mistake, the reader must be able to reconstruct:
Before: what was built, believed, or measured.
Break: what evidence exposed the mismatch and why the old mechanism could not answer the question.
Now: the current implementation or decision, shown with the same level of concrete detail as the failure.
Why: alternatives considered, decision rationale, and the tradeoff deliberately accepted.
Tenet: the bounded rule another engineer can carry without turning it into dogma.
Vision: what the repair is trying to make possible and which tension remains open.
Do not force these into six headings. Do make the comparison reconstructable through prose, code, diagrams, or tables. Present tense is not reserved for pain; it also names the system that exists now, the judgment behind it, and the bet it embodies. Critique without the repair teaches diagnosis but withholds growth.
Specificity Over Polish
Weak: "I've been working on my framework, things are going well."
Strong: "Week 3: Rewrote the component lifecycle. Old approach created 47 orphaned event listeners in a 10-component page. New approach: zero. Here's the diff."
Choose the Form First
Run shape-article before imposing structure. An exposed essay, essay of inquiry, field note, engineering argument, and research synthesis move differently and earn different endings. Never force a lesson, verdict, or open loop because a generic article template expects one.
Evidence-led Engineering Investigations
When an article starts from a system the author built or used and tests a disputed claim through implementation evidence, reproductions, primary documentation, and outside research, read references/evidence-led-engineering-investigations.md before research fan-out or drafting.
This is a conditional research mode, not the default structure for every sourced post. Use oss-radar instead when the article's subject and verdict are an open-source project or cohort.
Structure for Engineering Arguments and Build Logs
Lead with the thing — what you built, what you found, what broke. No preamble.
Context — why this matters, what problem it solves. Keep it short.
The meat — code, decisions, trade-offs, results. This is 70% of the post.
What I learned — honest reflection, not a summary.
What's next — open the loop for the next post.
Use this sequence only when it fits the material. Field notes may end at a blocker. Inquiry essays may deepen a question. Exposed essays end without a bow under personal-essays.
Code Blocks
Always specify language for syntax highlighting: ```typescript not ```
Keep code blocks focused — show the relevant 10 lines, not the whole file
Add brief comments in code only when the code isn't self-explanatory
For before/after comparisons, use two separate blocks with a sentence between
Interactive Elements
When a concept benefits from interactivity, embed a web component:
Here's the reactive counter in action:
<nisli-counterinitial="0"></nisli-counter>
Use sparingly — only when interactivity genuinely helps understanding. Most posts are fine with just text and code blocks.
Sourcing Rules
When to Use External Sources
This is a builder's blog, not a news outlet. External sources serve as evidence for claims, not as content filler. Use them when:
Backing a specific claim that readers might question
Attributing a concept or term to its originator
Pointing readers to deeper exploration on a topic
Don't overuse them. A post with 10+ external links feels like a research paper, not a blog.
Source Selection (strict priority order)
Original author's own post/tweet/repo — if someone coined a term or published a finding, link to THEIR source, not a summary of it
Authoritative builder blogs — engineers and builders who ship real things (e.g. Andrej Karpathy, Steve Yegge, Guillermo Rauch, Dan Abramov, Evan You)
Authoritative company engineering blogs — established companies sharing real engineering work (e.g. Vercel, Anthropic, GitHub, LangChain)
Academic/research institutions — for research-backed claims (e.g. Columbia, Stanford, MIT)
Reputable tech publications — MIT Technology Review, Pragmatic Engineer, etc.
Source Anti-Patterns
Never use subscription-gated articles — if the reader can't access it freely, don't link it
Avoid Wikipedia as a source — find the original. Wikipedia is a starting point for research, not a citation. Exception: only if the original source is genuinely unfindable.
Avoid generic SEO content farms — sites that exist to rank for keywords, not to inform
Avoid outdated sources without context — agentic engineering moves fast. A 2-year-old article about AI agents is likely outdated. If you must use it, note the date and acknowledge what may have changed.
Avoid news aggregators — link to the original, not the outlet that summarized it
Glossary Section
Posts that make claims backed by external evidence should end with a ## Glossary section. This is NOT part of the article narrative — it's a reference appendix.
Format:
---
## Glossary
| Term / Claim | Source | Date |
|---|---|---|
| Context engineering | [Andrej Karpathy](https://link) — "the delicate art and science of filling the context window..." | Jun 2025 |
| Vibe coding | [Andrej Karpathy on X](https://link) — coined the term | Feb 2025 |
Rules:
Always include dates — the industry evolves fast, readers need to know how fresh the source is
Use a table format — visually distinct from the article body, scannable
Link to the original source — not a summary or aggregator
Keep descriptions brief — one line per entry
Separate from article with a horizontal rule (---) — the glossary is a reference section, not a continuation of the narrative
Monorepo architecture, TypeScript tooling, open source maintenance
Post Types
Deep dive — technical exploration of one system/decision (e.g. "How nisli/core's template engine works")
Build log — what happened this week/month, real progress and setbacks
Decision record — why we chose X over Y, with full trade-off analysis
Lessons learned — retrospective on a completed project or milestone
Anti-Patterns
Don't write generic tutorials that could be about anyone's code — write from YOUR experience
Don't use "we" when you mean "I" — this is a personal blog
Don't pad posts with background the reader already knows — link to it instead
Don't bury the lede — if the interesting thing is in paragraph 5, move it to paragraph 1
Don't write engineering posts without concrete technical material. Personal essays do not need code.
Don't use AI-generated filler text — every sentence should carry information
Don't write walls of prose when bullets would be clearer — match format to content
Don't make every section bullets either — narrative sections need prose to land
Don't make unsubstantiated claims — if it's an opinion, own it. If it's a fact, source it.
Don't link to paywalled or subscription-gated sources
Don't use Wikipedia when the original source exists
Punctuation Rhythm
Em dashes are spice, not structure. Use them for genuine dramatic pauses or pivots, not as a default connector between clauses. If more than ~1 in 3 sentences has an em dash, the rhythm is monotonous. Replace the weaker ones with commas, periods, or parentheses.
Read paragraphs aloud — if every sentence has the same pause pattern, vary the punctuation.
Cross-Posting
Always publish on gkoreli.com first
Cross-post to dev.to with canonical_url pointing back to gkoreli.com
Share on X with a specific hook (not just the title) + #BuildInPublic
LinkedIn for milestone posts (launched, hit N downloads, etc.)
Quality Checklist
Before publishing:
Title is specific and descriptive
Description works as a standalone sentence
Post leads with the interesting thing, not preamble
Code blocks have language specified
At least one concrete number, metric, or specific detail
Formatting balance — prose for narrative, bullets for lists, blockquotes for strong claims
No walls of prose — sections with 3+ paragraphs of distinct points are restructured
External sources follow sourcing rules (original author, no paywalls, no Wikipedia)
For an evidence-led investigation, the claim table separates evidence states, stages, limits, counterevidence, and inference
Glossary has dates on all sources
Hyperlinks are contextual and useful (repos, READMEs, npm, blog pages)
Ending fits the governing form — no forced lesson, verdict, redemption, or open loop
Read it out loud — does it sound like you talking?
For AI-assisted collaborative posts, prompts file exists in prompts/ with all raw prompts that shaped the post; exposed essays and OSS Radar issues omit it
