I've been keeping a personal knowledge base for years. Notes, specs, decisions, journal entries — all in plain text files. When AI agents became part of my workflow, I started using them to write structured documents: RFC drafts, revision histories, typed notes with metadata. It worked well. Until I closed the session.
The next agent would open the same file and start from scratch — not because it forgot, but because the file gave no structure to hold onto. That's when I started looking at the format, not the model.
The problem I kept running into
My knowledge base has hundreds of files. An agent can read them, but reading isn't the same as understanding the shape of the file. Is this a journal entry or a spec? Is this draft published or scheduled? When was it written?
Plain text doesn't answer those questions. Markdown frontmatter gets you partway — but it's a convention, not a contract. Tools may or may not parse it, and agents that haven't been told what to look for usually don't. When I asked an agent to "write a blog post and schedule it for next Thursday," it produced great prose and put a date somewhere in the text. My publishing pipeline saw nothing.
The problem wasn't the agent's writing. The problem was that the file had no machine-readable structure. The agent had nowhere to put the metadata so that both humans and downstream tools could reliably find it.
What Podlite gives you
Podlite is a markup language built around explicit, typed blocks. Every block has a declared type, and blocks can carry named attributes — structured metadata that travels with the content.
Here's what a blog post looks like when an agent creates it:
=begin pod :pubdate('2026-03-12 10:00:00') :type('page') :publishUrl('/blog/podlite-skills')
=TITLE One command to add structured markup to your AI agent
Content written by the agent...
=end pod
The :pubdate, :type, and :publishUrl attributes aren't decorative. They're fields — any parser or tool that reads Podlite can access them directly, without guessing where in the prose to look.
Podlite natively includes Markdown, so you don't throw away existing files or habits. You can use Markdown syntax inside Podlite blocks without any changes. The structure layer sits on top; the content layer stays familiar.
How this plays out in practice
I ask Claude Code to draft a blog post about a recent technical decision. It creates a .podlite file with :pubdate set to next Wednesday and :publishUrl matching the slug I described. The prose is good. The metadata is correct. I close the session.
On Tuesday, I open a new session and ask a different agent to review the post and push the publish date back a week — I want more time to add a code example. The agent opens the file, reads the block header, finds :pubdate, changes the timestamp. That's it.
Worth slowing down on: the second agent didn't need context from the first session. The file itself carried the instructions. :pubdate is not a comment or a prose sentence — it's a structured field that any agent, parser, or tool can read without guessing. What acts on it depends on your setup — in my case a publishing pipeline that scans the folder and schedules based on the attribute. But the attribute is readable by anything.
This is the difference between "metadata mentioned in the file" and "metadata in the file."
Installing podlite-skills
npx skills add podlite/podlite-skills
This adds Podlite support to your AI agent environment — Claude Code, GitHub Copilot, Cursor, Codex CLI. After installation, the agent understands Podlite block syntax, attribute conventions, and how to create well-formed structured documents.
No configuration file to edit. No extension to install separately. The skill installs, and the agent knows the format. Even without a custom pipeline, you get files where an agent consistently puts type information and metadata in the same place — which means the next agent (or the next you, in six months) can read the file and know exactly what it is and what state it's in.
What I actually use it for
Three categories got noticeably better after switching:
Blog posts and RFC drafts — :pubdate, :status, :type mean any agent can pick up where another left off without me re-explaining the document's state.
Decision logs — typed blocks mean I can query "all decisions made in Q1" without parsing prose.
Specs with revision history — explicit block structure makes diff-reading much easier for agents doing review passes.
The files are still plain text. The agent still writes prose. The difference is that now the output holds its shape between sessions — metadata stays where it was put, structure stays parseable, and any tool or agent that opens the file later starts with something to work with rather than nothing.
If you're already using an AI agent for writing or documentation, this is a one-minute install:
npx skills add podlite/podlite-skills
The podlite-skills repository has the full list of supported blocks and attributes.
Top comments (1)
The distinction between 'metadata mentioned in the file' vs 'metadata in the file' is sharp. Curious if you've run into conflicts when two agents edit the same :pubdate in parallel — that's where structured blocks get tricky.