Alexandr Zahatski

I am interested in personal publishing, decentralised systems and software engineering 💻

Latest record:

I keep my notes, specs and plans in plain text, and these days most of the edits come from Claude Code. The files looked fine. Then I ran a checker over them and found dozens of broken attributes. One caption with an unquoted > in it had silently turned into garbage. Another file lost the page anchor it was supposed to set. Nothing had flagged any of it while I worked.

Markdown couldn't have helped here. The CommonMark spec says so itself: "because nothing in Markdown counts as a 'syntax error,' the divergence often isn't discovered right away."^[1]

My files are in Podlite. It reads a lot like Markdown, but blocks are explicit and carry attributes. The editor below is live: remove the quotes around the caption and watch the table break.

It also has a linter that reports problems with a line number. The agent wasn't running it.

So I wrote two skills: one teaches the agent to write Podlite, the other makes it check what it wrote before handing it back.

I gave Claude Code a file that already had three mistakes in it and asked only for a new "Known issues" section. The caption was written as :caption<Requests with latency > 100 ms>. Without quotes, several words in angle brackets aren't one string, and the > in "> 100" breaks the value. The parser then lost the whole table: it rendered as plain text. That's more damage than one bad caption should do, and it's on my bug list.

The agent added the section. While reading the file it noticed a code block that was never closed and closed it. Then it ran the linter, traced the warnings on the table lines back to the caption, fixed the quoting and ran the linter again until it came back clean. The part I liked is how it finished:

Note: lines 15-17 (=item1 Features / =item3 ... / =item3 ...) skip list level 2 — pre-existing, unrelated to this task, and not flagged by the linter. Left untouched since it wasn't part of the request.

Before, I found these much later, when I went looking. Now it happens in the same session, with a line number.

I built both skills with Claude Code and tested the install in an empty project with nothing else loaded. Free, MIT:

npx skills add podlite/podlite-skills

Source

Try it on a document your agent has edited a few times and see what the check turns up.

This page is written in Podlite too: the editor, the tip, the caution and the footnote are blocks in its source.