feat: --help for canisters

[gregorydemay]

Summary

• Adds a new canhelp skill that displays a human-readable summary of a canister's Candid interface given its mainnet canister ID or name
• Includes two helper scripts:
  • resolve-canister-id.sh: resolves name → principal via IC Dashboard API
  • fetch-candid.sh: fetches Candid metadata via icp CLI
• Agents can invoke this like --help for canisters — resolve by name or ID, fetch the .did, and present grouped query/update methods and use it to interact with the canister

Examples

Load Canister API in context

There are several ways to find the canister API of a canister:

1. By exact canister ID, e.g. /canhelp rrkah-fqaaa-aaaaa-aaaaq-cai
2. By canister name, e.g. /canhelp NNS Governance. If there is more than one match, e.g. if the search is too imprecise, the user will be asked to refine the search and a list of candidates canister is presented. For example /canhttp governance returns

   Multiple matches found. Which governance canister do you want?
   
     1. NNS Governance — rrkah-fqaaa-aaaaa-aaaaq-cai
     2. OpenChat Governance — 2jvtu-yqaaa-aaaaq-aaama-cai
     3. ICPSwap Governance — cvzxu-kyaaa-aaaaq-aacvq-cai
     4. KongSwap Governance — oypg6-faaaa-aaaaq-aadza-cai
     5. Gold DAO Governance — tr3th-kiaaa-aaaaq-aab6q-cai
     6. WaterNeuron Governance — jfnic-kaaaa-aaaaq-aadla-cai
     7. ORIGYN Governance — lnxxh-yaaaa-aaaaq-aadha-cai
   
     ...and 34 more. Pick a number or paste a canister ID.
   

Interact with canister by prompts

For example ask for List currently opened proposals, which returns

