---
title: Upstream skills
description: The method inside each skill comes from vendored upstream skills, pinned by content hash and never edited by hand.
sidebar:
  order: 7
---

## Why vendor

The factory skills are thin, owned wrappers. The method they apply comes
from skills by Matt Pocock, the Cursor pstack team, Addy Osmani, and
CodeRabbit, plus Drew's own poly-crap and lawbook skills. Those files are
copied verbatim under `upstream/` so a skill can load them with a stable
path, and pinned so a change upstream is a reviewed PR here rather than a
silent drift.

Each wrapper's `Load` section lists the upstream files it reads. Its
`Translate` section says what changes: an upstream command that does not
exist here, a label that becomes the `factory` label, a scratch directory
that becomes `<spec_dir>/<slug>/`. Its `Factory rules` section adds the
constraints that make the skills compose.

## The manifest

`upstream/upstream.json` lists every vendored entry with its repository,
ref, resolved commit, paths, license, and a content hash. Vendored files
are never edited by hand. A lawbook rule requires every loop skill to
load at least one file under `upstream/`.

## Commands

```bash
uv run --script scripts/sync-upstream.py check
```

```bash
uv run --script scripts/sync-upstream.py diff mattpocock-skills/tdd
```

```bash
uv run --script scripts/sync-upstream.py update mattpocock-skills/tdd --ref v1.4.0
```

```bash
uv run --script scripts/sync-upstream.py verify
```

- `check` reports entries behind their ref and newer tags.
- `diff` shows the upstream change since the pinned commit.
- `update` replaces the copy, re-pins, and regenerates
  `THIRD_PARTY_NOTICES.md`. It refuses to run over a hand-edited copy.
- `verify` confirms the copies match the manifest. It runs in CI.

## The weekly PR

A scheduled workflow runs `check` every Monday. When upstream moved, it
runs `update` for the entries behind and opens a PR with the diff in the
body and a reminder to re-read the Translate section of each affected
wrapper before merging.

## Licenses

Vendored files keep their own licenses. `THIRD_PARTY_NOTICES.md` lists
every entry and is regenerated by `update`.