icp-cli skill: accuracy and agent-guidance improvements

[marc0olo]

Summary

This issue tracks all improvements needed to the icp-cli skill to make it more accurate and reliable for agents — particularly those trained primarily on dfx. The changes fall into two groups: fixes to wrong/incomplete information, and new guidance that helps agents orient themselves without guessing.

All changes are expected to land in a single PR.

---

1. Add installation check and --help directive

Insert a new "Before You Start" section after "What This Is", before "Installation". It should contain:

Installation check:

which icp

If not found, install using one of the methods in the Installation section, then verify with icp --version.

Command discovery directive (the most important addition): before generating any icp command not explicitly shown in the skill, an agent must run:

icp --help
icp <command> --help
icp <command> <subcommand> --help

The --help output is authoritative for flags, arguments, and valid values. For --json output field names, run the command once live or check the documentation at https://cli.internetcomputer.org/llms.txt.

Why: A dfx-trained agent will hallucinate dfx command patterns unless it's explicitly told to consult --help first. Without the which icp check, an agent may attempt to use the CLI before it's installed.

---

2. Fix pitfall 6 — incomplete and wrong dfx identity mapping

Current text only describes icp identity default as a setter and maps it only to dfx identity use. The command is dual-purpose: without an argument it prints the current default (equivalent to dfx identity whoami).

Replace the current pitfall 6 with:

Getting dfx identity command mappings wrong. Key identity command changes:

• dfx identity use <name> → icp identity default <name> (sets default)
• dfx identity whoami → icp identity default (shows current — no argument)
• dfx identity get-principal → icp identity principal
• dfx identity remove → icp identity delete

Note: icp identity default is a dual-purpose command — with a name argument it sets, without it prints. Do not use icp identity use — it does not exist.

---

3. Add icp network stop to pitfall 9 and the workflow section

Pitfall 9 tells agents to run icp network start -d but never mentions how to stop it. An agent that starts a background network has no recovery path without this.

Append to pitfall 9:

Always stop the network when done: icp network stop

Also update the build pipeline examples in "How It Works" to show the full local dev lifecycle:

icp network start -d    # start background network (project-local)
icp deploy              # build + deploy + sync
icp network stop        # stop when done

---

4. Add port conflict pitfall (new pitfall 17)

The local network defaults to port 8000. A dfx-trained agent won't anticipate this (dfx used 4943) and won't know how to resolve conflicts. Add a new pitfall covering two distinct scenarios:

Scenario A — Another icp-cli project owns the port. The error names the offending project:

port 8000 is in use by the local network of the project at '/path/to/other-project'

Stop that network without changing directory, using --project-root-override:

icp network stop --project-root-override /path/to/other-project

Then start your own network normally.

Scenario B — A non-icp-cli service owns the port. icp-cli has no pre-check for this; the failure comes from the OS. Configure a different port in icp.yaml:

networks:
  - name: local
    mode: managed
    gateway:
      port: 8001

If you change the port, read the gateway URL dynamically rather than hardcoding localhost:8000:

icp network status --json  # returns api_url, gateway_url, root_key

---

5. Add icp new non-interactive warning (new pitfall 18)

Without --define flags, icp new launches an interactive prompt. In CI or automated agent use this will hang silently — nothing in the current skill warns about this. Add a new pitfall:

icp new blocks waiting for input in non-interactive contexts. Without --define flags, icp new launches an interactive prompt. In CI or automated setup this will hang silently. Pass all required template variables with --define and use --silent to fail fast if any value is missing instead of prompting:

icp new my-project --subfolder rust --define project_name=my-project --silent

---

6. Clarify icp canister status default-to-all behavior

A dfx-trained agent expects dfx canister status --all as an explicit opt-in. In icp-cli, omitting the canister argument queries all canisters in the environment — silence means all.

Add a note alongside any icp canister status example:

icp canister status with no canister argument queries all canisters in the environment — this is the default, not an opt-in. To target one canister, always pass its name explicitly.

---

7. Clarify icp canister status vs icp canister settings show

These two commands return similar information and are easy to confuse. Add a note near the canister lifecycle content:

icp canister status and icp canister settings show return similar information but differ in scope: status accepts an optional canister argument (defaults to all in the environment), while settings show requires exactly one canister. Prefer status for scripting across all canisters; use settings show when targeting one canister by name.