provenance-tracking

Files (4)

• SKILL.md
• CHANGELOG.md · references/
• SOURCE-TEMPLATE.md · references/
• provenance-check.sh · scripts/

SKILL.md (first lines)

# Provenance Tracking

## Overview

Every skill installed from a remote source must carry **source provenance** so the agent can
trace where it came from, detect when upstream changes, and decide how to integrate those
changes. This skill enforces three invariants:

1. **references/SOURCE.md exists** — cites the upstream source, ref, and install date.
2. **Freshness is checkable** — a `scripts/check-upstream.sh` can compare local vs upstream.
3. **Upstream content is preserved** — an `assets/` folder holds the canonical upstream source.

## When to Use

- Immediately after installing a skill from a remote repo (`just install`, `npx skills add`)
- When adapting a public methodology/gist into a local skill (like VDD/VSDD)
- During `just sync` to audit all remote skills for provenance compliance
- When the user asks "are any skills out of date?" or "check for updates"
- During periodic maintenance / skill audits
- When reviewing or modifying a skill that was installed from elsewhere

**Don't use when:**

- Authoring a new skill from scratch (no upstream source)
- Editing a skill that already has valid provenance and is up-to-date

## Skill Categories

Remote skills fall into two categories, each with different provenance requirements:

### Category A: Modified Third-Party Skills

The local skill **adapts** an upstream source (gist, repo, blog post) with local
modifications — additional instructions, project-specific patterns, self-learning protocol,
etc. The upstream is the methodology reference; the local SKILL.md is the working skill.

**Examples:** `vdd/` (adapts gist `45c95ebf...`), `vsdd/` (adapts gist `d8d3bc3e...`)

**Required structure:**

```
skill-name/
├── SKILL.md                    # Modified skill with local adaptations
├── assets/
│   └── upstream.md             # Raw upstream source (canonical reference)
├── scripts/
│   └── check-upstream.sh       # Fetches upstream, compares, updates assets/
└── references/
    ├── SOURCE.md               # Provenance metadata
    ├── CHANGELOG.md            # Skill update history
    └── LESSONS_LEARNED.md      # Evolving patterns (if self-learning)
```

**Source frontmatter pattern:**

```yaml
source:
  gist: https://gist.github.com/user/id
  gist_id: id
  fetched_at: "2026-01-01T00:00:00Z"
```

Or for a repo-based upstream:

```yaml
source:
  repo: https://github.com/org/repo
  ref: main
  path: subpath
  fetched_at: "2026-01-01T00:00:00Z"
```

### Category B: Unmodified Third-Party Skills

Skills installed verbatim from a remote repo via `npx skills add`, `just install`, or
manual copy. No local modifications — the SKILL.md is the upstream SKILL.md.

**Examples:** `qa/`, `write-a-prd/`, `grill-me/` (installed from mattpocock/skills)

**Required structure:**

```
skill-name/
├── SKILL.md                    # Unmodified upstream skill
├── assets/
│   └── upstream-SKILL.md       # Latest upstream SKILL.md for diff comparison
├── scripts/
│   └── check-upstream.sh       # Fetches upstream, compares, offers pull
└── references/
    └── SOURCE.md               # Provenance metadata
```

**Source frontmatter pattern:**

```yaml
source:
  repo: https://github.com/org/repo
  ref: main
  path: skill-name
```

## Instructions

### Step 1: Post-Install Provenance Gate

After any remote skill install, verify and create provenance metadata:

```
GIVEN: A skill directory exists at skills/<name>/
  AND: An entry exists in skills-lock.json for <name>

VERIFY:
  □ skills/<name>/references/ directory exists
  □ skills/<name>/references/SOURCE.md exists and is non-empty
  □ SOURCE.md contains: source URL, ref/branch, remote path, install date
  □ SKILL.md frontmatter has `source:` block
  □ skills/<name>/scripts/check-upstream.sh exists
  □ skills/<name>/assets/ directory exists

From kvithayathil/agent-resources, Apache-2.0.

More from kvithayathil/agent-resources