AI Agent Skills: The Markdown Playbook
How modern AI agents learn new capabilities through plain-text Markdown skill files - and why a simple .md recipe beats thousands of lines of plugin code.
Beyond Plugins: How Agents Learn New Tricks
When most people think of extending software with new capabilities, they picture plugins - thousands of lines of Python or JavaScript compiled into a binary that some runtime loads at startup. That is how we have done it for decades.
Modern AI agents are different. Because the "engine" at the centre of an agent is a Large Language Model (LLM) that reasons in plain text, the most natural way to teach it a new skill is also plain text. Specifically, a Markdown .md file.
This shift is not a workaround. It is a fundamental design decision that makes agent capabilities human-readable, rapidly composable, and even self-generating.
The Playbook Analogy
Imagine you hire a human assistant for the first time. You have two options for teaching them your expense-report process:
| Option A | Option B |
|---|---|
| Surgically alter their brain | Hand them a printed playbook |
| Permanent, costly, irreversible | Fast, readable, updatable |
| Requires a specialist | Anyone can write or audit it |
Option A is the equivalent of fine-tuning an AI model - expensive, slow, and baked in forever. Option B is the equivalent of a Markdown skill file - a plain-text recipe the agent reads and follows on demand.
Frameworks like Claude Code, Hermes, and skill marketplaces like ClawHub distribute these recipes as .md files. When you "install a skill," you are literally dropping a new page into your agent's playbook binder.
What is Inside a Skill File?
A skill file is a highly structured prompt that teaches the agent when and how to perform a specific task. A well-designed file contains four sections:
1. The Trigger - When to use this skill
A brief description that tells the agent which user requests should activate this skill. This acts as a routing rule.
## When to Use
Activate this skill when the user asks to commit and push code,
open a pull request, or says /commit-push-pr.
2. The Recipe - Step-by-step instructions
Plain-English (or pseudo-code) instructions that walk the agent through the task. Because LLMs follow structured prose naturally, these read almost like a human checklist.
## Steps
1. Run `git status` to confirm there are staged changes.
2. Write a concise commit message summarising the *why*, not the what.
3. Commit with `git commit -m "<message>"`.
4. Push to the remote branch with `git push`.
5. Open a pull request using `gh pr create` with a summary body.
3. Tool Schemas - The utensils
If the skill needs to call an external tool - run a shell command, call an API, click a button - the Markdown file includes the exact JSON format required to trigger that tool. This is how agents bridge the gap between text reasoning and real-world actions.
{
"tool": "Bash",
"parameters": {
"command": "git commit -m \"$MESSAGE\"",
"description": "Commit staged changes with the generated message"
}
}
4. Examples - Few-shot learning
A few sample conversations showing the skill being executed correctly. LLMs learn extraordinarily well from demonstration - a single good example can anchor the model's behaviour more reliably than paragraphs of instruction.
## Example
**User**: commit and push my work
**Agent**: Running git status... 3 files changed.
Committing: "feat(auth): add JWT refresh token rotation"
Pushing to origin/feature/auth...
PR created: https://github.com/org/repo/pull/42
Why Markdown, Not Code?
| Factor | Markdown Skill File | Traditional Code Plugin |
|---|---|---|
| Format LLMs understand natively | ✅ Trained heavily on Markdown | ❌ Must be parsed into tokens |
| Human-readable | ✅ Anyone can read and audit it | ❌ Requires engineering expertise |
| Writeable by the agent itself | ✅ Agent can generate new recipes | ❌ Requires a developer |
| Deployment speed | ✅ Drop in a file | ❌ Build, compile, publish |
| Versioning | ✅ Plain text in git | ❌ Binary artifacts |
The first point deserves emphasis. LLMs are trained on enormous amounts of Markdown - GitHub READMEs, Reddit posts, Wikipedia articles, technical documentation. Headers, bullet points, code fences, and bold text are not decoration to an LLM; they are structural signals the model has learned to parse and follow with high reliability.
Self-Generating Skills: The Feedback Loop
The most interesting implication of text-based skills is that agents can write their own.
If you demonstrate a multi-step workflow to an agent - say, walking it through your deployment checklist manually - a capable agent can observe those steps and author a new .md skill file summarising the recipe. The next time you need that workflow, the agent reads its own recipe and executes it independently.
This creates a virtuous cycle:
Manual demonstration
↓
Agent observes steps
↓
Agent writes .md skill file
↓
Skill saved to playbook
↓
Future requests trigger skill automatically
This is qualitatively different from traditional software. You are not programming a system - you are training a collaborator, and the collaborator takes its own notes.
Skills in the Wild: Claude Code
Claude Code, Anthropic's CLI agent, uses exactly this pattern. Skills live as .md files in the ~/.claude/ directory. Each file has a frontmatter block describing the trigger and a body containing instructions. The agent reads all skill files at startup and routes user requests to the appropriate playbook entry.
---
name: commit-push-pr
description: Commit staged changes, push to remote, and open a pull request.
---
## Steps
1. Confirm staged files with git status.
2. Generate a commit message from the diff summary.
...
Skill files can also declare which tools they need access to, what output to expect, and how to handle errors - all in plain text that a non-engineer can read, critique, and improve.
Skill Distribution: ClawHub and Hermes
The file-based skill model becomes most powerful when skills can be shared. Two projects address exactly this: ClawHub as the discovery and distribution layer, and Hermes as a portable runtime that executes those skills across agents.
ClawHub - The Skill Registry
ClawHub is an open registry for agent skill files - effectively npm for .md playbooks. A developer publishes a skill by pushing a Markdown file with a standard frontmatter schema (name, description, trigger, tool requirements). Anyone else can install it with a single command that drops the file into the appropriate agent directory:
clawhub install commit-push-pr
clawhub install code-review --target ~/.claude/
Because every package in the registry is a plain-text Markdown file, there are no binaries to trust, no native dependencies to resolve, and no build step. The full contents of any skill are human-readable before installation. ClawHub also hosts versioned skill sets - curated bundles of related skills (e.g., a git-workflow bundle containing commit, push, PR, and branch-cleanup skills) that install as a group.
The registry model creates a compounding network effect: as more developers publish skills for domain-specific workflows, the practical capability surface of any agent using ClawHub expands without the agent developer having to do anything other than keep their skill directory up to date.
Hermes - The Portable Skill Runtime
Hermes is a lightweight agent harness designed around one principle: skills should be portable across models and hosts. Where Claude Code reads CLAUDE.md files and routes to Claude models, and Cursor reads .cursorrules and routes to its own model layer, Hermes defines a model-agnostic skill execution protocol so the same .md skill file runs correctly regardless of which LLM backend is underneath.
A Hermes skill file adds one additional frontmatter field - tools - that declares which tool schemas the skill requires:
---
name: summarise-pr
description: Summarise the diff of an open pull request into bullet points.
tools: [Bash, WebFetch]
---
## Steps
1. Retrieve the PR diff with `gh pr diff <number>`.
2. Identify changed files and the intent of each change.
3. Return a three-to-five bullet summary with no jargon.
Hermes validates tool availability at load time and surfaces a clear error if a required tool is missing - preventing silent skill failures at runtime. It also resolves skill dependencies: if skill A calls skill B as a sub-step, Hermes loads both and passes state between them through a typed context object, rather than relying on the model to remember intermediate results.
The practical implication is that a skill authored for Hermes and published to ClawHub can be consumed by any agent runtime that embeds the Hermes executor - whether that is a Claude Code session, a self-hosted LangGraph node, or a Goose extension. The skill file is the contract; the harness is interchangeable.
Top 10 Skills Across ClawHub and Hermes
The table below lists the ten most widely installed skills across both registries, ranked by combined install count. Because both use the same .md format, most skills are cross-listed - the runtime column indicates where they originated.
| Skill | Category | What It Does | Runtime |
|---|---|---|---|
| commit-push-pr | Git workflow | Stages changes, writes a commit message from the diff, pushes to the remote branch, and opens a pull request with a structured summary. | ClawHub / Hermes |
| code-review | Code quality | Runs a static analysis pass over the current diff, classifies findings as critical bugs or style notes, and optionally posts inline PR comments. | ClawHub |
| summarise-pr | Documentation | Fetches an open PR diff and returns a three-to-five bullet plain-language summary suitable for a Slack post or async standup. | Hermes |
| security-review | Security | Scans staged changes for OWASP Top 10 patterns - injection, broken auth, exposed secrets - and produces a severity-ranked findings report. | ClawHub / Hermes |
| test-and-fix | Quality assurance | Runs the project test suite, captures failing tests, generates targeted fixes, re-runs tests, and repeats until the suite is green or a configurable retry limit is reached. | Hermes |
| refactor-for-clarity | Code quality | Applies consistent naming, reduces function length, removes dead code, and simplifies conditionals across a specified file or module without changing observable behaviour. | ClawHub |
| daily-standup | Productivity | Reads recent git commits, open PRs, and linked issue comments, then drafts a concise standup update in the team's preferred format. | ClawHub |
| dependency-audit | Security | Checks package.json, pyproject.toml, or go.mod against public CVE feeds and flags packages with known vulnerabilities, providing upgrade paths. | Hermes |
| generate-docs | Documentation | Reads exported functions and types in a file, infers intent from names and signatures, and writes JSDoc or docstring blocks for any symbol missing documentation. | ClawHub / Hermes |
| deploy-checklist | DevOps | Runs a pre-deploy gate: confirms tests pass, checks for uncommitted changes, verifies environment variables are set, and produces a signed-off checklist before any deploy command is executed. | Hermes |
The Bigger Picture
Markdown skill files represent a shift in how we think about software extensibility. The interface between a human's intent and a machine's capability is no longer a type-safe API - it is a shared language that both humans and models can read, write, and reason about.
This has three practical consequences:
- Lower barrier to contribution. Domain experts who cannot write Python can write a playbook. A sales ops specialist can document their own workflow and ship it as a skill.
- Transparent automation. Because every skill is a readable document, auditing what an agent will do is as simple as opening a file. No black-box binaries.
- Composable intelligence. Skills can reference each other, be forked, remixed, and shared through registries - the same way open-source code spreads, but with a much lower entry cost.
The era of the AI plugin is giving way to the era of the AI playbook. And the playbook, it turns out, is just a well-written Markdown file.
Summary: Key Takeaways
- AI agent skills are typically defined as plain-text Markdown files, not compiled code.
- A skill file contains four key sections: a trigger (when to activate), a recipe (step-by-step instructions), tool schemas (JSON definitions for external actions), and examples (few-shot demonstrations).
- Markdown is ideal because LLMs are natively trained on it, it is human-readable, and - crucially - agents can write their own skill files.
- Frameworks like Claude Code and Hermes distribute capabilities as
.mdfiles, making agent extensibility as simple as adding a document to a folder. Registries like ClawHub act as a discovery and distribution layer - effectively npm for agent playbooks. - This model enables a feedback loop where demonstrated workflows become permanent, reusable skills without any engineering overhead.