Markback

Appearance

Markback for AI agents ​

Markback is meant to be written by hand — which makes it a natural fit for coding agents. There is a drop-in agent skill that teaches an LLM coding agent (Claude Code, Cursor, and the like) to read and write .mb files correctly, without any tooling in the loop.

The skill is a single self-contained manual covering the record model, the four layouts, % file headers, position ranges, structured feedback, canonical form, the lint codes, and the traps that bite hand-authors.

Get the skill ​

The skill is hosted here and mirrored in the repo:

Fetch it straight into an agent's skills directory:

bash
# Claude Code (project-local skill)
mkdir -p .claude/skills/markback/references
curl -sSL https://markback.org/skill/markback.md \
  -o .claude/skills/markback/SKILL.md
curl -sSL https://markback.org/skill/references/tooling.md \
  -o .claude/skills/markback/references/tooling.md

The manual is plain Markdown with skill frontmatter (name, description), so it drops into any agent framework that loads Markdown skills — adjust the target directory to match yours.

When the agent should load it ​

The skill's own trigger says it best: load it whenever the agent is reading or writing a .mb file — a sidecar of review comments, a batch of labels, or any feedback paired with content. The one rule worth memorizing before then: a record is optional @ headers, then an optional blank line and content, then exactly one <<< feedback line that ends it — and the blank line before inline content is mandatory, or a content line starting with @ is silently parsed as a header.

What the skill covers ​

  • The record and every header (@id, @reply-to, @by, @action, @tag, @input, @file), with canonical order.
  • The four layouts — full, compact one-per-line, multi-segment section, and sidecar — and when to reach for each.
  • File-level % headers and the sweep pattern (%scope + %covers), where the absence of a record is meaningful.
  • Feedback — single-line, the """ fence for multi-line, and the optional structured/json: conventions.
  • Reading a .mb file: how each line is classified and how sections inherit.
  • The canonical checklist and the traps verified against the current implementation, plus the full lint-code table.

The rest of the docs ​

The skill points back here for the details a human reader wants too: