dfinity / dfinity/icskills

Add a version-coherence guard so skills cannot contradict each other on dependency versions

Open
#366 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

generated
Dominant language
Python
Stars
35
Forks
13
Avg merge
19h 10m
Merged PRs (30d)
22

Description

Version drift between skills is currently found only by manual audit. #297, #298 and #301 are all instances of the same missing check, and #364 is a case where a skill's install command contradicted its own stated prerequisites for months without anything noticing.

Evidence: a ~40-line extractor finds this today

Regexing version constraints out of skills/**/*.md and grouping by value:

CONFLICT  ic-cdk (cargo)
    0.19   <- canister-security, certified-variables, ckbtc, https-outcalls,
              icrc-ledger, multi-canister, sns
    0.20   <- evm-rpc, vetkeys

CONFLICT  mo:core
    2.1.0  <- multi-canister
    2.5.0  <- migrating-motoko-actors, troubleshooting-motoko-migrations, writing-motoko

CONFLICT  moc (toolchain)
    0.14.2 <- cloud-engine-canisters
    1.6.0  <- internet-identity
    1.7.0  <- mops-cli, stable-memory, writing-motoko
    1.11.2 <- migrating-motoko-actors, troubleshooting-motoko-migrations, writing-motoko
    1.12.0 <- mops-cli

CONFLICT  @icp-sdk/core
    ^5.0.0 <- icp-cli
    ^5.4   <- vetkeys

That reproduces #301, #297 and #298 automatically.

Design note: uniformity is the wrong rule

#333 ("state each skill's real mo:core minimum instead of one repo-wide pin") exists precisely because these numbers should differ in some places. A blunt "all versions must match" check would fight that PR. Three distinct kinds need three rules:

Kind Example Rule
Floor moc >= 1.6.0 in compatibility: May legitimately differ per skill. Flag only when below a known-bad version.
Pin @icp-sdk/core@^5.0.0 in an install command Must agree repo-wide.
Unpinned npm i @icp-sdk/core Always a defect in an install command.

The third rule alone would have caught #364 at authoring time.

Proposal: two tiers, matching existing repo infrastructure

Tier 1 — per-PR, offline

Extend scripts/check-project.js (already wired into npm run validate and CI, currently 76 lines doing metadata/eval checks) or add a sibling scripts/check-versions.js called from the same entry point.

  • Flag any npm install / npm i / mops add / cargo line naming a shared dependency with no version constraint.
  • Flag pin disagreement against a declared manifest.
  • Deterministic, no network, fails the build.

Manifest — a single source of truth for shared dependency versions, following the pattern .claude/upstream.md already establishes for upstream tracking. One file stating @icp-sdk/core is ^5 and why not ^6 (see #365), so the rationale lives in one place instead of being re-derived in five skills. Reference it from .claude/CLAUDE.md so new skills inherit pins rather than inventing them.

Tier 2 — scheduled, network

Mirror .github/workflows/sync-upstream.yml, reusing the sync-upstream-open-issue.sh pattern: on a weekly cron, run npm install --dry-run against the declared stack and open a labelled issue when it stops resolving. Do not auto-fix — surface it, same discipline as the upstream-sync workflow.

This tier is the important one, and the non-obvious part. #364 was introduced by an upstream release (@dfinity/oisy-wallet-signer 6.0.0 regressing its peer from @icp-sdk/core@^5 to ^4) with zero changes to this repo. No per-PR check could ever have caught it. It only becomes visible if something periodically attempts the install.

A minimal Tier 2 probe is roughly:

npm install --dry-run --no-audit --no-fund \
  '@icp-sdk/core@^5' @icp-sdk/auth @icp-sdk/vetkeys @icp-sdk/canisters \
  '@dfinity/oisy-wallet-signer@^4.1.3' @dfinity/utils zod

Non-zero exit, or more than one @icp-sdk/core in the resolved tree, means the declared stack has stopped composing.

Scope

  • scripts/check-versions.js + wire into npm run validate
  • version manifest file + .claude/CLAUDE.md pointer
  • .github/workflows/check-versions.yml (weekly) + label
  • Backfill: #297, #298, #301 should either resolve or be recorded as intentional floors in the manifest

Related: #364 (the live bug), #365 (v6 migration), #333 (per-skill floors).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with scripts/check-project.js and the npm run validate entry point, then read .claude/upstream.md, .claude/CLAUDE.md, and .github/workflows/sync-upstream.yml. Trace the existing sync-upstream-open-issue.sh pattern before deciding how the offline checks, manifest, and weekly workflow fit together. Done means the requested files are wired into validation and CI, with the listed conflicts resolved or recorded as intentional.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript, node.js, shell
Domain
build-system, ci-cd, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.