Every team we talk to has the same folder. It is called prompts/, or agents/, or nothing at all because it lives in someone's head. It holds the instructions that make an agent useful for this company — how to score a ticket, what a good PR review looks like, which words never go in a customer e-mail. And it is a mess: half YAML, half JSON, a few Notion pages, and one heroic Google Doc.
We think the file format is the problem, and that the answer is boring on purpose.
A skill is a contract, not a config
A skill tells an agent three things: when to use it, how to work, and what the output must look like. That is prose with a little structure — exactly what Markdown is for. Headings give you the sections, lists give you the rules, a fenced block gives you the output contract. There is nothing to escape, nothing to validate, nothing to render before a human can read it.
YAML and JSON optimise for machines parsing fields. Skills are read by a model, and a model reads Markdown the way you do. The moment you wrap instructions in {"rules": ["..."]} you have made them harder for both audiences.
Diffs you can review
A skill changes the way code changes: someone tightens a rubric, adds an edge case, removes a rule that backfired. With a .md file that is a normal pull request with a normal diff. Every version on emdly is exactly that — a numbered revision you can open, compare and pin.
Portable by default
A Markdown skill works in Claude Code, in a hosted agent, in a cron job that pipes it into the API, and in a README. It does not need an SDK. npx @emdly/cli add owner/skill is a download, and the raw URL is a curl. When the tooling changes — and it will — the file survives.
What we ask of a skill
Not much: a title, a body, a license. Our checks are there to keep the catalog trustworthy, not to impose a schema. If a .md reads well to a person, it will read well to an agent.
That is the whole bet. Files over frameworks.