Bootstrap

Skill Provenance: Bootstrap

Add provenance tracking to an existing unversioned skill bundle. This is a one-time operation that creates the initial manifest, version headers, and changelog.

When to use

Run /skill-provenance:bootstrap when you have a skill directory that contains a SKILL.md but lacks MANIFEST.yaml. This is the entry point for adopting Skill Provenance on an existing project.

If the bundle already has a MANIFEST.yaml, use /skill-provenance:open instead.

Protocol

1. Inventory all files. Read the directory structure yourself — do not

ask the user to list files. Identify:

• SKILL.md (required — if missing, this isn't a skill bundle)
• Evals files (e.g., evals.json)
• Scripts (e.g., generate.js, validate.sh)
• Output artifacts (.docx, .pdf)
• Source material provided by the user
• Any other files present

1. Propose version numbers. Ask the user what version to assign. If

there's a handoff note, git history, or other context suggesting prior versions, propose a number based on that history. Default to 1.0.0 for the bundle and 1 for individual files if no history exists.

1. Add internal version headers to files that can safely carry YAML

frontmatter. Use the metadata block pattern for SKILL.md:

``yaml --- name: skill-name description: What the skill does. metadata: skill_bundle: skill-name file_role: skill version: 1 version_date: 2026-04-11 previous_version: null change_summary: Initial versioned release. --- ``

For files that cannot safely carry frontmatter (.json, .sh, binaries), the manifest tracks their version — no modification needed.

1. Determine frontmatter mode. Ask the user about their target

platforms:

• If targeting only Claude Code / agentskills.io-compatible clients:

use frontmatter_mode: metadata (includes the metadata block).

• If targeting Codex, Gemini CLI, or other strict platforms: use

frontmatter_mode: minimal (name + description only in SKILL.md; manifest is the sole version record).

• If unsure: default to metadata — it's more expressive and can

always be stripped later with a packaging script.

1. Generate MANIFEST.yaml. Include:

• bundle, bundle_version, bundle_date, description
• compatibility section based on user's target platforms
• files list with path, role, version, hash (SHA-256), note
• Leave deployments empty unless the user mentions existing installs.

1. Generate CHANGELOG.md. Create a single entry summarizing known

history. If the user has context about prior changes, incorporate it. Otherwise:

```markdown # Changelog

## 1.0.0 — 2026-04-11

• Initial versioned release. All files inventoried and hashed.
• SKILL.md: [brief description of current state]
• evals.json: [N evals covering X]

```

1. Deliver the versioned bundle. Provide all new and modified files.

Summarize what was created and any decisions for the user to confirm.

File roles

Assign these roles in the manifest based on file type:

| Role | Files | |------|-------| | skill | SKILL.md | | evals | evals.json, evals-*.json | | script | .js, .py, .sh scripts | | output | .docx, .pdf rendered artifacts | | handoff | handoff notes | | source | user-provided material (tracked, not versioned) | | reference | documentation in references/ | | asset | templates, images, fonts in assets/ |

Conventions referenced

• Version identity lives inside files when their format allows it,

and always in the manifest.

• MANIFEST.yaml is not self-listed. It tracks other files only.
• Per-file versions are integers. Bundle version is semver.
• Hashes are SHA-256 of file contents.
• Filenames never contain version numbers. Version lives in metadata

and the manifest, not in SKILL_v5.md.

For the full spec: https://skillprovenance.dev

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snapsynapse
• Source: snapsynapse/skill-provenance
• License: MIT
• Homepage: https://skillprovenance.dev/

Install and usage instructions live in the source repository linked above.