Sscribnet.io
Zero to Dangerous

Agentic Markdowns

One library of plain-text files that gives every AI you run — local or cloud — the same personas, skills, and memory. Write it once, use it in every tool.

6 chapters~15 min readIntermediate
Chapter 1

Why Markdown Won

Every AI platform began by inventing its own configuration: a settings page here, a JSON blob there, a "custom instructions" box with a character limit somewhere else. Those configurations share three fatal properties. They are trapped inside one vendor's product, so switching tools means starting over. They are invisible — you cannot diff them, review them, or roll them back. And they do not compose: there is no way to say "this agent gets these three abilities plus that personality" and have it mean the same thing on two platforms.

Plain-text files fix all three, for a boring reason: text files are the most portable technology in computing. A Markdown file written today will be readable by every tool you are likely to run in 2030, including tools that do not exist yet. It versions in Git, so every change has an author, a date, and a reason. It can be read by a human in an editor and by a model in a context window with equal ease — no parser, no SDK, no export wizard. And because it is just files in folders, pieces recombine freely: a skill written for a coding agent can be handed to a research agent by copying a directory.

This is not a theory about the future; it is what already happened. Two file conventions escaped their home products and became open standards in late 2025, and the rest of the industry adopted them within months. The library this book describes is built entirely on those two conventions, plus one older idea borrowed from how good teams have always worked: a short list of shared principles that every specialist inherits, so the whole fleet behaves consistently even though each agent has a different job.

Tip: If a configuration cannot be put in Git, it is not an asset — it is a liability with a login page. The test for any agent setup is: "if this vendor vanished tomorrow, what do I still own?"
Chapter 2

The Two Standards

AGENTS.md is the instruction standard. It began at OpenAI in mid-2025 as a simple idea — a README written for machines instead of humans, living at the root of a project — and governance moved to the Agentic AI Foundation under the Linux Foundation that December. It is deliberately format-less: plain Markdown, no required fields, no frontmatter. Tens of thousands of projects use it, and Codex, Gemini CLI, Copilot, Cursor, and most other serious tools read it natively. Its job is the standing context an agent needs before any task makes sense: what this is, how we work here, what the boundaries are.

Agent Skills are the capability standard. Anthropic published the format in October 2025 and released it as an open standard at agentskills.io that December. A skill is a folder containing one required file, SKILL.md: YAML frontmatter carrying a name and a description, then Markdown instructions. The description is the clever part — it states both what the skill does and when to use it, so an agent can scan hundreds of skills and load only the matching one. That yields the format's defining trick, progressive disclosure, in three levels:

That economics lesson is why skills beat giant system prompts: expertise stops being a tax on every conversation and becomes a library the agent consults. Hermes, Claude, Codex, Gemini CLI, and other agent runtimes all speak this format now, so a skill written once genuinely runs everywhere.

Two neighboring standards complete the picture without competing. MCP standardizes how agents connect to tools and data; skills standardize what to do with those tools. A2A standardizes how agents talk to each other. Instructions, capabilities, connections, communication — four different layers, and this library deliberately lives in the first two, where portability is total and lock-in is zero.

Footgun: One major tool reads CLAUDE.md, not AGENTS.md. The fix is the oldest trick in software: generate the dialect from the source and stamp it "generated, do not edit." The moment you hand-edit a generated file, you have forked your agent's brain.
Chapter 3

Anatomy of a Persona

A persona in this library is a folder of five files, and the split is the design. Most agent setups cram everything into one system prompt, where personality, job description, rules, and facts blur into a single undifferentiated blob that nobody can maintain. Five files, five distinct jobs:

Above the personas sits a shared core/: the principles every persona inherits — verify before claiming, confirm before irreversible actions, never write secrets into files, fix the source not the output. Inheritance is what keeps a fleet coherent. When the researcher's skepticism and the coder's rigor both trace back to the same "say what you could not verify" principle, the agents feel like one team with specializations instead of four strangers wearing the same logo.

Two design choices are worth naming because you will feel them later. First, one persona per job, not per mood — if two personas differ only in tone, that is one persona with a SOUL variant, because every real persona carries maintenance cost. Second, the manifest makes personas composable: a new agent for, say, homelab operations is mostly a new folder plus a skill list assembled from parts that already exist. The library's value is not any single persona; it is that the next persona costs an afternoon, not a month.

Chapter 4

Memory and Skills: How an Agent Actually Learns

