skill-provenance

Version tracking for Agent Skills bundles and their associated files across sessions, surfaces, and platforms. Use when creating, editing, versioning, validating, packaging, or handing off a skill bundle; when checking or updating MANIFEST.yaml, CHANGELOG.md, hashes, stale evals, or frontmatter mode; and when keeping version identity with the bundle instead of filenames. Compatible with the agentskills.io open standard.

# Skill Provenance

## The Problem This Solves

Skill projects move between sessions, surfaces (Chat, IDE, CLI, Cowork),
platforms (Claude, Gemini CLI, Codex, Copilot), and local storage
(Obsidian, working directories, git repos). Version identity gets lost
when it lives only in filenames. A file renamed from `SKILL_v4.md` to
`SKILL_v5.md` with no internal record of what changed creates ambiguity.

This skill establishes three conventions that prevent that:

1. Version identity lives inside files when their format allows it, and
   always in the manifest.
2. A recent changelog travels with the skill bundle, while longer history
   can live in the source repo.
3. A manifest lists all files in the bundle so any session can verify completeness.

## What Gets Versioned

A skill bundle is a SKILL.md plus all associated files. Typical contents:

- SKILL.md (the skill definition)
- evals.json (evaluation suite)
- Generation scripts (e.g., generate.js, generate.py)
- Output artifacts (.docx, .pdf) produced by evals or real use
- Handoff notes
- Source material provided by the user (tracked but not versioned)

The skill itself (SKILL.md) and evals are the primary versioned artifacts.
Scripts and outputs are tracked by the manifest but version with the bundle
rather than independently. Handoff notes are optional convenience artifacts.


## Internal Version Header

Files that can safely carry YAML frontmatter begin with a YAML frontmatter
block (or extend an existing one) containing these fields:

```yaml
---
skill_bundle: my-skill            # bundle name, stable across versions
file_role: skill                  # skill | evals | script | output | handoff
version: 5                        # integer, monotonically increasing
version_date: 2026-02-10          # date of this version
previous_version: 4               # null for v1
change_summary: >
  Rewrote Phase 5 layout rules. Removed per-section page breaks.
  Added content flow check. Added validation checklist as standalone final page.
---
```

### Rules

**version** is an integer for per-file tracking. It counts revisions to
that specific file within the bundle. The bundle-level version
(`bundle_version` in MANIFEST.yaml) uses semver.

**change_summary** is required for every version after v1. One to three
sentences. It must describe what changed, not just that something changed.

**previous_version** creates a chain. Any session can trace the lineage.

**file_role** values:
- `skill` — the SKILL.md itself
- `evals` — the evals.json file
- `script` — generation scripts, utility scripts
- `output` — rendered artifacts (.docx, .pdf)
- `handoff` — session handoff notes
- `source` — user-provided source material (tracked, not versioned)
- `reference` — documentation in references/ loaded on demand
- `asset` — templates, images, fonts in assets/ used in output
- `agents` — platform UI metadata (e.g., Codex's agents/openai.yaml)

For files that cannot safely carry YAML frontmatter (binary files and
strict-format files such as `.json` or executable `.sh`), the manifest
tracks their version and its `version` field is authoritative.

**SKILL.md frontmatter constraint:** The Agent Skills open standard
(agentskills.io) requires `name` and `description`. Different platforms
enforce different rules about additional fields:

| Platform | Allowed SKILL.md frontmatter |
|---|---|
| **agentskills.io spec** | `name`, `description`, `license`, `metadata`, `compatibility`, `allowed-tools` |
| **Claude Chat / Settings UI** | Same as spec. Claude's settings importer rejects unrecognized fields. |
| **Claude Code** | Spec fields plus extensions: `disable-model-invocation`, `user-invocable`, `context`, `agent`, `model`, `hooks`, `argument-hint`. These are Claude Code features, not part of the base spec. |
| **Claude API** | Skills uploaded via `/v1/skills`. Validates `name` and `description`. Supports `metadata`. |
| **Gemini CLI (Google)** | `name` and `description` only. Extra fields not officially supported. |
| **Codex (OpenAI)** | `name` and `description` only. Extra fields rejected. |
| **GitHub Copilot / VS Code** | Follows agentskills.io spec. |
| **Cursor, Roo Code, Junie, others** | Follows agentskills.io spec. See agentskills.io for the full adopter list (30+). |

For maximum portability, keep SKILL.md frontmatter to `name` and
`description` only. If the canonical bundle needs attribution or visible
SKILL.md metadata, use the spec's `metadata` field there and generate a
derived minimal copy for strict platforms:

```yaml
---
name: my-skill
description: What the skill does.
metadata:
  skill_bundle: my-skill
  file_role: skill
  version: 3
  version_date: 2026-02-10
  previous_version: 2
  change_summary: >
    Added Phase 6 validation step.
---
```

If targeting Codex or other strict platforms directly, omit `metadata`
from SKILL.md entirely. The manifest tracks SKILL.md's version either
way, so no version information is lost.

**Note on spec support:** The agentskills.io spec formally supports
`metadata` as an arbitrary key-value map, with `version` shown as an
example use. This means the `metadata.version` approach is now
spec-blessed, not a Claude-only extension. However, the spec's version
is a static label — it does not address staleness tracking, changelogs,
or bundle integrity. Prefer manifest-based tracking as the default and
use `metadata` only when you need version info visible in the file
itself.

## Manifest

The manifest is a YAML file named `MANIFEST.yaml` at the root of the skill
bundle directory — the same level as `SKILL.md`. When the bundle is
packaged as a `.skill` ZIP, the manifest lives inside the ZIP. It is the
single source of truth for what the bundle contains.

```yaml
bundle: my-skill
bundle_version: 5.1.0
bundle_date: 2026-02-10
description: >
  Skill for generating professional documents from source material
  and user briefs. Handles research, structuring, and formatting.

compatibility:
  designed_for:
    surfaces:
      - chat
      - cli
      - ide
    capabilities:
      - minimal SKILL.md frontmatter
      - local filesystem access
      - optional git workflow
  tested_on:
    - platform: Anthropic Claude
      model: Claude Opus 4.6
      surface: Chat
      status: pass
      date: 2026-02-10
    - platform: Anthropic Claude
      model: Claude Sonnet 4.5
      surface: Chat
      status: partial
      date: 2026-02-09
      notes: Misses staleness detection on complex bundles
  spec_version: agentskills.io/1.0
  frontmatter_mode: minimal
    # minimal = name + description only (Codex, Gemini CLI, max portability)
    # metadata = includes metadata block (any platform supporting the spec's metadata field)

dependencies: []
  # List skill names this bundle depends on. Omit or leave empty if none.

deployments:
  api:
    version: 1759178010641129
    workspace: docs-prod
  claude:
    scope: user
  perplexity:
    package_format: zip

files:
  - path: SKILL.md
    role: skill
    version: 5
    hash: sha256:abc123...
    note: Canonical skill definition

  - path: evals.json
    role: evals
    version: 3
    hash: sha256:def456...
    note: 7 evals including real-content synthesis

  - path: scripts/generate.js
    role: script
    version: 4
    hash: sha256:ghi789...
    note: Generation script for eval 3

  - path: outputs/eval3-output.pdf
    role: output
    version: 4
    hash: sha256:jkl012...
    note: Rendered eval 3 output, 10 pages, validated

  - path: sources/article-1.md
    role: source
    version: null
    hash: sha256:pqr678...
    note: Source article 1 (published)
```

### Rules

**bundle_version** uses semver (MAJOR.MINOR.PATCH). Bump MAJOR for
breaking changes to the skill's model or interface, MINOR for new
features or capabilities, PATCH for fixes and documentation updates.
Per-file `version` fields remain integers — they are revision counters,
not release identifiers.

**hash** is sha256 of the file contents. This is how a new session verifies
that the fi