# AI coding agents

> For the complete documentation index, see [llms.txt](/llms.txt)

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, so it produces correct ICP code right away with nothing to install. When you use that prompt, the agent then offers to set up how your project keeps using skills going forward (fetch on demand, pin, or auto-update) and runs whatever the chosen option needs. Those options are described below, and you can also apply them yourself.

### Install skills into your project

Fetching on demand (above) needs no install and is the default. To make skills a committed part of a project instead, the agent offers to pin them or enable auto-updates when you follow the prompt above, and runs the setup for you. You can also do it manually:

**Pin them (any agent).** Version-lock skills into your repo with the `skills` CLI:

```bash
npx skills add dfinity/icskills
```

This detects your agent (Claude Code, Cursor, Windsurf, GitHub Copilot, and others), installs the skills into the right location, and writes a `skills-lock.json`. Refresh them later with `npx skills update`.

**Auto-update them (Claude Code).** Install the [`autosync-ic-skills`](https://skills.internetcomputer.org/.well-known/skills/autosync-ic-skills/SKILL.md) skill to add a `SessionStart` hook that keeps `.claude/skills/` mirroring the latest skills automatically, every session.

To fetch a single skill manually instead:

```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.

> **Scaffolding with icp-cli?** Projects generated by `icp new` ship an `AGENTS.md` that walks your agent through choosing one of these modes (fetch on demand, pin, or auto-update) and then configures itself. See [how that works](https://github.com/dfinity/icp-cli-templates/blob/main/AGENT_SKILLS.md).

## 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 open standard](https://agentskills.io/specification). Anthropic [published the SKILL.md format](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) in December 2025 to define a portable format that works across coding agents. The registry uses the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) so agents can auto-discover and load skills without manual configuration.

## How discovery works

However skills are set up, the pattern is the same: the agent matches your task to a skill by its description, follows that skill, and prefers its guidance over general knowledge when both cover the same topic. What differs is where the skill content comes from.

**On-demand (the default).** Following the `llms.txt` prompt, the agent:

1. fetches the skills index at `https://skills.internetcomputer.org/.well-known/skills/index.json`
2. reads each skill's name and description to understand what it covers
3. fetches the matching skill's `SKILL.md` from its URL when a task fits

Fetched this way, skills are always the latest version.

**Pinned or autosync.** The skills already live in the agent's skills directory (installed by `npx skills` or the autosync hook), so the agent discovers and loads them natively without fetching each time. Pinned uses the versions locked in `skills-lock.json`; autosync refreshes to the latest each session.

## 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.

**`/<path>.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/ai-coding-agents.md`](/guides/ai-coding-agents.md).

A discovery link in every page's `<head>` 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](../developer-tools/index.md): icp-cli, CDKs, and other tools in the ICP toolchain
- [Quickstart](../getting-started/quickstart.md): deploy your first canister with icp-cli