Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills/asset-canister/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: asset-canister
description: "Deploy frontend assets to the IC. Covers certified assets, SPA routing with .ic-assets.json5, custom domains, content encoding, and programmatic uploads. Use when hosting a frontend, deploying static files, configuring custom domains, or setting up SPA routing on IC. Do NOT use for canister-level code patterns."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0, Node.js >= 22"
compatibility: "icp-cli >= 0.2.2, Node.js >= 22"
metadata:
title: "Asset Canister & Frontend"
category: Frontend
Expand Down
2 changes: 1 addition & 1 deletion skills/certified-variables/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: certified-variables
description: "Serve cryptographically verified responses from query calls using Merkle trees and subnet BLS signatures. Covers certified data API, RbTree/CertTree construction, witness generation, and frontend certificate validation. Use when query responses need verification, certified data, or response authenticity proofs."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: Certified Variables
category: Security
Expand Down
2 changes: 1 addition & 1 deletion skills/ckbtc/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: ckbtc
description: "Accept, send, and manage ckBTC (chain-key Bitcoin). Covers BTC deposit flow via minter, ckBTC transfers, withdrawal to BTC, subaccount derivation, and UTXO management. Use when integrating Bitcoin, ckBTC, BTC deposits, or BTC withdrawals in a canister. Do NOT use for plain token transfers without BTC minting/withdrawal — use icrc-ledger instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: ckBTC Integration
category: DeFi
Expand Down
2 changes: 1 addition & 1 deletion skills/cycles-management/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: cycles-management
description: "Manage cycles and canister lifecycle. Covers cycle balance checks, top-ups, freezing thresholds, canister creation, and ICP-to-cycles conversion via the CMC. Use when working with cycles, canister funding, freezing threshold, frozen canister, out of cycles, top-up, canister creation, or cycle balance. Do NOT use for wallet-to-dApp integration or ICRC signer flows — use wallet-integration instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: Cycles Management
category: Infrastructure
Expand Down
2 changes: 1 addition & 1 deletion skills/evm-rpc/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: evm-rpc
description: "Call Ethereum and EVM chains from IC canisters via the EVM RPC canister. Covers JSON-RPC calls, multi-provider consensus, ERC-20 reads, and sending pre-signed transactions. Use when calling Ethereum, Arbitrum, Base, Optimism, or any EVM chain from a canister. Do NOT use for generic HTTPS calls to non-EVM APIs — use https-outcalls instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: EVM RPC Integration
category: Integration
Expand Down
2 changes: 1 addition & 1 deletion skills/https-outcalls/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: https-outcalls
description: "Make HTTPS requests from canisters to external web APIs. Covers transform functions for consensus, cycle cost management, response size limits, and idempotency patterns. Use when a canister needs to call an external API, fetch data from the web, or make HTTP requests. Do NOT use for EVM/Ethereum calls — use evm-rpc instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: HTTPS Outcalls
category: Integration
Expand Down
2 changes: 1 addition & 1 deletion skills/icrc-ledger/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: icrc-ledger
description: "Deploy and interact with ICRC-1/ICRC-2 token ledgers (ICP, ckBTC, ckETH). Covers transfers, balances, approve/transferFrom allowances, fee handling, and ledger deployment. Use when working with ICP transfers, token transfers, balances, ICRC-1, ICRC-2, approve, allowance, or any fungible token on IC. Do NOT use for ckBTC minting or BTC deposit/withdrawal flows — use ckbtc instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: ICRC Ledger Standard
category: Tokens
Expand Down
16 changes: 9 additions & 7 deletions skills/internet-identity/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: internet-identity
description: "Integrate Internet Identity authentication. Covers passkey and OpenID login flows, delegation handling, and principal-per-app isolation. Use when adding login, sign-in, auth, passkeys, or Internet Identity to a frontend or canister. Do NOT use for wallet integration or ICRC signer flows — use wallet-integration instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0, Node.js >= 22"
compatibility: "icp-cli >= 0.2.2, Node.js >= 22"
metadata:
title: Internet Identity Auth
category: Auth
Expand All @@ -22,12 +22,12 @@ Internet Identity (II) is the Internet Computer's native authentication system.

| Canister | ID | URL | Purpose |
|----------|------------|-----|---------|
| Internet Identity (backend) | `rdmx6-jaaaa-aaaaa-aaadq-cai` | `https://backend.id.ai` | Manages user keys and authentication logic |
| Internet Identity (backend) | `rdmx6-jaaaa-aaaaa-aaadq-cai` | | Manages user keys and authentication logic |
| Internet Identity (frontend) | `uqzsh-gqaaa-aaaaq-qaada-cai` | `https://id.ai` | Serves the II web app; identity provider URL points here |

## Mistakes That Break Your Build

