Authoring · 12 min read

A skill is one file.
Frontmatter, body, that's it.

A SKILL.md is markdown with YAML frontmatter. AutoVault keeps the format plain, then validates the extra production fields it needs for capability mapping, capability signals, agent targeting, and signed delivery.

YAML frontmattertools_requiredtransformationscapabilitiesagents

Hover a field to see what it does

The colored rows show how the validation gate reads a skill: identity first, then tool requirements, rendering transforms, capability signals, and the markdown body the agent actually follows.

● SIGNEDextract-pdf/SKILL.mdproduction shape · v1.4.0

Frontmatter fields, in full

AutoVault does not need proprietary files beside SKILL.md. The fields below are the current production contract the gate and renderer understand.

Open Agent Skills fields. The fields name and description remain the portable core; license, resources, and the markdown body stay plain SKILL.md. AutoVault extensions add local validation, transform, scope, secret-requirement, and signed setup metadata around that open shape.

FieldTypeRequiredDescription

namestringyesCanonical id. Use kebab-case and keep it stable across releases.

versionsemver-likeyesVersion used for update checks, drift reporting, and provenance records.

descriptionstringyesOne concise sentence used during discovery and search.

licensestringoptionalLicense metadata. First-party examples currently use MIT.

tools_requiredstring[]yesCanonical capability names the skill body expects to use.

transformationsagent mapoptionalPer-agent mapping from canonical capabilities to caller-specific tool names.

capabilitiesobjectoptionalNetwork, filesystem (readonly/readwrite), and canonical tools declared by the skill author.

requires-secretsobject[]optionalNames and purposes of required secrets. Values are never stored in the skill.

binaction mapoptionalSigned user-run setup, verify, or rotation actions for out-of-band configuration.

agentsstring[]optionalSupported target agents before local scope narrows delivery.

resourcesfile[]optionalPackaged files loaded through get_skill with include_resources.

The transformation manifest

Authors write against canonical capability names. Transform maps adapt those capabilities for each caller at render time, so one source skill can become Claude Code, Codex, Cursor, or AutoHub-specific output without forking upstream content.

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

The capabilities block, in author terms

The full three-layer permission model — capabilities, transforms, and install scope — has its own page at /permissions. This section is the author-facing slice: what to put in the SKILL.md you are actually writing, and what AutoVault validates when it admits it.

Inside the skill, capabilities is the author's signal: which canonical tools the skill body uses, whether the network is needed, whether the filesystem is read-only or read-write. This is intent, not enforcement — the host agent still owns runtime gating. The schema is exactly three fields:

FieldTypeRequiredDescription

networkbooleanoptionalWhether the skill needs outbound network access. Defaults to false.

filesystem"readonly" | "readwrite"optionalFilesystem access expected by the skill body.

toolsstring[]optionalCanonical tool names the skill expects. Per-agent transforms can rename or override these.

Per-agent renames belong in a separate TRANSFORM.md; install scope belongs outside the skill entirely. See transforms and install scope.

Do (as an author)

List the canonical capabilities the skill body uses in tools_required — this is the field the gate checks against the body, and the one transforms map per agent.
Add a capabilities block alongside it to declare network, filesystem, and (optionally) the same tool list as readable metadata for reviewers and agents.
Ship one canonical SKILL.md and a TRANSFORM.md per agent variant, not three forks.

Don't

Hide network or filesystem expectations in prose instead of the capabilities block.
Embed credentials, tokens, or shell scripts in frontmatter.
Encode host-level install decisions inside the skill — that is the operator's job.

Secrets and .env variables

AutoVault is a skill vault, not a credential vault. A skill may describe that it needs authorization, but secret values belong in the host's real secret store: SSH agent, macOS Keychain, 1Password CLI, provider CLIs, or the deployment platform's secret manager. Do not put passwords, private keys, API tokens, or filled .env files in SKILL.md, resources, transforms, or the vault folder.

declare the requirement

requires-secrets:
  - name: SITE_SSH_ALIAS
    description: SSH config alias for the production host.
    required: true

This is metadata for review and setup. It stores the name and purpose, never the secret value.

set up outside the agent

bin:
  setup:
    command: bin/setup
    description: Configure SSH alias and key lookup.
    requires-tty: true

Use signed bin setup for interactive configuration. The user runs it in their terminal, so credentials do not enter the agent transcript.

Good pattern

Store SSH keys under ~/.ssh with a named host alias and least-privileged server account.
Store API tokens in Keychain, 1Password, provider CLIs, or platform secrets.
Teach the skill the safe workflow, expected remote paths, dry-run checks, and rollback commands.

Avoid

Do not bundle .env files, SSH private keys, access tokens, or copied dashboard secrets.
Do not instruct the agent to read ~/.ssh/id_*, ~/.aws/credentials, or full environment dumps.
Do not use AutoVault signatures as a substitute for secret rotation, revocation, or least privilege.

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. Paste a SKILL.md, fetch a GitHub/raw URL, and run the browser gate to see what passes, warns, or 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.

Admission through the gate

Once the skill is clean locally, all write paths use the same validation and signing pipeline before generated agent profiles refresh.

Proposed

source adapter

Repaired

frontmatter clean

Scanned

denylist + behavior

Signed

ed25519 provenance

Indexed

searchable and scoped