diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md index 22ea219a..5660d732 100644 --- a/docs/getting-started/choose-your-path.md +++ b/docs/getting-started/choose-your-path.md @@ -91,8 +91,8 @@ The Service Nervous System (SNS) lets you tokenize your application and create a **You want to:** Use AI coding agents to build on ICP. -ICP has a set of [icskills](https://skills.internetcomputer.org) -- structured knowledge files that AI agents can load to write canister code, debug deployments, and navigate the platform. If you work with tools like Claude Code, Cursor, or Copilot, icskills give them the context they need. +ICP has a set of [ICP skills](https://skills.internetcomputer.org) — structured knowledge files that AI agents can load to write canister code, debug deployments, and navigate the platform. If you work with tools like Claude Code, Cursor, or Copilot, ICP skills give them the context they need. -**Learn more:** [Agentic development](../guides/tools/agentic-development.md) +**Learn more:** [AI coding agents](../guides/tools/ai-coding-agents.md) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 0c4418e2..f9c7e340 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -129,7 +129,7 @@ Each canister name maps to a directory containing its own `canister.yaml` with b - [Project structure](project-structure.md) — Understand how icp-cli projects are organized - [Choose your path](choose-your-path.md) — pick a development path based on what you want to build - [Concepts: Canisters](../concepts/canisters.md) — Learn what canisters are and how they work -- [Agentic development](../guides/tools/agentic-development.md) — Use AI agents to build on the Internet Computer +- [AI coding agents](../guides/tools/ai-coding-agents.md) — Use ICP skills to build on the Internet Computer with AI - [icp-cli documentation](https://cli.internetcomputer.org/) — Full CLI reference and guides diff --git a/docs/guides/index.md b/docs/guides/index.md index 088253b3..3917261f 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -28,4 +28,6 @@ Practical how-to guides organized by development stage. Each guide solves a spec ## Developer tools -- **[Tools](tools/agentic-development.md)** -- AI-assisted development with icskills, developer tools, and migrating from dfx. +- **[Tools](tools/ai-coding-agents.md)** — AI coding agents with ICP skills, developer tools, and migrating from dfx. + + diff --git a/docs/guides/tools/agentic-development.md b/docs/guides/tools/agentic-development.md deleted file mode 100644 index 359f829c..00000000 --- a/docs/guides/tools/agentic-development.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: "Agentic Development" -description: "Use AI agents with icskills to build ICP applications faster and with fewer errors" -sidebar: - order: 1 ---- - -AI agents can build, deploy, and interact with Internet Computer applications using the same tools as human developers: `icp` for project management, icskills for implementation patterns, and the `llms.txt` discovery endpoint for navigating these docs programmatically. This page explains how to configure agents for ICP development and what resources are available. - -## What icskills are - -icskills are structured, agent-readable markdown files that teach AI agents how to build correctly on the Internet Computer. Each skill covers one capability area and includes: - -- Correct canister IDs for mainnet services -- Tested, copy-paste-correct code patterns in Motoko and Rust -- Common pitfalls that cause hallucinations or build failures -- Required dependency versions and configuration formats -- Step-by-step deployment and verification commands - -Skills exist because LLMs frequently hallucinate canister IDs, use deprecated APIs, and miss IC-specific constraints. A skill loaded into an agent's context prevents these errors by providing accurate ground truth for a specific integration area. - -The skills registry is hosted at [skills.internetcomputer.org](https://skills.internetcomputer.org) and follows the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc). - -## Available skills - -The following integration skills are published in the `dfinity/icskills` registry: - -| Skill | What it covers | -|-------|----------------| -| `icp-cli` | icp.yaml config, recipes, environments, canister lifecycle, identity management | -| `asset-canister` | Frontend hosting, certified assets, SPA routing, content encoding | -| `canister-security` | Access control, reentrancy prevention, cycle drain protection, safe upgrades | -| `certified-variables` | Certified data API, Merkle trees, witness generation, frontend certificate validation | -| `ckbtc` | BTC deposit via minter, ckBTC transfers, withdrawal to BTC, subaccount derivation | -| `cycles-management` | Cycle balance checks, top-ups, freezing thresholds, ICP-to-cycles conversion | -| `custom-domains` | DNS configuration, `ic-domains` file, domain registration and validation via the HTTP gateway | -| `evm-rpc` | Ethereum/EVM calls from canisters via the EVM RPC canister | -| `https-outcalls` | HTTPS requests from canisters to external APIs, transform functions | -| `ic-dashboard` | Query the dashboard REST API for canister info, ledger data, network metrics | -| `icrc-ledger` | ICRC-1/ICRC-2 token transfers, balances, approve/transferFrom, ledger deployment | -| `internet-identity` | Passkey and OpenID login, delegation handling, principal-per-app isolation | -| `motoko` | Motoko language pitfalls, stable types, `mo:core` standard library | -| `multi-canister` | Inter-canister calls, canister factory pattern, async messaging pitfalls | -| `sns-launch` | SNS DAO configuration, token economics, governance parameters, testflight | -| `stable-memory` | StableBTreeMap, MemoryManager, persistent actors, upgrade hook patterns | -| `vetkd` | On-chain encryption with vetKeys, IBE encryption/decryption, transport keys | -| `wallet-integration` | ICRC signer standards (ICRC-21/25/27/29/49), wallet popup flows, consent messages | - -The registry also includes tool skills like `canhelp`, which displays a human-readable summary of any mainnet canister's Candid interface. Browse the full list at [skills.internetcomputer.org](https://skills.internetcomputer.org). - -Each skill is a self-contained markdown file. Skills can be loaded individually — you only need the skills relevant to your project. - -## Installing skills - -### CLI installation (recommended) - -The `skills` CLI installs skill files directly into your agent's configuration directory: - -```bash -npx skills add dfinity/icskills -``` - -This command prompts you to choose which agent you're configuring (Claude Code, Cursor, Windsurf, GitHub Copilot, and others), then installs the selected skills into the correct location for that agent. - -### Manual installation - -To fetch a single skill without the CLI: - -```bash -curl -sL https://skills.internetcomputer.org/.well-known/skills/icp-cli/SKILL.md -``` - -Paste the output into your agent's system prompt, rules file, or context window. The files are plain markdown. - -### Programmatic access - -Skills are available via a machine-readable index: - -| Resource | URL | -|----------|-----| -| All skills (index) | `https://skills.internetcomputer.org/.well-known/skills/index.json` | -| Single skill | `https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.md` | -| Additional reference files | `https://skills.internetcomputer.org/.well-known/skills/{name}/references/{file}.md` | -| Skill zip bundle | `https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.zip` | -| Skills discovery index for agents | `https://skills.internetcomputer.org/llms.txt` | - -The index JSON follows the Agent Skills Discovery RFC format — agents that support this standard can auto-discover and load skills on demand. - -## Configuring AI agents - -### Claude Code - -After running `npx skills add dfinity/icskills`, skill files are installed as `.claude/skills/*.md` in your project. Claude Code automatically reads files in `.claude/skills/` as part of its system context. - -To load a skill manually in Claude Code, reference the skill file in a CLAUDE.md or in your session prompt: - -``` -Load .claude/skills/icp-cli/SKILL.md before generating any icp commands. -``` - -For batch projects with multiple skill areas, load each relevant skill at session start. The `icp-cli` skill is always useful — load it for every ICP project regardless of other skills. - -### Cursor and Windsurf - -Skills installed via `npx skills add dfinity/icskills` are placed in your agent's rules directory (`.cursor/rules/` for Cursor) or into Windsurf's Cascade context. The CLI handles placement automatically when you select your agent during installation. - -### GitHub Copilot - -The `npx skills add` CLI installs skills into the correct location for GitHub Copilot custom instructions automatically when you select Copilot during installation. The exact path depends on your Copilot version and workspace configuration. - -## Agent-friendly documentation - -This docs site implements the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). Two endpoints make these docs directly consumable by agents: - -**`/llms.txt`** — a discovery index listing every page with links to its clean markdown endpoint, plus the skills registry URL. Agents that support `llms.txt` can use this to discover all available documentation. - -**`/.md`** — every page in the docs is available as clean markdown at a `.md` URL. HTML, navigation, and site chrome are stripped, leaving only the page content. For example, this page is available at `/guides/tools/agentic-development.md`. - -A `` tag in every page's `` points to `/llms.txt`, so agents that crawl docs pages discover the index automatically without prior knowledge of this endpoint. - -To use these endpoints when querying ICP docs: - -```bash -# Discover all available pages -curl -sL https://beta-docs.internetcomputer.org/llms.txt - -# Fetch any page as clean markdown -curl -sL https://beta-docs.internetcomputer.org/guides/tools/agentic-development.md -``` - -Skills take priority over docs for implementation-level questions. Use skills for "how do I implement X" and use the docs for "what is X and how does it fit in the architecture." - -## When to load which skill - -Load skills based on what your project integrates. You do not need every skill — only the ones relevant to your build: - -| If you are building... | Load these skills | -|------------------------|-------------------| -| Any IC project | `icp-cli` | -| Frontend dApp | `icp-cli`, `asset-canister`, `internet-identity` | -| Frontend dApp with custom domain | `icp-cli`, `asset-canister`, `custom-domains` | -| Token integration | `icp-cli`, `icrc-ledger` | -| Bitcoin integration | `icp-cli`, `ckbtc` | -| Cross-chain with Ethereum | `icp-cli`, `evm-rpc` | -| Multi-canister architecture | `icp-cli`, `multi-canister` | -| Secure canister | `icp-cli`, `canister-security` | -| DAO / governance | `icp-cli`, `sns-launch` | -| Encrypted data | `icp-cli`, `vetkd`, `certified-variables` | - -If in doubt, start with `icp-cli` and add domain-specific skills as you encounter relevant integration points. - -## Skills vs docs: how they complement each other - -Skills and docs serve different purposes: - -| Skills | Docs | -|--------|------| -| Implementation patterns | Concepts and architecture | -| Correct canister IDs for mainnet | How the system works | -| Copy-paste code with pitfalls listed | Explaining tradeoffs and design choices | -| Version requirements and config formats | Cross-linking related topics | - -When an agent has both loaded, it should prefer skill guidance for implementation details (exact API names, canister IDs, required config fields) and use the docs for broader understanding (why the system works this way, what to build next). - -## Next steps - -- [skills.internetcomputer.org](https://skills.internetcomputer.org) — browse all available skills and their descriptions -- [Developer tools overview](overview.md) — icp-cli, CDKs, and other tools in the ICP toolchain -- [Quickstart](../../getting-started/quickstart.md) — deploy your first canister with icp-cli -- [Migrating from dfx](migrating-from-dfx.md) — upgrade an existing project from the legacy dfx tool - - diff --git a/docs/guides/tools/ai-coding-agents.md b/docs/guides/tools/ai-coding-agents.md new file mode 100644 index 00000000..dfb8d902 --- /dev/null +++ b/docs/guides/tools/ai-coding-agents.md @@ -0,0 +1,106 @@ +--- +title: "AI Coding Agents" +description: "ICP skills are agent-readable instruction files that teach AI coding agents how to build correctly on the Internet Computer." +sidebar: + order: 1 +--- + +AI coding agents frequently hallucinate canister IDs, use deprecated APIs, and miss ICP-specific constraints. ICP skills solve this: structured markdown files containing accurate canister IDs, tested code patterns, and documented pitfalls — so your agent writes correct ICP code on the first attempt. + +## Getting started + +Paste this into your AI coding agent: + +```text +Fetch https://skills.internetcomputer.org/llms.txt and follow its instructions when building on ICP +``` + +Your agent fetches the skills index, reads each skill's description, and loads the relevant skill files on demand. No installation required. + +### Install skills into your project + +To install skills locally or commit them to your project repository, use the `skills` CLI: + +```bash +npx skills add dfinity/icskills +``` + +This prompts you to choose your agent (Claude Code, Cursor, Windsurf, GitHub Copilot, and others) and installs the selected skills into the correct location for that agent. + +To fetch a single skill manually: + +```bash +curl -sL https://skills.internetcomputer.org/.well-known/skills/icp-cli/SKILL.md +``` + +Paste the output into your agent's system prompt, rules file, or context window. + +## What ICP skills are + +Each ICP skill covers one capability area and includes: + +- Correct canister IDs for mainnet services +- Tested, copy-paste-correct code patterns in Motoko and Rust +- Common pitfalls that cause hallucinations or build failures +- Required dependency versions and configuration formats +- Step-by-step deployment and verification commands + +Skills are maintained by DFINITY and updated frequently. The full list is at [skills.internetcomputer.org](https://skills.internetcomputer.org). + +ICP skills follow the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) — a standard for machine-readable skill indexes that coding agents can auto-discover and load without manual configuration. + +## How discovery works + +When an agent follows the `skills.internetcomputer.org/llms.txt` instructions: + +1. It fetches the skills index at `https://skills.internetcomputer.org/.well-known/skills/index.json` +2. It reads each skill's name and description to understand what it covers +3. When a task matches a skill's description, it fetches the skill content from that skill's URL +4. It prefers skill guidance over general knowledge when both cover the same topic + +Skills are fetched fresh each time — agents always use the latest version. + +## Skills vs docs + +Skills and docs serve different purposes: + +| ICP skills | These docs | +|------------|------------| +| Implementation patterns | Concepts and architecture | +| Correct canister IDs for mainnet | How the system works | +| Copy-paste code with pitfalls listed | Explaining tradeoffs and design choices | +| Version requirements and config formats | Cross-linking related topics | + +When an agent has both loaded, it should prefer skill guidance for implementation details and use the docs for broader understanding of the platform. + +## Agent-friendly documentation + +This docs site implements the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). Two endpoints make these docs directly consumable by agents: + +**[`/llms.txt`](/llms.txt)** — a discovery index listing every page with links to its clean markdown endpoint, plus the ICP skills registry URL. + +**`/.md`** — every page is available as clean markdown. HTML, navigation, and site chrome are stripped, leaving only the content. For example, this page is available at [`/guides/tools/ai-coding-agents.md`](/guides/tools/ai-coding-agents.md). + +A discovery link in every page's `` points to `/llms.txt`, so agents that crawl docs pages find the index automatically. + +## Programmatic access + +ICP skills are available without authentication: + +| Resource | URL | +|----------|-----| +| All skills (index) | `https://skills.internetcomputer.org/.well-known/skills/index.json` | +| Single skill | `https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.md` | +| Additional reference files | `https://skills.internetcomputer.org/.well-known/skills/{name}/references/{file}.md` | +| Skill zip bundle | `https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.zip` | +| Skills discovery index | `https://skills.internetcomputer.org/llms.txt` | + + +## Next steps + +- [skills.internetcomputer.org](https://skills.internetcomputer.org) — browse all available ICP skills +- [Developer tools overview](overview.md) — icp-cli, CDKs, and other tools in the ICP toolchain +- [Quickstart](../../getting-started/quickstart.md) — deploy your first canister with icp-cli +- [Migrating from dfx](migrating-from-dfx.md) — upgrade an existing project from the legacy dfx tool + + diff --git a/docs/index.mdx b/docs/index.mdx index d9b1c9cc..7273627c 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -29,7 +29,7 @@ Teach your AI agent canister patterns, token standards, CLI commands, and deploy
-Browse ICP skills +Learn more