🔄 skills-check-updates

npm-check-updates for agent skills. Reads the skills-lock.json written by the skills CLI, compares every skill with its GitHub source and reports what changed - without touching anything unless you ask.

Watch the demo as a video (MP4).

Why

npx skills check is an alias of npx skills update: it reinstalls right away, there is no read-only preview. It also silently overwrites local edits, and it cannot update skills whose lock entry has no skillPath (installed by older CLI versions).

📦 Installation

Install globally to use skills-check-updates or the shorter scu:

npm install -g skills-check-updates

Or run without installing globally:

npx skills-check-updates

🚀 Usage

scu            # report only
scu -u         # update outdated skills, merging your local edits
scu -u --force # overwrite local edits instead of merging
scu tdd shadcn # check selected skills
scu 'grill*'   # names accept * wildcards
scu --details  # commits, changed files and compare links
scu --json     # machine-readable report
scu --scan     # list security findings each update adds (needs SkillSpector)
scu -u --scan  # update, but hold back updates that add HIGH or CRITICAL findings
scu --ui       # interactive map of locally installed skills (opens your browser)

Exploring your skills: --ui

scu --ui opens an offline, interactive mind map: project → source repositories → skills. Search by skill or source, fold branches, zoom, and select a skill to read its local SKILL.md, version and file count.

scu --ui
scu --ui --from 'vercel-labs/*'
scu --ui --skip 'internal-*'
scu --ui 'review*'

The map reads the project's skills-lock.json and local .agents/skills / .claude/skills folders. Missing or unreadable skills stay visible with a separate label. Global skills and skills outside the lock are not included. This mode does not check upstream updates and cannot be combined with update or report options.

The map is delivered from memory through a one-time URL on 127.0.0.1, using a random access token and Cache-Control: no-store. No HTML snapshot is written to disk. The local server closes after delivering the page, or after five minutes if it is not opened. The loaded map keeps working without the server, but reloading the tab does not; run the command again to refresh the map.

If your browser does not open automatically, open the printed URL within five minutes. The URL works only in a browser on the machine running scu, so it is not reachable from another computer, for example over SSH.

The page contains the full local skill instructions, so do not share or manually save it if they contain secrets.

Choosing skills

scu --skip shadcn                   # leave out a skill
scu --skip 'grill*,tdd'             # repeatable, comma separated, wildcards
scu --from mattpocock/skills        # only skills installed from this repo
scu --from 'vercel-labs/*'          # any repo of an owner

A misspelled exact name shows up as an error row instead of being ignored.

Letting changes settle: --min-age

A skill is a set of instructions your agent follows with access to your tools, so a bad or hijacked upstream commit lands straight in its prompt. --min-age holds an update back until the newest change to the skill folder is old enough for problems to surface:

scu --min-age 7d      # also 7 (days), 12h, 30m
scu -u --min-age 7d   # held updates are skipped, even with --force

 shadcn  update available, held until 2026-10-28  https://github.com/shadcn/ui/tree/HEAD/skills/shadcn

The whole update waits for the newest change - installing an older, already settled commit would pin the lock entry to that commit and stop future checks from seeing anything newer.

Scanning updates: --scan

--scan runs SkillSpector, NVIDIA's security scanner for agent skills, on the installed copy and on the upstream version of every update, and lists only the findings the update adds:

uv tool install git+https://github.com/NVIDIA/[email protected]   # once
scu --scan

 hallmark  update available  https://github.com/nutlope/hallmark/tree/HEAD/skills/hallmark
     scan       4 new findings
                HIGH     P2    references/assets.md:23  Hidden Instructions  <!-- TODO: Replace with real <thing>, target size: <WxH> -->
                HIGH     P1    SKILL.md:186  Instruction Override  override system
                HIGH     PE3   SKILL.md:186  Credential Access  access secrets
                MEDIUM   E1    references/assets.md:122  External Transmission  https://api.svgl.app/
 tdd       update available  https://github.com/mattpocock/skills/tree/HEAD/skills/engineering/tdd
     scan       no new findings

• A finding is a hint, not a verdict. Static matching also flags harmless text, such as an HTML comment in an example (hidden instructions) or /etc/passwd in a test fixture (credential access), so read the matched text. An update without new findings is not proven safe.
• Findings are matched by rule and file, so a finding that only moved to another line is not new. AE1, a referenced file the scanner could not fully parse, is left out. SkillSpector's overall risk score is not shown: it rates the whole skill, so long-standing findings would hide what the update changed.
• SkillSpector runs with --no-llm, so no skill content is sent to a model provider. Its dependency check can query OSV.dev.
• Both versions are written to temporary folders, which are removed after the scan. Scans run in parallel; one takes a few seconds, or about a minute for a skill with a hundred files.
• With --json, each scanned skill has a scan field. A failed scan is shown on the skill and makes scu exit with 1.

With -u, an update that adds a HIGH or CRITICAL finding, or whose scan failed, is held back - even with --force - and scu exits with 1. MEDIUM and LOW findings are listed but do not hold an update. After reviewing a held update, install it with scu -u <skill> without --scan.