There are 2 currently open proposals:

  ┌─────┬────────┬─────────────────────────────────────────────────────────────────────────┬──────────────┬────────────────┬────────┬─────────────────────┐
  │  #  │   ID   │                                  Title                                  │     Yes      │       No       │ Total  │   Deadline (UTC)    │
  ├─────┼────────┼─────────────────────────────────────────────────────────────────────────┼──────────────┼────────────────┼────────┼─────────────────────┤
  │ 1   │ 140865 │ NNS Proposal to create an SNS named 'Yusan'                             │ 3.45T (7.4%) │ 11.17T (23.9%) │ 46.69T │ Mar 16, 2026 ~11:49 │
  ├─────┼────────┼─────────────────────────────────────────────────────────────────────────┼──────────────┼────────────────┼────────┼─────────────────────┤
  │ 2   │ 140873 │ Upgrade NNS Canister: he6b4-hiaaa-aaaan-aaaeq-cai (wasm hash 541a8592…) │ 1.38T (2.9%) │ 175.6B (0.4%)  │ 46.66T │ Mar 18, 2026 ~09:10 │
  └─────┴────────┴─────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────┴────────┴─────────────────────┘

  (Voting power shown in e8s. 1T e8s = 10,000 ICP voting power.)

  Proposal 140865 (SNS creation for Yusan) is leaning heavily toward rejection. Proposal 140873 (NNS canister upgrade) has early support with minimal opposition.```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[ielashi]

Very useful, lgtm!

[marc0olo]

Great concept and clean implementation — the name resolution feature is the standout. A few concrete suggestions before merging:

Description

Only name resolution is mainnet-specific, but the current description makes the whole skill feel limited. More importantly it doesn't state the mainnet scope clearly enough as an intentional constraint, and the killer feature (name resolution) isn't mentioned:

Display a human-readable summary of a canister's interface given its mainnet canister ID or name. Like --help but for canisters.

Suggested replacement:

Fetch and display the Candid interface of any IC mainnet canister by ID or human-readable name. Resolves names like "NNS Governance" or "ckBTC Minter" to canister IDs via the IC Dashboard. Only for mainnet canisters — for local canisters, read the generated .did file in your project directly.

The last sentence is important for agents — without it they may attempt to use this skill for local development, where it adds no value since the .did file is already in the project directory.

Frontmatter

• Missing license field
• Missing compatibility: "icp-cli >= 0.1.0" (validator warns)

fetch-candid.sh

Missing newline at end of file.

Better error message when metadata is missing. The current fallback in the SKILL.md says "suggest the user verify the canister ID and that icp is installed" — but this is wrong for a common failure mode: the canister exists but has no embedded Candid metadata. This happens with older canisters and some system canisters. The icp canister metadata command will return an empty result or error in this case, and the agent should communicate that clearly rather than suggesting the user reinstall icp.

SKILL.md body

Quote $ARGUMENTS — multi-word names like "NNS Governance" will break without quotes:

./scripts/resolve-canister-id.sh "$ARGUMENTS"  # not $ARGUMENTS

Add a pitfalls section covering:

• No embedded Candid metadata. Not all canisters embed their Candid interface in the WASM. If icp canister metadata <id> candid:service -e ic returns empty or errors, the canister exists but hasn't published its interface. This is not an icp installation issue. In this case, check the IC Dashboard canister page — some canisters list their .did files separately, or check the project's GitHub repository.

• Name resolution returns too many matches. Common words like "governance" or "ledger" return dozens of results. Encourage users to be more specific or paste the canister ID directly if they know it.

Add a "what next" pointer — after displaying the interface, the agent knows the method signatures but not necessarily how to call the canister in code. Add a brief note that for writing code against the canister, there are language-specific patterns and bindings generation tools available.

Evals

No eval file included. Suggest adding evaluations/canhelp.json with at minimum:

Should trigger:

• "What methods does the NNS governance canister have?"
• "Show me the interface of rrkah-fqaaa-aaaaa-aaaaq-cai"
• "I found a canister on the IC Dashboard, what can it do?"
• "What does the ckBTC minter canister expose?"

Should NOT trigger:

• "How do I deploy a canister?"
• "How do I transfer ICP tokens?"
• "How do I write a canister in Motoko?"
• "How do I inspect a canister I deployed locally?"

---

Note on PR #88 and dedicated skills

PR #88 proposes a canister-calls skill that bundles Candid discovery with curated workflows for ckBTC, ICRC ledgers, and EVM RPC via reference files. After running trigger evals and thinking through the architecture, a different direction seems more effective:

canister-calls should cover generic discovery and calling patterns only — no reference files for specific canisters. Its role would complement canhelp: where canhelp is for inspection (what does this canister expose?), canister-calls is for action (how do I write code that calls it?). That skill is still being refined.

Dedicated skills for ckBTC, ICRC ledgers, and EVM RPC should remain separate. The reason is fundamental: the trigger description is the routing signal for agents, and one description cannot reliably cover "generic Candid discovery" AND "ckBTC deposit workflows" AND "ICRC fee handling" AND "EVM RPC cycle costs" simultaneously. Trigger evals confirmed this — when dedicated skills exist, agents correctly prefer them for domain-specific tasks because their descriptions are more precise. Embedding domain knowledge into a generic skill produces a description that is mediocre at triggering all use cases rather than sharp at one. The content in PR #88's reference files is solid and could instead flow into improvements to the existing dedicated skills.

[github-actions]

Skill Validation Report

Validating skill: /home/runner/work/icskills/icskills/skills/canhelp

Structure

• Pass: SKILL.md found
• Pass: all files in scripts/ are referenced

Frontmatter

• Pass: name: "canhelp" (valid)
• Pass: description: (252 chars)
• Pass: license: "Apache-2.0"
• Pass: compatibility: (16 chars)
• Pass: metadata: (2 entries)
• Pass: allowed-tools: "Bash(./scripts/resolve-canister-id.sh *), Bash(./scripts/fetch-candid.sh *), Read, Grep, Glob"
• Warning: unrecognized field: "argument-hint"

Markdown

• Pass: no unclosed code fences found

Tokens

File	Tokens
SKILL.md body	443
Total	443

Content Analysis

Metric	Value
Word count	347
Code block ratio	0.01
Imperative ratio	0.11
Information density	0.06
Instruction specificity	0.00
Sections	2
List items	15
Code blocks	2

Contamination Analysis

Metric	Value
Contamination level	low
Contamination score	0.00
Primary language category	shell
Scope breadth	1

Result: 1 warning

Project Checks

✓ Project checks passed for 1 skills (0 warnings)

[gregorydemay]

@marc0olo @raymondk This file was generated by Claude and seems reasonable to me but when I try to run the evaluation framework I run into the following type of errors}

❌ Runs resolve-canister-id.sh with the provided principal
→ The assistant did not run the script; it stopped to ask for permission approval instead of executing it.

How do you want to handle this? It's kind of usual that Claude asks for the permission to do stuff but I'm not sure we want to allow to do everything when running that framework (since this is run locally and not in some sandbox). How do you handle these scenarios?