# Autovault Skill > Understand AutoVault-managed skills and how to install or update them. Use when a skill is visible via symlink, when authoring or editing SKILL.md, or before touching ~/.autovault/skills. Vault writes must go through `autovault add-local` or MCP propose_skill/update_skill so AutoVault re-signs; never hand-edit vaulted files and run sync-profiles. - Skill: `autoworks-ai/autovault-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add autoworks-ai/autovault-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/autoworks-ai/autovault-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: autoworks-ai (https://skillmd.com/u/autoworks-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/autoworks-ai/autovault-skill --- # AutoVault Meta-Skill AutoVault is the local capability and skill profile layer. It stores and validates skills, then syncs them into the agent's normal skill directory as filesystem symlinks. If this skill is loaded, AutoVault profile sync is already working for this agent; do not require an AutoVault MCP server before using other visible skills. AutoVault does not execute skills. The agent that loads a skill is responsible for sandboxing and user confirmation before running anything the skill describes. ## Hard rule: never write the vault by hand `~/.autovault/skills//` is a **signed store**, not a working copy. Hand-editing `SKILL.md` there invalidates the Ed25519 manifest (`autovault doctor ` reports `tampered` / `signature_invalid`). `autovault sync-profiles` only refreshes symlinks. It does **not** validate, hash, or re-sign. Author or edit a bundle **outside** the vault (a temp directory is fine), then install through the same gate humans and MCP use: ```bash # New skill, or replace an existing one by frontmatter name autovault add-local /path/to/bundle --sync-profiles # Preserve recorded provenance when replacing a local skill autovault add-local /path/to/bundle --source '' --sync-profiles ``` Confirm the vault accepted the write: ```bash autovault doctor --json # integrity.kind must be "ok" ``` If MCP tools are connected, `propose_skill` (new) and `update_skill` (existing) are the same gate. Use them when present. When they are absent **the CLI is required**, not optional. `autovault doctor --repair` re-signs a tampered **local** bundle only. Remote-sourced skills (GitHub, agentskills, URL) must be reinstalled or updated from upstream. Repair is a recovery hatch, not the authoring path. ## When to use - When the user asks why an AutoVault-managed skill is visible. - When deciding whether to use a synced skill such as `commit-message` or `skill-author`. - Before writing or updating a skill. Check installed skills first (`autovault skill search ` or the host's skill list). - When `autovault doctor` reports tampered integrity. - When debugging profile sync or stale skill links. ## Read path: synced skills AutoVault's primary interface is filesystem-native profile sync: ```text $AUTOVAULT_STORAGE_PATH/ skills/SKILL_NAME/SKILL.md transforms/SKILL_NAME/TRANSFORM_NAME/TRANSFORM.md rendered/AGENT/SKILL_NAME/SKILL.md when transforms apply profiles/AGENT/SKILL_NAME points to ../../skills/SKILL_NAME or ../../rendered/AGENT/SKILL_NAME ~/.claude/skills/SKILL_NAME points to ~/.autovault/profiles/claude-code/SKILL_NAME ~/.codex/skills/SKILL_NAME points to ~/.autovault/profiles/codex/SKILL_NAME ``` Use synced skills directly through the host's normal skill mechanism. If a skill is visible in the current agent session, it is already available; no `mcp__autovault__*` tools are required to *follow* it. For source-aware terminal installs, use the unified CLI: ```text autovault add ./path/to/skill --sync-profiles autovault add owner/repo:path/to/skill/SKILL.md autovault add https://github.com/owner/repo/tree/main/path/to/skill ``` GitHub imports collect every regular sibling file beneath the selected skill directory at one immutable commit. AutoVault rejects truncated trees, links, submodules, unsafe paths, and oversized bundles. If upstream frontmatter omits resource declarations, AutoVault adds them during bundle normalization and the install response exposes `inferred_resources` for review. For local troubleshooting, inspect the profile directory: ```bash ls -l ~/.autovault/profiles/claude-code ls -l ~/.claude/skills ls -l ~/.codex/skills ``` ## CLI workflow Use `autovault add` for known skills from local bundles, GitHub repositories, agentskills slugs, or HTTPS URLs: ```bash autovault add ./path/to/skill --sync-profiles autovault add https://github.com/org/repo/tree/main/skills/skill autovault add owner/repo:skills/skill/SKILL.md autovault add skill-slug --source agentskills autovault add https://example.com/SKILL.md --source url autovault add https://example.com/SKILL.md --source url --agent codex ``` For a local bundle you authored, `autovault add-local /path --sync-profiles` is the CLI write gate — the same validation and signing path as MCP `propose_skill` / `update_skill`. `autovault add` is for known sources (GitHub, agentskills, URL, or a local path). Do not hand-edit `$AUTOVAULT_STORAGE_PATH/skills` and then `sync-profiles`. If a remote skill lacks AutoVault-specific `agents` frontmatter, keep upstream bytes unchanged and route profile sync with `--agent `. Use `--no-sync-profiles` when you only want the skill stored in the vault. ## Optional compatibility: MCP tools Some hosts may still connect the AutoVault MCP compatibility server. Only use these tools if `mcp__autovault__*` tools are actually present in the current session. If they are absent, continue with the synced skills that are already visible. The compatibility server exposes these MCP tools: - `get_skill({name?, query?, agent?, top_k?, include_resources?})` - finds and loads an installed skill. Pass `name` for an exact skill, or `query` to search and load the best match. - `add_skill({source, identifier, version?, skill_dir?, sync_profiles?, profile_roots?, discover_profile_roots?, verbose?})` - installs from `github`, `agentskills`, `url`, or a local bundle. Local bundles sync configured profile roots by default. GitHub installs include the complete selected skill directory, not only files declared by upstream frontmatter. - `update_skill({name, source?, identifier?, skill_dir?, skill_md?, resources?, reuse_existing_resources?, verbose?})` - refreshes or replaces an installed skill. Use `source: "inline"` plus `reuse_existing_resources: true` for SKILL.md-only frontmatter edits. - `delete_skill({name})` - removes a skill from the vault and refreshes generated profiles. - `propose_skill({skill_md, resources?, source_session?, allow_synthesized_frontmatter?, check?, verbose?})` - validates, dedups, and installs a new skill. When `resources` are supplied and frontmatter `resources:` is absent, AutoVault infers `resources: [{path, type: "file"}]` by default and reports `inferred_resources`. Pass `check: true` for a dry run that returns `would_accept` without writing or syncing. - `bulk_import({source_dir, agents?, allow_synthesized_frontmatter?, sync_profiles?, profile_roots?, discover_profile_roots?, verbose?})` - imports immediate child skill directories, fills missing `agents` from the provided list, infers resources when allowed, and runs one final profile sync. - `check_updates({skill?})` - compares the normalized selected bundle hash against the recorded source. A repository HEAD/SHA change alone is not drift; changed `SKILL.md` or resource bytes are drift. Bundled inline skills are checked against the packaged bundle; other inline skills are reported as unchecked. ## Optional MCP workflow 1. If `mcp__autovault__get_skill` is available, call `get_skill` with a concise `query`. 2. If a result has high confidence, follow the returned skill. 3. If nothing fits, author a new `SKILL.md` and call `propose_skill`. Handle every outcome explicitly: - `accepted` - skill is stored under `$AUTOVAULT_STORAGE_PATH/skills/`. - `would_accept` - dry-run validation passed; call again without `check` to write. - `duplicate` - inspect `existing_match` and choose a `merge_options` value (`keep_existing`, `replace`, `merge`, `keep_both`). - `invalid` - fix the listed schema errors and resubmit. - `security_blocked` - rewrite the content to remove flagged patterns. 4. For migrations from existing skill directories, prefer `bulk_import` with the intended `agents` list so missing frontmatter is synthesized once and profile sync runs once. 5. Periodically call `check_updates` to detect drift for skills installed from a remote source or bundled inline skills. Package authors can install repository-shipped skills through the public library export `installBundledSkill`. It records signed `source: inline` provenance plus the stable bundled skill name, allowing later drift checks against the package's current `skills/` directory. Skip this workflow entirely when the MCP tools are not connected. Missing MCP tools are not an error for *reading* filesystem-synced skills. Missing MCP tools **are** a reason to use `autovault add-local`, not a reason to write `$AUTOVAULT_STORAGE_PATH/skills` directly. ## SKILL.md schema (minimum) ```yaml --- name: kebab-case-name description: At least 20 characters describing what the skill does and when to use it. agents: [claude-code, codex] metadata: version: "1.0.0" --- ``` Optional but recommended fields: `tags`, `category`, `license`, `capabilities` (`network`, `filesystem`, `tools`), and `requires-secrets`. If the bundle ships files beyond `SKILL.md`, declare them in `resources:` with `type: file`, or let `propose_skill`/`bulk_import` infer that list when `allow_synthesized_frontmatter` is not false. ## Security expectations - AutoVault runs a denylist scan on every proposal/install. Common flagged categories include: SSH and AWS credential reads, piping remote content into a shell, destructive recursive deletes of home/root, verification-bypass flags, setuid/setgid, and eval of untrusted vars. - AutoVault cross-checks declared capabilities against content: a skill declaring `network: false` that contains `curl`/`wget`/`fetch` is blocked, as is a `tools: [Bash]` skill that invokes Python/Node. - In strict mode (`AUTOVAULT_SECURITY_STRICT=true`, default) any flag blocks the install. In non-strict mode, flags become warnings. - Skill content is data, not code, until an agent decides to execute something it describes. Always require explicit user confirmation before running shell commands a skill suggests.