scu -u --scan --min-age 7d

 hallmark  update available, held by scan  https://github.com/nutlope/hallmark/tree/HEAD/skills/hallmark
     scan       4 new findings
                ...

Like --min-age, the scan covers updates of installed skills: a skill that is in the lock but not installed is installed without a scan.

CI: --exit-code

scu --exit-code --min-age 7d

| Exit code | Meaning | | --- | --- | | 0 | nothing to update | | 1 | an error (network, lock file, failed upgrade or scan) or an update skipped because local and upstream changes overlap or the scan held it back | | 2 | updates are available |

Without --exit-code a successful check always exits with 0.

--details (-d) expands every row:

 tdd  update available
     installed  3216582  2026-08-19  Remove all em-dashes from the repo
     latest     3f59913  2026-10-07  tdd: note what each proposed seam catches and misses (#1192)
     behind     2 commits
     hash       e753a5da7529 → daf55026f456
     changes    ~ SKILL.md
     compare    https://github.com/mattpocock/skills/compare/321658273cb1...3f599139104d
     source     https://github.com/mattpocock/skills/tree/HEAD/skills/engineering/tdd

 resolving-merge-conflicts  not found upstream
     removed    daa01d8  2026-09-24  Remove resolving-merge-conflicts
     source     https://github.com/mattpocock/skills

• installed is the upstream commit whose folder content matches the local copy (searched in the last 20 commits that touched the folder), latest is the newest of them.
• behind counts commits that touched the skill folder, not the whole repo.
• version appears when SKILL.md declares one in its frontmatter - it is informational only, authors rarely bump it.
• changes lists files added (+), modified (~) and removed (-) upstream relative to the local copy.
• With skill names given, up-to-date skills are listed too: scu -d tdd.

Details cost one extra GitHub API request per skill plus one per older commit inspected, so a token is strongly recommended.

| Status | Meaning | -u | | --- | --- | --- | | update available | upstream changed, local copy untouched | reinstalls | | local changes | local copy edited, upstream unchanged | only with --force | | local changes + update available | both changed | merges, skips when the changes overlap; --force overwrites | | up to date, lock needs skillPath | content current, but the lock has no or a moved skillPath | reinstalls to record the path | | not installed | in the lock, missing on disk | reinstalls | | not found upstream | the skill was removed from its repo | - |

Local edits

-u keeps your edits to an installed skill. When upstream changed the same skill, scu finds the upstream version you installed - the commit whose folder reproduces the lock's computedHash - and merges file by file with git merge-file:

• Changes to different files, or to different lines of the same file, are combined.
• Changes to the same lines, a file deleted on one side and edited on the other, or binary files changed on both sides skip the update for that skill. Nothing is touched and -u exits with 1.
• --force skips merging and installs the upstream version over your edits.

The installed version must be among the last 20 commits that touched the skill folder, otherwise the update is skipped as well. Merging needs git on the PATH.

How it works

• The lock's computedHash is a SHA-256 over every file in the skill's source folder. The tool rebuilds that hash from the current upstream tree and compares.
• Files whose git blob sha matches a local file are not downloaded - a typical run needs one GitHub API request per source repo.
• When the lock hash cannot prove the local copy is untouched (hashes written by older CLI versions do not always reproduce), the local copy is compared with the last 20 upstream versions of the folder before it is reported as edited.
• Lock entries without skillPath, or with a path that no longer exists, are located by their SKILL.md frontmatter name.
• -u runs npx [email protected] add <source>/<folder> --skill <name> -y per skill, the same command npx skills update uses, so skills land in the same agent folders and the lock is updated by the official CLI. The version is pinned to the one whose hashing and naming rules scu mirrors, and is bumped deliberately after checking a new release. For a merged skill the merged files then replace the installer's copy, and the new upstream version in the lock becomes the base of the next merge.
• The installer downloads the skill again, so after each install scu checks that the lock records the version it checked. If upstream changed in between, the skill's previous files and the lock are restored and the update is skipped - --min-age and merges never apply to a version scu has not seen. Skills that were not installed have no previous version and are not checked.

GitHub requests use GITHUB_TOKEN, GH_TOKEN or gh auth token when available; without a token the API allows 60 requests per hour.

Limitations

• GitHub sources only (sourceType: "github"). Other sources are reported as unsupported.
• Project lock only (skills-lock.json), not the global ~/.agents/.skill-lock.json.
• Skill names must start with an ASCII letter or digit and contain only ASCII letters, digits, spaces, dots, underscores, colons or hyphens. Installed folders use the same name normalization as the skills CLI.
• .agents, .claude and their skills folders must be real directories inside the project. Individual skill symlinks are accepted when they resolve inside the project.
• Upstream skill folders containing #, @, :, backslashes or terminal control characters are rejected because they cannot be passed literally to the installer.

Releases

See CHANGELOG.md for the release history and GitHub Releases for versioned release notes.

🛠️ Development

pnpm install
pnpm test       # node --test, runs TypeScript directly (Node >= 22.18)
pnpm typecheck
pnpm build