Docs/Authoring/Anatomy of a SKILL.md

Authoring · 12 min read

Write one skill.
Run it everywhere.

Authoring an AutoVault skill is writing a single SKILL.md that declares what it does, what it needs, and how it should be rendered for each calling agent. The vault handles the rest — validation, signing, scoping, transformation.

YAML frontmatterCanonical capabilitiesPer-caller transformPermission boundaries

Anatomy of a SKILL.md

Hover any block in the file below to see what it does and why it's there. The colored bands show how the validation gate parses each section.

● SIGNEDextract-pdf/SKILL.md33 lines · ed25519

1---
2name: extract-pdf
3version: 1.4.0
4description: "Extract structured text from PDF files."
5author: autoworks-ai
6license: Apache-2.0
7 
8tools_required:
9  - browser.fill_form
10  - browser.click
11  - fs.read
12  - fs.write
13 
14transformations:
15  claude-code:
16    browser.fill_form: chrome-devtools
17    fs.read: read
18  codex:
19    browser.fill_form: browser_form
20    fs.read: file_read
21 
22permissions:
23  network: false
24  fs_scope: ["./inputs", "./outputs"]
25  egress: deny
26 
27---
28 
29# Extract PDF text
30 
31Use this skill when the user provides a PDF path
32and asks for its text contents, structure, or
33summarization. Returns markdown with preserved
34headings, lists, and table layout where possible.

The transformation manifest

This is the part that distinguishes AutoVault from every other registry. The manifest is a flat dictionary keyed by agent identifier, mapping canonical capability names to whatever each agent calls them.

claude-code

browser.fill_form → chrome-devtools

browser.click → chrome-devtools

fs.read → read

fs.write → write

codex

browser.fill_form → browser_form

browser.click → browser_click

fs.read → file_read

fs.write → file_write

cursor

browser.fill_form → playwright_fill_form

browser.click → playwright_click

fs.read → fs_read

fs.write → fs_write

You don't have to map every agent. Unmapped agents fall through to the canonical name — which usually fails, which is intentional. Better to fail loudly with tool browser.fill_form not found than silently with a confused caller.

If your team uses an agent we haven't mapped, just add it to the manifest. The renderer will use it as soon as the next scope refresh fires.

Permissions: declared vs. enforced

This trips up new authors, so it's worth being clear: AutoVault is a content provider, not an executor. The vault never runs your skill. Permissions you declare are signals to the host agent about what the skill expects to do.

Declare exact canonical tools.
Declare network and filesystem scope.
Keep secrets as named references only.

Don't

Hide shell access inside prose.
Embed credentials in frontmatter.
Ship a generic helper skill with broad powers.

Try the gate yourself

This is the same five-step pipeline that runs on every skill admitted to a real vault — minus the actual signing step (we don't have your private key). Paste a SKILL.md, fetch a GitHub/raw URL, and click Run gate to see what passes, what warns, and what fails.

browser gateValidate this SKILL.md

Source URL

SKILL.md · editablelive clean

gate output

Run the gate to see yaml-repair, denylist, capability, dedup, transformation, and sign checks.

Publishing through the gate

Once your skill is happy locally, you have two paths to a shareable, validated artifact:

Proposed

source adapter

Repaired

frontmatter clean

Scanned

denylist + behavior

Signed

ed25519 provenance

Indexed

searchable · scopable

The other path uses autovault publish to push directly from the CLI — useful for quick iteration, with the same gate enforcement. Either way, the skill is signed against your vault's keypair before it leaves your machine.