docs: AI Coding Agents guide (replaces Agentic Development)

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)
 
 <!-- Upstream: hand-written -->

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
 
 <!-- Upstream: informed by dfinity/icp-cli docs/quickstart.md, docs/tutorial.md -->

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.
+
+<!-- Upstream: hand-written -->

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.
+
+**`/<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/tools/ai-coding-agents.md`](/guides/tools/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 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
+
+<!-- Upstream: informed by dfinity/icskills — README.md, skills/*/SKILL.md -->

docs/index.mdx

@@ -29,7 +29,7 @@ Teach your AI agent canister patterns, token standards, CLI commands, and deploy
 
 <div class="skills-actions">
 <button class="skills-primary" id="skills-give-btn"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg><span id="skills-give-label">Give your agent ICP skills</span></button>
-<a class="skills-cta" href="https://skills.internetcomputer.org"><span>Browse ICP skills</span><svg class="arrow-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="7" y1="17" x2="17" y2="7"></line><polyline points="7 7 17 7 17 17"></polyline></svg></a>
+<a class="skills-cta" href="/guides/tools/ai-coding-agents/"><span>Learn more</span><svg class="arrow-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"></polyline></svg></a>
 </div>
 
 </div>