# Authoring AutoVault Skills

A skill is one SKILL.md file: YAML frontmatter plus a markdown body. Open Agent Skills fields provide the portable core: name, description, optional metadata, and resources. AutoVault extensions add production validation fields for canonical tools, transform maps, capability declarations, resources, secret requirements, signed setup actions, and target agents.

## Minimal shape

```yaml
---
name: skill-author
version: 1.0.0
description: "Author a well-formed SKILL.md with valid AutoVault frontmatter."
license: MIT
tools_required:
  - fs.read
  - fs.write
transformations:
  claude-code:
    fs.read: read
    fs.write: write
  codex:
    fs.read: file_read
    fs.write: file_write
capabilities:
  network: false
  filesystem: readwrite
  tools:
    - fs.read
    - fs.write
agents:
  - claude-code
  - codex
---

# Skill Author

Use this skill when the user wants to create or repair a SKILL.md file.
```

## Schema and validation

- Keep the open SKILL.md core portable: name, description, metadata, resources, and markdown body should still make sense without AutoVault.
- Declare canonical tool names in tools_required.
- Map caller-specific tool names in transformations instead of forking the skill.
- Use the capabilities block for declared network, filesystem, and tool boundaries; the host agent still owns runtime enforcement.
- Use requires-secrets for secret names and purposes only. Never put secret values in SKILL.md, resources, transforms, or vault files.
- Use signed bin setup actions only for user-run setup, verify, or rotation workflows.
- Package resources beside SKILL.md and load them through get_skill with include_resources.

## 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 deployment platform secrets.

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.
- Use signed bin setup actions for interactive configuration that the user runs in their own terminal.

Avoid:

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

## Scope

Scope is local policy, not a frontmatter substitute. Use it to decide which agents, projects, devices, and profile links can load the signed skill after admission.

## Admission

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.