Copied skills rarely receive upstream fixes. Skill Constellations (Seddik, arXiv:2610.11169) cites the GitSkills finding that half of all SKILL.md files on GitHub are copies of another file, and reports that only 11.1% of changes to a clone group reach every copy. An installed SKILL.md records nothing about its source, so neither people nor tools can tell whether a copy is stale.
What it does. With --record-lineage, skills add resolves the cloned ref to a full commit SHA and writes two keys under metadata in each installed SKILL.md:
metadata:
derived-from: "https://github.com/<owner>/<repo>/tree/<sha>/<skill path>"
derived-from-hash: "sha256:<hex>"The hash uses the normalisation of the reference implementation, checked against it on fixtures. Other frontmatter keys and the body are untouched; reinstalling overwrites the keys. Sources without a commit (local paths, downloads) install normally with a warning. The flag clones instead of using the blob fast path, which has no commit SHA.
Why opt-in. It edits installed files and the convention is still a proposal (agentskills discussion #620). Default behaviour is unchanged. Related: #1391.
How to test
pnpm test src/lineage.test.ts tests/record-lineage.test.ts
mkdir /tmp/try && cd /tmp/try && mkdir .claude
node <repo>/src/cli.ts add vercel-labs/skills --skill find-skills -a claude-code -y --record-lineage
head -6 .claude/skills/find-skills/SKILL.md