Strip the marketing away and an agent has two kinds of learning, matching the two kinds humans have. Declarative memory is facts: what is true. Procedural memory is skills: how to do things. The library keeps them in different files because they fail differently, age differently, and are written at different moments.

Declarative memory lives in MEMORY.md and is deliberately small and curated. Hermes, the strictest of the common runtimes, budgets roughly 2,200 characters for it in the always-loaded tier — and that constraint is a feature. Memory that tries to remember everything remembers nothing usefully; it bloats every context window and, worse, it gets believed when it goes stale. So the rules are strict: durable facts, preferences, decisions with their reasons, and dated lessons. Not transcripts, not status updates, not anything a live lookup answers better. And grown, personal memory stays on the machine that runs the agent — a shared library like this one holds seed memory only, because a Git repo, even a private one, is not a vault.

Procedural memory is the skills folder, and this is where self-improving runtimes like Hermes change the game: after a complex task, the agent writes its own SKILL.md capturing the procedure, the pitfalls, and the verification step. Read that again — the agent drafts its own training material from experience. Left alone, that produces drift and clutter. Run through a library, it produces a compounding asset: the agent experiments locally, the skills that prove themselves get reviewed, hardened, and promoted into the shared library, and from there they ship to every other platform in the next bundle build. One agent's hard lesson becomes every agent's standing knowledge. That promotion loop — local experiment, curation, shared library — is the closest thing in current tooling to how a good engineering team actually gets smarter.

Footgun: Both kinds of memory rot. Facts change (a "current" version number is a lie by spring), procedures quietly stop matching tools that updated, and skills accumulate steps nobody needs. The countermeasures are boring and effective: date every entry, prefer updating over appending, and periodically delete. A small, true memory beats a vast, approximate one — the same way a senior engineer with good notes beats one with a photographic memory of outdated facts.
Chapter 5

Making Them Experts

The first version of this library's personas was competent and shallow — the standard failure mode. They said things like "act as a senior engineer," which is an adjective, not an ability. The rebuild ran on a different principle: expertise is written as decision rules, checklists, and named traps, or it does not exist. Concretely, each persona now carries an expertise map (what it can defend, domain by domain), a working loop with a quality gate per step, doctrine stated as rules that fire identically every time — the researcher labels claims Confirmed, Corroborated, Single-source, Inference, or Unknown, and the words are not allowed to drift — red flags that make it stop and escalate instead of bluffing, and reference files that load on demand: a sizing checklist that forces the raw-to-usable capacity math into the open, an environment-ghosts table for the stale caches and phantom processes that mimic code bugs, a discovery question bank where each question states what its answer changes. That is the difference between a costume and a craft.

What is still weak (an honest audit)

None of these weaken the foundation; they are the roadmap of a system designed to be improved in the open, one dated changelog entry at a time. Start with the evaluation bench. A library you can measure is one you can trust — and trust, verified a little more each week, is the whole product.

Chapter 6

The Working Library

Standards and personas are the theory; this chapter is the daily practice — the three tools and one habit that keep a library like this true instead of merely tidy.

The validator: trust, but verify mechanically

A small script checks the whole library in one pass: every SKILL.md has valid frontmatter (name matches its folder, description present and sized for routing), every persona has its five files, every skill a persona claims actually exists — and a secret scan fails the build if anything credential-shaped sneaks into a file. Run it after every edit:

python3 tools/validate.py
# expect: ALL CHECKS PASSED

The scan matters more than it looks. Agent libraries invite pasted examples, real configs, real hostnames — the exact material that must never be committed. A mechanical gate beats a good intention every single time.

The builder: one source, every platform

When a persona changes, a builder script emits a per-platform bundle — the Hermes skill and memory folders, the generated CLAUDE.md, the GEMINI.md, the runtime-specific file sets — each with a manifest describing what goes where:

python3 tools/build.py coder --target hermes
python3 tools/build.py researcher --target claude
Tip: Pair every instruction you write — for an agent or a human — with a read-only checker and the output to expect. "Install the skills, then list the skills folder; you should see these names" teaches more than the install itself, because the reader learns to verify, not just to follow.

The habit: a changelog with teeth

Every change to the library gets a dated entry in the same commit — what changed, why, and anything parked or decided. Six months in, the changelog is the only honest history of why the fleet behaves the way it does, and it is where future-you finds out that a strange rule was a scar from a real incident, not a superstition. Write the scar tissue down; it is the cheapest expertise there is.

The dangerous checklist