| name | refresh-library |
| description | Refresh a stale library dossier in the animation-library corpus. Use this skill when the user says "the <lib> dossier is out of date", "refresh <lib>", "update <lib> to the latest version", "re-verify <lib>", or when invoked directly as `/animation-library:refresh-library <slug>`. Also invoked automatically by the sibling `pick-library` skill's Workflow Step 0 when its freshness check detects a version mismatch between a dossier's recorded `Version researched` and the library's current npm version. Fetches current npm version and release notes, dispatches a subagent to identify changes between the dossier's version and latest, applies the resulting edits across dossier.md / references/*.md / COMPARISON.md, and updates the sources.md retrieval date. Do NOT use for creating a new library entry (that's `scaffold-library`) or for answering "how do I use <lib>" questions (that's `pick-library`). |
| argument-hint | <library-slug> |
| allowed-tools | Read, Edit, Grep, Glob, Bash, WebFetch, Agent |
Refresh a library dossier
This skill reconciles an existing dossier in ../pick-library/ with the library's current upstream state. It's invoked in two ways:
- Direct:
/animation-library:refresh-library <slug> — user explicitly asks to refresh a slug they name.
- Automatic: the sibling
pick-library skill detects a version mismatch during its freshness check (Workflow Step 0) and hands off to this skill.
If invoked with $ARGUMENTS, the first positional arg is the library slug.
Workflow
- Locate the dossier. Search
../pick-library/motion/<slug>/ and ../pick-library/rendering/<slug>/. If neither exists, tell the user and suggest scaffold-library instead.
- Read the current state:
dossier.md — extract name (from frontmatter), the Version researched value (format: X.Y.Z (released YYYY-MM-DD)), and remember which category the dossier lives in.references/sources.md — extract the current retrieval date (top-line All sources retrieved YYYY-MM-DD.) and scan for the upstream npm / docs / repo URLs.references/overview.md — note the version-history table rows.
- Resolve the npm package name. Usually it's the slug. When it isn't, it's documented in
dossier.md's Framework support row or sources.md's first npm registry link. For non-npm entries (e.g. waapi, view-transitions-api) where Version researched is "Web standard (no SPDX)" or similar, skip to step 9 and report "not applicable — browser-native API, no npm version to compare against."
- Fetch current version + release date:
curl -s https://registry.npmjs.org/<package>/latest | jq -r '.version + " " + (.time.modified // .time.created)'
(Use WebFetch with the same URL if Bash/curl is unavailable.)
- Compare. If the current version equals the dossier's
Version researched X.Y.Z, report "<slug> is current at <version> — no changes applied." and exit. No edits.
- On mismatch, dispatch a research subagent (Explore for read-only verification followed by general-purpose for write-planning, or just general-purpose). The prompt must include:
- Library slug, npm package name, category.
- Old version from dossier (
X.Y.Z) and new version from npm.
- Verbatim current contents of
dossier.md's Quick facts, references/overview.md's Version history table, references/api.md, references/differentiators.md, references/drawbacks.md, references/sources.md.
- Instruction to fetch release notes / changelog / GitHub releases covering every intermediate version, then return a structured diff listing:
- Exact
dossier.md Quick-facts cells to replace (version, bundle size if changed, framework support if changed, runtime if changed).
- New rows to append to
overview.md's Version history table.
- New/removed/renamed APIs that affect
api.md.
- Any differentiator or drawback claims invalidated by the new release.
- Updated bundle-size figures with the source annotation (
(bundlephobia) / (readme) / (measured)).
- New source URLs for
sources.md.
- Explicit ask to not invent values; flag anything unverifiable.
- Apply the edits with Edit calls, targeting each file the subagent flagged. One Edit per distinct change; don't batch unrelated changes into a single Edit.
- Update retrieval date. Rewrite
references/sources.md's top line to All sources retrieved YYYY-MM-DD. using today's date.
- Propagate to COMPARISON.md. If any cell the subagent changed maps to a
COMPARISON.md column (version string, bundle size, license, framework support, maintenance posture), update that library's row in the relevant matrix (Part 1a motion / Part 1b rendering). Leave cluster writeups in Part 2 alone unless the change is structural (e.g. ownership change, deprecation) — those are narrative and need human review.
- Report. Summarise for the user:
- Version delta (
X.Y.Z → A.B.C).
- Files changed (bullet list).
- Anything the subagent flagged for human review (e.g. "API surface reshape too large to auto-apply — see
references/api.md notes").
- Suggested follow-up: the user should read the diff before committing.
Principles
- Citation discipline stays in force. Every new or updated fact must trace back to a primary source the subagent retrieved today. Update
sources.md with new URLs; don't drop old ones unless the target 404'd (note that case too).
- Preserve retrieval-date honesty. The retrieval date on
sources.md is the date of this refresh, not the original research. The dossier's version history table (in overview.md) retains the full timeline.
- Don't over-edit. Refresh changes that are factually outdated (version numbers, bundle sizes, API names). Don't rewrite prose that's still accurate — preserve voice and structure from the original author.
- Non-semver entries are exempt. WAAPI / view-transitions-api and similar browser-native entries have no npm version; skip step 4 and exit with "not applicable".
- Major version jumps may need human oversight. If the subagent reports structural API changes (e.g. v3 → v4 with a breaking-change list), apply the easy parts (Quick facts, version history) and flag the rest for the user to review and write by hand — don't silently paper over a breaking-change migration.
