# Authoring AutoVault Skills

An AutoVault skill is a SKILL.md file with YAML frontmatter and markdown instructions. The frontmatter declares identity, capabilities, resources, permissions, target agents, and optional transform metadata.

## Minimal shape

```yaml
---
name: extract-pdf
version: 1.4.0
description: "Extract structured text from PDF files."
author: autoworks-ai
license: MIT
tools_required:
  - fs.read
  - fs.write
permissions:
  network: false
  filesystem: readonly
agents:
  - codex
  - claude-code
---

# Extract PDF

Use this skill when the user asks for text, structure, or summaries from a PDF.
```

## Validation expectations

- Keep the name kebab-case and the version semver-like.
- Declare every tool or capability the body actually uses.
- Keep secrets as named references, never literal credentials.
- Package resources beside SKILL.md and load them through get_skill with include_resources when an agent needs the extra files.
- Use the narrowest useful permission scope.

## Transforms

Vault-local transforms let a workspace or agent apply different instructions, tools, or setup without forking the upstream skill. AutoVault stores the transform under the vault, pins the base skill, applies it when get_skill renders for an agent, and reports base drift through check_updates.

## Publishing

Use propose_skill while iterating, add_skill for trusted remote sources or local bundles, and update_skill when replacing an existing skill. All write paths run through the validation and signing gate.