chore: add shared skills infrastructure with submodule-based symlinks

marc0olo · marc0olo · commit eabbdfcbcd32 · 2026-03-19T10:17:09.000+01:00
Set up .agents/skills/ as the agent-agnostic canonical location for all
skills, with .claude/skills/ symlinks for Claude Code. All 17 skills are
pure symlinks: 16 icskills point to .sources/icskills/skills/, and
technical-documentation points to .sources/dotskills/skills/ (new
submodule, kept external due to AGPL-3.0 license). Updated AGENTS.md
with submodule docs, verification commands, and prerequisites.
diff --git a/.agents/skills/asset-canister b/.agents/skills/asset-canister
@@ -0,0 +1 @@
+../../.sources/icskills/skills/asset-canister
diff --git a/.agents/skills/canister-security b/.agents/skills/canister-security
@@ -0,0 +1 @@
+../../.sources/icskills/skills/canister-security
diff --git a/.agents/skills/certified-variables b/.agents/skills/certified-variables
@@ -0,0 +1 @@
+../../.sources/icskills/skills/certified-variables
diff --git a/.agents/skills/ckbtc b/.agents/skills/ckbtc
@@ -0,0 +1 @@
+../../.sources/icskills/skills/ckbtc
diff --git a/.agents/skills/cycles-management b/.agents/skills/cycles-management
@@ -0,0 +1 @@
+../../.sources/icskills/skills/cycles-management
diff --git a/.agents/skills/evm-rpc b/.agents/skills/evm-rpc
@@ -0,0 +1 @@
+../../.sources/icskills/skills/evm-rpc
diff --git a/.agents/skills/https-outcalls b/.agents/skills/https-outcalls
@@ -0,0 +1 @@
+../../.sources/icskills/skills/https-outcalls
diff --git a/.agents/skills/ic-dashboard b/.agents/skills/ic-dashboard
@@ -0,0 +1 @@
+../../.sources/icskills/skills/ic-dashboard
diff --git a/.agents/skills/icp-cli b/.agents/skills/icp-cli
@@ -0,0 +1 @@
+../../.sources/icskills/skills/icp-cli
diff --git a/.agents/skills/icrc-ledger b/.agents/skills/icrc-ledger
@@ -0,0 +1 @@
+../../.sources/icskills/skills/icrc-ledger
diff --git a/.agents/skills/internet-identity b/.agents/skills/internet-identity
@@ -0,0 +1 @@
+../../.sources/icskills/skills/internet-identity
diff --git a/.agents/skills/multi-canister b/.agents/skills/multi-canister
@@ -0,0 +1 @@
+../../.sources/icskills/skills/multi-canister
diff --git a/.agents/skills/sns-launch b/.agents/skills/sns-launch
@@ -0,0 +1 @@
+../../.sources/icskills/skills/sns-launch
diff --git a/.agents/skills/stable-memory b/.agents/skills/stable-memory
@@ -0,0 +1 @@
+../../.sources/icskills/skills/stable-memory
diff --git a/.agents/skills/technical-documentation b/.agents/skills/technical-documentation
@@ -0,0 +1 @@
+../../.sources/dotskills/skills/technical-documentation
diff --git a/.agents/skills/vetkd b/.agents/skills/vetkd
@@ -0,0 +1 @@
+../../.sources/icskills/skills/vetkd
diff --git a/.agents/skills/wallet-integration b/.agents/skills/wallet-integration
@@ -0,0 +1 @@
+../../.sources/icskills/skills/wallet-integration
diff --git a/.claude/skills/asset-canister b/.claude/skills/asset-canister
@@ -0,0 +1 @@
+../../.agents/skills/asset-canister
diff --git a/.claude/skills/canister-security b/.claude/skills/canister-security
@@ -0,0 +1 @@
+../../.agents/skills/canister-security
diff --git a/.claude/skills/certified-variables b/.claude/skills/certified-variables
@@ -0,0 +1 @@
+../../.agents/skills/certified-variables
diff --git a/.claude/skills/ckbtc b/.claude/skills/ckbtc
@@ -0,0 +1 @@
+../../.agents/skills/ckbtc
diff --git a/.claude/skills/cycles-management b/.claude/skills/cycles-management
@@ -0,0 +1 @@
+../../.agents/skills/cycles-management
diff --git a/.claude/skills/evm-rpc b/.claude/skills/evm-rpc
@@ -0,0 +1 @@
+../../.agents/skills/evm-rpc
diff --git a/.claude/skills/https-outcalls b/.claude/skills/https-outcalls
@@ -0,0 +1 @@
+../../.agents/skills/https-outcalls
diff --git a/.claude/skills/ic-dashboard b/.claude/skills/ic-dashboard
@@ -0,0 +1 @@
+../../.agents/skills/ic-dashboard
diff --git a/.claude/skills/icp-cli b/.claude/skills/icp-cli
@@ -0,0 +1 @@
+../../.agents/skills/icp-cli
diff --git a/.claude/skills/icrc-ledger b/.claude/skills/icrc-ledger
@@ -0,0 +1 @@
+../../.agents/skills/icrc-ledger
diff --git a/.claude/skills/internet-identity b/.claude/skills/internet-identity
@@ -0,0 +1 @@
+../../.agents/skills/internet-identity
diff --git a/.claude/skills/multi-canister b/.claude/skills/multi-canister
@@ -0,0 +1 @@
+../../.agents/skills/multi-canister
diff --git a/.claude/skills/sns-launch b/.claude/skills/sns-launch
@@ -0,0 +1 @@
+../../.agents/skills/sns-launch
diff --git a/.claude/skills/stable-memory b/.claude/skills/stable-memory
@@ -0,0 +1 @@
+../../.agents/skills/stable-memory
diff --git a/.claude/skills/technical-documentation b/.claude/skills/technical-documentation
@@ -0,0 +1 @@
+../../.agents/skills/technical-documentation
diff --git a/.claude/skills/vetkd b/.claude/skills/vetkd
@@ -0,0 +1 @@
+../../.agents/skills/vetkd
diff --git a/.claude/skills/wallet-integration b/.claude/skills/wallet-integration
@@ -0,0 +1 @@
+../../.agents/skills/wallet-integration
diff --git a/.gitignore b/.gitignore
@@ -28,10 +28,14 @@ public/docs-manifest.json
 # macOS-specific files
 .DS_Store
 
