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
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
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.
Add internal version headers to files that can safely carry YAML
frontmatter. Use the metadata block pattern for SKILL.md:
---
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.
Determine frontmatter mode. Maintain the canonical source in
frontmatter_mode: metadata when richer provenance is useful. For Codex,
Gemini CLI, or another strict loader, derive a minimal-frontmatter install
copy rather than weakening the canonical source in place. If the user
explicitly wants one strict-only bundle, minimal is valid.
Generate MANIFEST.yaml. Include:
bundle, bundle_version, bundle_date, description
compatibility section based on user's target platforms
- Exactly one top-level
files: list using unquoted normalized relative
paths and a sha256: hash or explicit hash: null for every entry
- Leave
deployments empty unless the user mentions existing installs.
Generate CHANGELOG.md. Create a single entry summarizing known
history. If the user has context about prior changes, incorporate it.
Otherwise:
# 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]
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
1---2name: bootstrap3description: >4 Add version tracking to an existing unversioned skill bundle. Use when5 you have a skill project with SKILL.md but no MANIFEST.yaml, no version6 headers, and no changelog. Creates the initial manifest, adds version7 metadata to files, and generates the first changelog entry. Triggers on:8 "bootstrap this skill", "add versioning", "start tracking versions",9 "create a manifest", "this skill has no versioning".10license: MIT11metadata:12 source: https://skillmd.com/skills/snapsynapse/bootstrap13---1415# Skill Provenance: Bootstrap1617Add provenance tracking to an existing unversioned skill bundle. This is18a one-time operation that creates the initial manifest, version headers,19and changelog.2021## When to use2223Run `/skill-provenance:bootstrap` when you have a skill directory that24contains a `SKILL.md` but lacks `MANIFEST.yaml`. This is the entry point25for adopting Skill Provenance on an existing project.2627If the bundle already has a `MANIFEST.yaml`, use `/skill-provenance:open`28instead.2930## Protocol31321. **Inventory all files.** Read the directory structure yourself — do not33 ask the user to list files. Identify:34 - `SKILL.md` (required — if missing, this isn't a skill bundle)35 - Evals files (e.g., `evals.json`)36 - Scripts (e.g., `generate.js`, `validate.sh`)37 - Output artifacts (`.docx`, `.pdf`)38 - Source material provided by the user39 - Any other files present40412. **Propose version numbers.** Ask the user what version to assign. If42 there's a handoff note, git history, or other context suggesting prior43 versions, propose a number based on that history. Default to `1.0.0`44 for the bundle and `1` for individual files if no history exists.45463. **Add internal version headers** to files that can safely carry YAML47 frontmatter. Use the `metadata` block pattern for SKILL.md:4849 ```yaml50 ---51 name: skill-name52 description: What the skill does.53 metadata:54 skill_bundle: skill-name55 file_role: skill56 version: 157 version_date: 2026-04-1158 previous_version: null59 change_summary: Initial versioned release.60 ---61 ```6263 For files that cannot safely carry frontmatter (`.json`, `.sh`,64 binaries), the manifest tracks their version — no modification needed.65664. **Determine frontmatter mode.** Maintain the canonical source in67 `frontmatter_mode: metadata` when richer provenance is useful. For Codex,68 Gemini CLI, or another strict loader, derive a minimal-frontmatter install69 copy rather than weakening the canonical source in place. If the user70 explicitly wants one strict-only bundle, `minimal` is valid.71725. **Generate MANIFEST.yaml.** Include:73 - `bundle`, `bundle_version`, `bundle_date`, `description`74 - `compatibility` section based on user's target platforms75 - Exactly one top-level `files:` list using unquoted normalized relative76 paths and a `sha256:` hash or explicit `hash: null` for every entry77 - Leave `deployments` empty unless the user mentions existing installs.78796. **Generate CHANGELOG.md.** Create a single entry summarizing known80 history. If the user has context about prior changes, incorporate it.81 Otherwise:8283 ```markdown84 # Changelog8586 ## 1.0.0 — 2026-04-1187 - Initial versioned release. All files inventoried and hashed.88 - SKILL.md: [brief description of current state]89 - evals.json: [N evals covering X]90 ```91927. **Deliver the versioned bundle.** Provide all new and modified files.93 Summarize what was created and any decisions for the user to confirm.9495## File roles9697Assign these roles in the manifest based on file type:9899| Role | Files |100|------|-------|101| `skill` | SKILL.md |102| `evals` | evals.json, evals-*.json |103| `script` | .js, .py, .sh scripts |104| `output` | .docx, .pdf rendered artifacts |105| `handoff` | handoff notes |106| `source` | user-provided material (tracked, not versioned) |107| `reference` | documentation in references/ |108| `asset` | templates, images, fonts in assets/ |109110## Conventions referenced111112- **Version identity lives inside files** when their format allows it,113 and always in the manifest.114- **MANIFEST.yaml is not self-listed.** It tracks other files only.115- **Per-file versions are integers.** Bundle version is semver.116- **Hashes are SHA-256** of file contents.117- **Filenames never contain version numbers.** Version lives in metadata118 and the manifest, not in `SKILL_v5.md`.119120For the full spec: https://skillprovenance.dev