1. **Using the wrong II URL for the environment.** The identity provider URL must point to the **frontend** canister (`uqzsh-gqaaa-aaaaq-qaada-cai`), not the backend. Local development must use `http://uqzsh-gqaaa-aaaaq-qaada-cai.localhost:8000`. Mainnet must use `https://id.ai` (which resolves to the frontend canister). Both canister IDs are well-known and identical on mainnet and local replicas -- hardcode them rather than doing a dynamic lookup.
1. **Using the wrong II URL for the environment.** The identity provider URL must point to the **frontend** canister (`uqzsh-gqaaa-aaaaq-qaada-cai`), not the backend. Local development should use `http://id.ai.localhost:8000`. Mainnet must use `https://id.ai` (which resolves to the frontend canister). Both canister IDs are well-known and identical on mainnet and local replicas -- hardcode them rather than doing a dynamic lookup.

2. **Setting delegation expiry too long.** Maximum delegation expiry is 30 days (2_592_000_000_000_000 nanoseconds). Longer values are silently clamped, which causes confusing session behavior. Use 8 hours for normal apps, 30 days maximum for "remember me" flows.

Expand All @@ -39,7 +39,7 @@ Internet Identity (II) is the Internet Computer's native authentication system.

6. **Passing principal as string to backend.** The `AuthClient` gives you an `Identity` object. Backend canister methods receive the caller principal automatically via the IC protocol -- you do not pass it as a function argument. The caller principal is available on the backend via `shared(msg) { msg.caller }` in Motoko or `ic_cdk::api::msg_caller()` in Rust. For backend access control patterns, see the **canister-security** skill.

## Implementation
## Using II during local development

### icp.yaml Configuration

Expand All @@ -52,7 +52,9 @@ networks:
ii: true
```

This tells icp-cli to pull and run the II canister automatically when you deploy. No canister entry needed — II is not part of your project's canisters. For the full `icp.yaml` canister configuration, see the **icp-cli** and **asset-canister** skills.
This deploys the II canisters automatically when the local network is started. By default, the II frontend will be available at http://id.ai.localhost:8000
No canister entry needed — II is not part of your project's canisters.
For the full `icp.yaml` canister configuration, see the **icp-cli** and **asset-canister** skills.

### Frontend: Vanilla JavaScript/TypeScript Login Flow

Expand All @@ -71,14 +73,14 @@ let authClient;
const canisterEnv = safeGetCanisterEnv();

// Determine II URL based on environment.
// The identity provider URL points to the frontend canister (uqzsh-gqaaa-aaaaq-qaada-cai),
// The identity provider URL points to the frontend canister which gets mapped to http://id.ai.localhost,
// not the backend (rdmx6-jaaaa-aaaaa-aaadq-cai). Both are well-known IDs, identical on
// mainnet and local replicas.
function getIdentityProviderUrl() {
const host = window.location.hostname;
const isLocal = host === "localhost" || host === "127.0.0.1" || host.endsWith(".localhost");
if (isLocal) {
return "http://uqzsh-gqaaa-aaaaq-qaada-cai.localhost:8000";
return "http://id.ai.localhost:8000";
}
return "https://id.ai";
}
Expand Down
2 changes: 1 addition & 1 deletion skills/multi-canister/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: multi-canister
description: "Design and deploy multi-canister dapps. Covers inter-canister calls, canister factory pattern, async messaging pitfalls, bounded vs unbounded wait, and 2MB payload limits. Use when splitting an app across canisters, making inter-canister or cross-canister calls, or designing canister-to-canister communication. Do NOT use for single-canister apps."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: Multi-Canister Architecture
category: Architecture
Expand Down
2 changes: 1 addition & 1 deletion skills/sns-launch/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: sns-launch
description: "Configure and launch an SNS DAO to decentralize a dapp. Covers token economics, governance parameters, testflight validation, NNS proposal submission, and decentralization swap. Use when launching an SNS, configuring tokenomics, or setting up DAO governance for a dapp. Do NOT use for NNS governance or general canister management."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0, dfx with sns extension"
compatibility: "icp-cli >= 0.2.2, dfx with sns extension"
metadata:
title: SNS DAO Launch
category: Governance
Expand Down
2 changes: 1 addition & 1 deletion skills/stable-memory/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: stable-memory
description: "Persist canister state across upgrades. Covers StableBTreeMap and MemoryManager in Rust, persistent actor in Motoko, and upgrade hook patterns. Use when dealing with canister upgrades, data persistence, data lost after upgrade, stable storage, StableBTreeMap, pre_upgrade traps, or heap vs stable memory. Do NOT use for inter-canister calls or access control — use multi-canister or canister-security instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: "Stable Memory & Upgrades"
category: Architecture
Expand Down
2 changes: 1 addition & 1 deletion skills/vetkd/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: vetkd
description: "Implement on-chain encryption using vetKeys (verifiable encrypted threshold key derivation). Covers key derivation, IBE encryption/decryption, transport keys, and access control. Use when adding encryption, decryption, on-chain privacy, vetKeys, or identity-based encryption to a canister. Do NOT use for authentication — use internet-identity instead."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
compatibility: "icp-cli >= 0.2.2"
metadata:
title: vetKeys
category: Security
Expand Down
Loading