-# Claude Code (local-only files; .claude/settings.json is committed)
+# Claude Code (local-only files; .claude/settings.json and .claude/skills/ are committed)
 .claude/settings.local.json
 .claude/worktrees/
 
+# Skills install artifacts (npx skills add writes here; committed skills live in .agents/skills/)
+/skills/
+skills-lock.json
+
 # Dolt database files (added by bd init)
 .dolt/
 *.db
diff --git a/.gitmodules b/.gitmodules
@@ -40,3 +40,6 @@
 [submodule ".sources/response-verification"]
 	path = .sources/response-verification
 	url = git@github.com:dfinity/response-verification.git
+[submodule ".sources/dotskills"]
+	path = .sources/dotskills
+	url = git@github.com:vincentkoc/dotskills.git
diff --git a/.sources/dotskills b/.sources/dotskills
@@ -0,0 +1 @@
+Subproject commit a44218fb73f1ab5ef597d66ab3d9eb651f075f9c
diff --git a/AGENTS.md b/AGENTS.md
@@ -324,7 +324,7 @@ Add enough context in the notes so the next agent (or human) understands the blo
 ## Always (do these without asking)
 
 - Read `.docs-plan/decisions.md` before proposing structural changes
-- **Ensure all required skills are loaded** before starting any work (see "Skills (required)" section). This is a hard prerequisite — if skills fail to install, do not create content or review PRs. Report the failure to the user and work on non-content tasks only (rebasing, housekeeping, infrastructure).
+- **Ensure all required skills are accessible** before starting any work (see "Skills (required)" section). Skills are pre-installed as symlinks — if they appear broken, run `git submodule update --init --depth 1`. Do not start content or review work if skills are inaccessible.
 - Use icp-cli commands in all CLI examples — never `dfx`
 - Write plain `.md` files only — never `.mdx` or JSX
 - Include complete frontmatter (see CONTRIBUTING.md for schema)
