forge-reference
Distill one library into a pack reference for the version this repo locks: its idioms as the repo uses them, pitfalls and version notes, every claim cited to official docs or file:line. Use when a pack skill needs library facts, or corrections show the agent misusing a library.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge-reference
- metadata
- { "layer": "L3", "source": "cursor/plugins@1e5c90a:pstack/skills/typescript-best-practices/SKILL.md + EveryInc/compound-engineering-plugin@7a68002:skills/ce-plan/references/agents/framework-docs-researcher.md + mattpocock/skills@49dd158:skills/engineering/research/SKILL.md", "license": "MIT" }
- description
- Distill one library into a pack reference for the version this repo locks: its idioms as the repo uses them, pitfalls and version notes, every claim cited to official docs or file:line. Use when a pack skill needs library facts, or corrections show the agent misusing a library.
03 SKILL.md 正文
Forge a reference
A reference holds the library facts a pack skill reads on demand: short, pinned to the locked version, and cited claim by claim. Skills hold judgment; references hold facts.
Input: a library and the pack. <pack dir> is $(ven-profile path)/packs/<pack>/.
1. Pin the version
Read the resolved version from the lockfiles the profile lists (ven-profile get stack.sources). No lockfile entry for the library: stop and say so. An unpinned reference goes stale without anyone noticing.
2. Gather, in parallel
delegate two read-only worker briefs. They gather; you synthesize.
- Docs: fetch the official documentation for the locked version with your agent's web fetch tool: the docs pages for the APIs the repo calls, the changelog or release notes, and the migration guide from the version most examples assume. Check deprecations first. Primary sources only: the library's own docs, repository and changelog. Return claims, each with its URL.
- Usages: search the repo for the library's imports and calls. Return each distinct usage pattern with a count and up to three
file:lineexamples, and every usage that contradicts the docs.
3. Distill
Write <pack dir>/references/<library>.md in this shape:
# <library> <version>
Locked in <lockfile>. Docs fetched <date>.
## Idioms
| Idiom | How this repo does it | Seen at |
## Pitfalls
| Pitfall | Symptom | Do instead | Source |
## Version notes
- <what differs in this version from what most examples assume: new, deprecated, removed> (<source>)
## Sources
- <url>
- Every row cites a docs URL or
file:line. A claim with no source is cut. - Keep what changes the agent's behavior in this repo. A generic tutorial is noise the agent already knows.
- Where the repo contradicts the docs, record it as a pitfall and flag it to the user; deciding which side is right is theirs.
- One library per file, under 150 lines.
4. Check the citations
Apply citation-check: each file:line says what its row claims, and each URL contains its claim. Fix or cut every row that fails.
5. Register
- Add
{ "file": "references/<library>.md", "library", "version", "lockfile" }toreferencesin<pack dir>/pack.json. Pack audits compare that version with the lockfile to find stale references. - In each pack skill that needs the facts, fill the "Library facts" line that ven's skill template (
$(ven-profile root)/setup/assets/templates/skill/SKILL.md) provides: when to read the reference, in one line. - Bump the patch
versionin<pack dir>/pack.json.
04 同仓库更多 Skills
yeet
Take every local change green through the repo's own checks, slice it into conventional commits, push, and with --pr open a pull request on the code host. Use only when the user explicitly asks to yeet, or to commit and push everything; never on your own initiative.
write-docs
Write or update documentation from the code: gather facts, pick the shape for the reader, write it plain, and prove every command and path in it. Use when asked to document a repo, module or feature, or to bring stale docs up to date.
why
Find why code is shaped the way it is (design rationale, trade-offs, regressions, odd thresholds) from history, tickets, docs and chat, citing every claim and stating its confidence. Use for 'why does X work this way', 'why did we pick Y', or before changing code whose purpose is unclear.
verify
Prove a change works with the check that matches its type, do the read-back, and log the pass against the exact tree. Use when a change is ready to call done, before review, commit or stopping, and whenever ven-decisions end refuses an unverified tree.
unslop
Cut AI writing tells (filler, model vocabulary, metaphor nouns, hedging, formatting tics) from text while keeping every fact. Use when editing or checking any prose before it ships: docs, PR bodies, reports, skill text.
type-discipline
Apply when designing types or data shapes, reviewing a signature, or handling outside data, in any language. Make wrong states fail early: in the compiler for typed languages, in validated runtime contracts for untyped ones.