feat(vetkeys): replace vetkd with vetkeys + encrypted-maps skills

[marc0olo]

Summary

Replaces the outdated vetkd skill with two skills split by abstraction level, updated to the current vetKeys libraries and verified end-to-end.

• vetkeys — the vetKD management API plus advanced primitives: symmetric key derivation, IBE, timelock encryption, threshold BLS signatures, offline public-key derivation, and VRF. Feature depth lives in references/ibe.md and references/bls-signing.md.
• encrypted-maps — high-level, access-controlled encrypted key-value storage (the default for password managers / encrypted notes): the Rust export_encrypted_maps_canister! macro, the Motoko EncryptedMapsCanister mixin, the TS EncryptedMaps client, a short KeyManager section, and the metadata / custom-value-endpoint variant in references/metadata.md.

Each skill's description routes to the other, so agents land on the right one (bidirectional routing verified in the trigger evals).

Why replace vetkd?

The shipped vetkd skill was inaccurate against the current libraries. It used the renamed @dfinity/vetkeys (frozen at 0.4), told Motoko developers to hand-roll the management canister (a full Motoko ic-vetkeys library now exists), pinned Rust ic-vetkeys 0.6 (now 0.9), used the deprecated ic-cdk call API, referenced a non-existent toDerivedKeyMaterial(), and misstated cycle costs.

What's corrected

• @icp-sdk/vetkeys 0.5 (renamed from @dfinity/vetkeys); frontend agent/identity from @icp-sdk/core, not @dfinity/agent
• Rust ic-vetkeys 0.9 + ic-cdk 0.20 + ic-cdk-management-canister; Motoko ic-vetkeys 0.6 (moc 1.13 / core 2.6.1)
• Library management helpers (ic-cdk-management-canister, mo:ic-vetkeys/ManagementCanister) instead of hand-rolled Candid + actor "aaaaa-aa"
• VetKey.asDerivedKeyMaterial() → encryptMessage/decryptMessage (the old skill's toDerivedKeyMaterial() does not exist)
• Correct cycle costs — test_key_1 and key_1 behave the same locally and on mainnet; helpers attach the amount
• verifyBlsSignature(DerivedPublicKey, …), persistent actor (compiles with or without --default-persistent-actors), and the Motoko-has-no-frontend-crypto asymmetry documented

Verification

Every code block is derived from the canonical dfinity/examples sources (Rust master, Motoko from dfinity/examples#1475, frontends master) and the library source. All Motoko snippets compiled verbatim on moc 1.13.0 / ic-vetkeys 0.6.0 / core 2.6.1, in both mops configurations (bare and --default-persistent-actors). Cycle costs were measured on a local replica. npm run validate passes for both skills.

Honoring prior contributions

This supersedes and builds on prior community work — thank you both:

• @andreacerulli — the vetkeys / encrypted-maps split and the BLS / IBE / timelock scoping (Replace vetkd skill with a new vetkeys covering BLS, IBE, and timelock. #162, feat: Add encrypted-maps skill for vetKeys EncryptedMaps #158)
• @raymondk — the accuracy review and eval seed (Contradiction: vetkd uses legacy ic-cdk caller/call API while pinning ic-cdk 0.19 #272, vetkd: example code attaches fewer cycles than the skill's own stated key_1 fee #285, vetkd: key_1 listed as mainnet-only but local-dev section says the local network provisions it #286, fix(vetkd): use the current ic-cdk call API for management-canister vetKD calls #308)

Closes #73, #272, #285, #286.
Supersedes #158, #162, #308.

Evals

Output evals — all cases pass with the skill; strong with-skill vs baseline deltas

vetkeys

Case	WITH skill	WITHOUT (baseline)
ibe_encrypt_to_principal	4/4	2/4
symmetric_key_material_api	3/3	1/3
motoko_has_no_low_level_primitives	4/4	0/4
cycle_cost_and_helpers	3/3	0/3
bls_verify_uses_derived_public_key	3/3	0/3

encrypted-maps

Case	WITH skill	WITHOUT (baseline)
scaffold_backend_with_macro	4/4	1/4
share_map_access_rights_variant	2/2	0/2
scaffold_motoko_backend_mixin	5/5	0/5
derived_key_material_caching	3/3	1/3

Trigger evals — 100% on both skills, including bidirectional routing

• vetkeys — should_trigger 4/4, should_not_trigger 2/2 (declines the password-manager query → routes to encrypted-maps)
• encrypted-maps — should_trigger 3/3, should_not_trigger 2/2 (declines the IBE / BLS queries → routes to vetkeys)

🤖 Generated with Claude Code

[github-actions]

Skill Validation Report

Project Checks

✓ Project checks passed for 2 skills (0 warnings)

[Copilot]

Pull request overview

Replaces the outdated vetkd skill with current, abstraction-specific vetKeys guidance.

Changes:

• Adds low-level vetkeys and high-level encrypted-maps skills.
• Adds IBE, BLS, metadata, and deployment guidance.
• Adds routing and output evaluations for both skills.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
.claude/CLAUDE.md	Clarifies dependency documentation conventions.
skills/vetkd/SKILL.md	Removes obsolete vetKD guidance.
skills/vetkeys/SKILL.md	Adds updated core vetKeys guidance.
skills/vetkeys/references/ibe.md	Documents IBE and timelock flows.
skills/vetkeys/references/bls-signing.md	Documents threshold BLS signing.
skills/encrypted-maps/SKILL.md	Adds encrypted storage guidance.
skills/encrypted-maps/references/metadata.md	Covers custom metadata endpoints.
evaluations/vetkeys.json	Adds vetKeys behavior and routing evaluations.
evaluations/encrypted-maps.json	Adds EncryptedMaps behavior and routing evaluations.

Suppressed comments (1)

skills/vetkeys/SKILL.md:210

• A context/input mismatch is reported as a verification or decryption error; it is not silent. This wording can lead consumers to ignore or misdiagnose the rejected promise/result.

6. **`context` and `input` must match end to end.** A different `context` (or a different `input`) produces a different key; decryption then fails silently. Keep them byte-identical across public-key, derive, and client verify/decrypt.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.