AGENT SKILL

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:line examples, 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

  1. Add { "file": "references/<library>.md", "library", "version", "lockfile" } to references in <pack dir>/pack.json. Pack audits compare that version with the lockfile to find stale references.
  2. 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.
  3. Bump the patch version in <pack dir>/pack.json.

04 同仓库更多 Skills

Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0