@@ -373,6 +373,8 @@ Add enough context in the notes so the next agent (or human) understands the blo
 - `docs/guides/tools/migrating-from-dfx.md` — Synced from `dfinity/icp-cli` (do not edit directly)
 - `.docs-plan/` — Analysis artifacts, decisions, and progress tracking (see `.docs-plan/README.md`)
 - `.sources/` — **Pinned submodules of upstream source repos** (see "Source material repos" below)
+- `.agents/skills/` — Shared agent skills. All entries are symlinks: `technical-documentation` → `.sources/dotskills/skills/technical-documentation`, icskills → `.sources/icskills/skills/`. Requires submodules to be initialized (`git submodule update --init --depth 1`).
+- `.claude/skills/` — Symlinks to `.agents/skills/` for Claude Code. Same skills, Claude-specific path.
 - `.claude/settings.json` — Shared Claude Code permissions (committed to git). Ensures worktree/background agents can run without interactive approval.
 - `plugins/` — Astro build plugins (rehype/remark transforms and the agent-docs integration)
 - `icp.yaml` — icp-cli project config (asset canister recipe)
@@ -419,6 +421,7 @@ All upstream source repos are pinned as **git submodules** under `.sources/`. Th
 | `.sources/cdk-rs` | `dfinity/cdk-rs` | `timers-1.0.0` / `executor-2.0.0` | Rust CDK (`ic-cdk`, `ic-cdk-timers`, `ic-cdk-macros`) — API signatures, management canister types |
 | `.sources/candid` | `dfinity/candid` | `2025-12-18` | Candid spec, type system, `didc` tool source |
 | `.sources/response-verification` | `dfinity/response-verification` | `v3.1.0` (latest release) | Response verification, certified variables, certificate trees |
+| `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) |
 
 ### Submodule initialization
 
@@ -489,18 +492,21 @@ Read `.docs-plan/content-authoring.md` before writing any page. It covers the fu
 
 ## Skills (required)
 
-Skills are a **hard prerequisite** — do not start any content work, review, or ICP-related task without them. At session start, verify skills are loaded. If not, install them:
+Skills are a **hard prerequisite** — do not start any content work, review, or ICP-related task without them. All skills are pre-installed in the repo:
 
-```bash
-# Technical documentation skill (drafting and reviewing docs quality)
-npx skills add https://github.com/vincentkoc/dotskills --skill technical-documentation
+- `.agents/skills/` — agent-agnostic location (canonical)
+- `.claude/skills/` — symlinks to `.agents/skills/` for Claude Code
+
+**Prerequisite:** All skills are symlinks into `.sources/` submodules (icskills → `.sources/icskills/skills/`, technical-documentation → `.sources/dotskills/skills/technical-documentation`). Run `git submodule update --init --depth 1` if skills appear as broken symlinks.
 
-# ICP development skills (canister IDs, code patterns, common pitfalls)
-npx skills add .sources/icskills
+At session start, verify skills are accessible:
+```bash
+ls .agents/skills/icp-cli/SKILL.md .agents/skills/technical-documentation/SKILL.md
+# Both should resolve (not "No such file"). If broken, run: git submodule update --init --depth 1
 ```
 
 - **`technical-documentation`** — Load before drafting or reviewing any docs page
-- **icskills** (17 skills) — Load the relevant skill before writing any feature-specific content. Skills are in `.sources/icskills/` (pinned submodule). Use the skill that matches the page topic (e.g., `ckbtc` for Bitcoin guides, `multi-canister` for architecture pages, `icp-cli` for CLI guides).
+- **icskills** (16 skills) — Load the relevant skill before writing any feature-specific content. Use the skill that matches the page topic (e.g., `ckbtc` for Bitcoin guides, `multi-canister` for architecture pages, `icp-cli` for CLI guides).
 
 ## Frontmatter schema
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/asset-canister`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/canister-security`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/certified-variables`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/cycles-management`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/https-outcalls`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/ic-dashboard`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../.sources/icskills/skills/icrc-ledger`