Quarkdown & AI: The Agent Skill and Why Markdown Is the Bridge

This is the part that brought Quarkdown onto this blog in the first place. This platform is an experiment in keeping content machine- and AI-friendly — every page is also available natively as Markdown so AI systems can access it without noise. Quarkdown hits the same nerve from the production side: it explicitly markets itself as agent-friendly and ships its own skill for AI coding agents. After the practical tooling from part 8, this is where the circle to this site's theme closes.

What an "agent skill" is

A skill is a compact set of instructions an AI agent (such as Claude Code or ChatGPT) loads as soon as a particular task comes up — here: writing or editing a .qd file. Instead of relying on vague training knowledge, the model gets a precise working instruction and access to the truth: Quarkdown ships a full offline copy of its wiki and stdlib API reference. So the agent can consult the real docs before generating code — instead of guessing function signatures.

How the skill works

The flow is deliberately disciplined. The skill first resolves the install directory …

QUARKDOWN_INSTALL="$(quarkdown doctor get install-dir)"

… then reads the wiki index (docs/wiki/_nav.qd), the quickstart if needed, and the pages relevant to the task, only then writes the .qd file — and verifies it by compiling:

quarkdown c main.qd --strict --out /tmp/quarkdown-verify

The --strict from part 8 is the key trick here: it makes errors hard-visible instead of rendering them silently as boxes into the document. So the agent notices immediately when something doesn't compile and can fix it. "Read before writing, compile to check" — a way of working I can only confirm from my own day-to-day with agents.

Installation

Setting up the skill is quick. In Claude Code you symlink the bundled skill into your skills directory:

ln -s "$(quarkdown doctor get agent-skill)" ~/.claude/skills/quarkdown

After restarting the session it activates as soon as you ask the agent to write a .qd file; manually you trigger it with /quarkdown. For ChatGPT and other agents you simply upload the SKILL.md — its path is provided by quarkdown doctor get agent-skill. Quarkdown even points to its own eval measuring fluency with and without the skill.

Why Markdown is the bridge to AI

The deeper point goes beyond a single tool. Markdown has become the lingua franca between humans and language models: it's plain text, structured, free of rendering noise — exactly the format LLMs read and write most cleanly. What classic tools like LaTeX or DOCX make machine-processable but not model-friendly, Markdown delivers by nature.

Quarkdown extends this format without sacrificing machine readability: the source stays plain text, and an agent can both understand and produce the same .qd code — and build a polished artifact (PDF, slides, wiki) from it. Exactly this dual role makes it a natural partner for AI-assisted content production. It's the same bet behind this platform, which I describe in more detail in What is GEO? and Writing for AI: keeping content machine-readable makes it future-proof.

FAQ

Do I need the skill to use Quarkdown with AI?

No, but it helps noticeably. Without the skill the model guesses from its training; with the skill it works against the real, current docs and verifies its result by compiling. Especially for a still-young language with its own syntax, that's the difference between "plausible" and "actually compiles".

Does this only work with Claude?

No. The skill is a plain SKILL.md plus a docs bundle. Claude Code wires it in via symlink, other agents via uploading or referencing the file. The principle is agent-neutral.

What does this have to do with this blog?

The same idea from two sides: this site keeps existing content AI-friendly; Quarkdown produces content AI-friendly. Both rely on Markdown being the interface between human writing and machine reading.