---
title: "Making a Technical Blog Agent-Ready: Why and How We Built a Level 5 Agent-Native Website"
date: "2026-09-06T10:00:00+02:00"
tags: ["Agentic AI", "LLMs", "Hugo", "Cloudflare Pages", "Agent Readiness Directory", "llms.txt", "Web Performance"]
categories: ["AI & LLM Ops", "Web Performance"]
---

![Agent-Ready Architecture for Technical Blogs][1]

In today's post, I want to talk about something that completely changed how I think about running this blog: making it native for AI agents.

For years, I obsessed over optimizing [wojcieh.net](https://www.wojcieh.net) for human readers—tuning Core Web Vitals to 99/100 and cutting page load times down to milliseconds. But in 2026, a substantial portion of our traffic isn't humans clicking around in Chrome. They are autonomous AI coding agents (Antigravity, Cursor, Claude Code, Gemini CLI) searching for exact configurations, CLI flags, and YAML blocks to solve real engineering tasks.

Standard websites make this painful for agents, forcing them to burn thousands of tokens parsing megabytes of HTML boilerplate, cookie banners, and CSS just to extract five lines of config. Here is how I transformed this blog into a **Level 5 Agent-Native** platform that keeps 99/100 mobile PageSpeed for humans while giving AI agents zero-friction markdown endpoints.

<!--more-->

## Why Traditional Web Architecture Fails AI Agents

When an autonomous agent needs to answer a technical question (like *"How do I configure Traefik double-proxy with WireGuard?"*), standard web scraping introduces massive friction:

1. **Token Inefficiency:** A 10KB technical article typically comes wrapped inside a 400KB HTML DOM tree. Agents burn thousands of context tokens stripping out headers, sidebars, cookie modals, and footer links.
2. **JavaScript Rendering Walls:** Single Page Applications (SPAs) and dynamic client-side frameworks require heavy headless browser engines (Puppeteer/Playwright) just to render text.
3. **Loss of Code Formatting:** Naive HTML-to-text converters often mangle indentation, YAML colons, or bash pipe operators.

---

## The 3 Pillars of an Agent-Ready Blog

To make this site natively consumable by any LLM or autonomous agent, we implemented three core architectural standards:

### 1. Dual-Format Output: Native Markdown (`/index.md`)

Instead of forcing agents to parse HTML, we configured Hugo's multi-output engine in `hugo.toml` to generate parallel, raw Markdown files alongside standard HTML:

```toml
[mediaTypes."text/markdown"]
  suffixes = ["md"]

[outputFormats.Markdown]
  mediaType = "text/markdown"
  isPlainText = true
  isHTML = false

[outputs]
  page = ["HTML", "Markdown"]
  home = ["HTML", "Markdown"]
  section = ["HTML", "Markdown"]
```

Now, every article on this blog has a twin endpoint. A human visits `/goodbye-vmware-vexpert-next-chapter/` and sees a styled page, while an AI agent requests `/goodbye-vmware-vexpert-next-chapter/index.md` to get pure, unbloated markdown instantly.

### 2. The `llms.txt` and `llms-full.txt` Standard

Following the open `llms.txt` specification, we maintain two curated files in the web root:
- **`/llms.txt`**: A clean, structured markdown directory mapping core topics (Cloud Run, Homelab, vLLM, Traefik, Home Assistant) to their canonical URLs.
- **`/llms-full.txt`**: A bundled context file designed for RAG (Retrieval-Augmented Generation) systems that want to index entire technical summaries in a single HTTP request.

### 3. Agent Readiness Directory (ARD v0.9)

We declared our site capabilities in `/.well-known/ai-catalog.json`:

```json
{
  "spec_version": "0.9.0",
  "site": {
    "name": "Wojciech Marusiak IT Blog",
    "url": "https://www.wojcieh.net"
  },
  "readiness": {
    "level": 5,
    "level_name": "Agent-Native",
    "features": [
      "raw_markdown_endpoints",
      "llms_txt_standard",
      "structured_ai_catalog",
      "agent_skills_manifest"
    ]
  }
}
```

---

## Retaining 99/100 Core Web Vitals for Humans

Making a site agent-native does not mean sacrificing the human experience. By running Hugo Extended `0.165.0` on Cloudflare Pages with edge caching, we achieved:
- **Performance Score:** 99–100% on mobile and desktop.
- **Total Blocking Time (TBT):** 0 ms (analytics scripts for GTM and AdSense are loaded asynchronously without holding the main render thread).
- **Media Optimization:** 100% WebP image delivery across all historical posts.

---

## The Human-in-the-Loop AI Pair-Writing Pipeline

Finally, building an agent-ready blog reshaped how I write:
1. **Spoken Dictation:** I capture ideas, anecdotes, and technical war stories via audio notes or voice dictation.
2. **AI Drafting:** My assistant structures the thoughts into clear architectural guides with code blocks and diagrams.
3. **No-AI-Slop Filter:** Every draft passes through the `no-ai-slop` editing rules to purge corporate jargon (*delve, paradigm shift, game changer*) while preserving my personal voice and technical opinions.
4. **Automated CI/CD:** A single git push triggers a 4-second build on Cloudflare Pages.

As AI agents continue to change how software engineers find solutions, making your technical writing machine-readable isn't a gimmick—it is the future of documentation.

[1]: /images/uploads/2026/09/agent-ready-level-5-blog.webp