Rune is the name runedeck gives an instruction artifact: a skill, an agent, or a rule, written as portable markdown, owned by you, and compiled for whatever AI harness runs it. First contact is the hands-on walkthrough; this page is what the words mean.
A deck is a git repository of runes. It is the canonical source: you version it, review
changes to it the way you review code, and everything a harness ever sees is compiled from
it in a step called assembly. Runes group into domains (such as core), and
casts name reusable selections across them. A project chooses what it wants with
rune add, which records the selection in a .rune manifest at the
project root.
SKILL.md, with companion files for depth,
scripts it can execute, and assets it can read.The frontmatter carries only portable Agent Skills fields: name,
description, license, compatibility,
metadata, allowed-tools. Anything tool-specific is banned from the
source on purpose; it arrives later, at assembly.
The body follows the Stable shell: one H1 whose text equals both the frontmatter name and
the directory name, then a fixed H2 vocabulary in order, of which only
Instructions is required:
# skill-name
## Prerequisites (optional, flat)
## Constraints (optional)
## Instructions (required)
## Verification (optional)
## Troubleshooting (optional)
## References (optional, flat)Task-specific H3 headings live under Constraints, Instructions,
Verification, and Troubleshooting; nothing goes deeper than H3.
More than four H3s under Instructions is the signal to move detail into
companion files. The point is predictable navigation: every skill opens the same way, for
readers and for machines.
A qualifier is a directory inside a rune: user/, a provider like
claude/, or a model nested beneath its provider like
claude/claude-opus-4/. A variant is the file inside it that overrides the base
file of the same name. At assembly, one variant is resolved (user/ wins, then
the provider's model directory, then the provider) and merged: its frontmatter keys replace
the base keys outright, and its body joins the base body according to its mode
(append, prepend, or replace). This is how a Claude deployment gains
argument-hint while the canonical source stays clean.
Two contracts, two checkers, told here for skills. A skill's frontmatter is validated
against a JSON Schema that rejects unknown fields; agents and rules carry lighter
frontmatter checks of their own. Body structure is validated against an
.mdschema: the standalone mdschema binary enforces the full
Stable shell (section order, unexpected sections, flat sections, uniqueness), while rune's
built-in fallback checks required sections, heading depth, and level continuity, and says
plainly what it could not check. Three checks are always rune's own: the identity check
(H1, name, directory must agree), the instruction-breadth warning, and a ban on markdown
tables in any rune, because models read labeled lists better than tables.
Two speeds for bringing in someone else's work. rune import records provenance
and lands the artifact without review. rune adopt is the review flow: the
artifact is split into blocks, an injection lint flags anything instruction-shaped (override
phrasing, tool-call patterns, encoded content, external URLs), and every block requires a
verdict, keep, adapt, or cut, before finalize will seal the record.
rune adopt doctor later verifies the sealed record three ways: the record's
digest, the file's digest, and the digest in its provenance sidecar, covered next, must all
agree.
rune add stages a selection, rune install assembles and deploys
it, rune doctor proves what landed. Deployed skills, agents, and rules carry a
provenance sidecar tracing each file back to its source. doctor never
overwrites an edit you made in place; overwriting takes a deliberate
rune install --force. rune drift compares a deployment against
its assembled baseline, or your source against the upstream it came from, with frontmatter
and body reported separately. Providers are configuration: a target directory plus a
transform list, which is why one deck can reach a harness that does not exist yet.
.rune file recording what a project selected, and the .manifest files recording what was deployed.Ready for the hands-on version? First contact walks the same ground with a terminal open.