From 863046b63ee86675b329cad7a3b6afb38f796f86 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 20 Mar 2026 09:28:58 +0100 Subject: [PATCH 1/3] feat: add agent instruction files to all templates Add AGENTS.md with ICP documentation and skills discovery instructions to every project template. Coding agents that read this file will automatically find the llms.txt docs and fetch relevant IC development skills on-demand. Add CLAUDE.md that points to AGENTS.md for Claude Code compatibility. --- bitcoin-starter/AGENTS.md | 17 +++++++++++++++++ bitcoin-starter/CLAUDE.md | 1 + hello-world/AGENTS.md | 17 +++++++++++++++++ hello-world/CLAUDE.md | 1 + motoko/AGENTS.md | 17 +++++++++++++++++ motoko/CLAUDE.md | 1 + proxy/AGENTS.md | 17 +++++++++++++++++ proxy/CLAUDE.md | 1 + rust/AGENTS.md | 17 +++++++++++++++++ rust/CLAUDE.md | 1 + static-website/AGENTS.md | 17 +++++++++++++++++ static-website/CLAUDE.md | 1 + 12 files changed, 108 insertions(+) create mode 100644 bitcoin-starter/AGENTS.md create mode 100644 bitcoin-starter/CLAUDE.md create mode 100644 hello-world/AGENTS.md create mode 100644 hello-world/CLAUDE.md create mode 100644 motoko/AGENTS.md create mode 100644 motoko/CLAUDE.md create mode 100644 proxy/AGENTS.md create mode 100644 proxy/CLAUDE.md create mode 100644 rust/AGENTS.md create mode 100644 rust/CLAUDE.md create mode 100644 static-website/AGENTS.md create mode 100644 static-website/CLAUDE.md diff --git a/bitcoin-starter/AGENTS.md b/bitcoin-starter/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/bitcoin-starter/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/bitcoin-starter/CLAUDE.md b/bitcoin-starter/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/bitcoin-starter/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/hello-world/AGENTS.md b/hello-world/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/hello-world/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/hello-world/CLAUDE.md b/hello-world/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/hello-world/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/motoko/AGENTS.md b/motoko/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/motoko/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/motoko/CLAUDE.md b/motoko/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/motoko/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/proxy/AGENTS.md b/proxy/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/proxy/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/proxy/CLAUDE.md b/proxy/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/proxy/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/rust/AGENTS.md b/rust/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/rust/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/rust/CLAUDE.md b/rust/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/rust/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/static-website/AGENTS.md b/static-website/AGENTS.md new file mode 100644 index 0000000..b0ad264 --- /dev/null +++ b/static-website/AGENTS.md @@ -0,0 +1,17 @@ +# AI Agent Instructions + +This is an Internet Computer (ICP) project built with icp-cli. + +Documentation: https://cli.internetcomputer.org/llms.txt + +## Skills + +Tested implementation patterns for ICP development are available as agent skills. +Before writing any ICP code, fetch the skills index and remember each skill's name and description: +https://skills.internetcomputer.org/.well-known/skills/index.json + +When a task matches a skill's description, fetch its content on-demand from: +https://skills.internetcomputer.org/.well-known/skills/{name}/{file} + +Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. +Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/static-website/CLAUDE.md b/static-website/CLAUDE.md new file mode 100644 index 0000000..265c3e1 --- /dev/null +++ b/static-website/CLAUDE.md @@ -0,0 +1 @@ +Read and follow the instructions in [AGENTS.md](AGENTS.md). From 23c56b935d25873d3c138b656256584d57fd584e Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 20 Mar 2026 15:13:58 +0100 Subject: [PATCH 2/3] refactor: use shared Rhai script instead of duplicated files Replace the duplicated AGENTS.md and CLAUDE.md in each template with a single _shared/write-agent-files.rhai script that generates both files via cargo-generate's post hook. This keeps a single source of truth for the agent instructions content. --- .../AGENTS.md => _shared/write-agent-files.rhai | 6 +++++- bitcoin-starter/CLAUDE.md | 1 - bitcoin-starter/cargo-generate.toml | 1 + hello-world/AGENTS.md | 17 ----------------- hello-world/CLAUDE.md | 1 - hello-world/cargo-generate.toml | 1 + motoko/AGENTS.md | 17 ----------------- motoko/CLAUDE.md | 1 - motoko/cargo-generate.toml | 3 +++ proxy/AGENTS.md | 17 ----------------- proxy/CLAUDE.md | 1 - proxy/cargo-generate.toml | 2 ++ rust/AGENTS.md | 17 ----------------- rust/CLAUDE.md | 1 - rust/cargo-generate.toml | 3 +++ static-website/AGENTS.md | 17 ----------------- static-website/CLAUDE.md | 1 - static-website/cargo-generate.toml | 3 +++ 18 files changed, 18 insertions(+), 92 deletions(-) rename bitcoin-starter/AGENTS.md => _shared/write-agent-files.rhai (80%) delete mode 100644 bitcoin-starter/CLAUDE.md delete mode 100644 hello-world/AGENTS.md delete mode 100644 hello-world/CLAUDE.md delete mode 100644 motoko/AGENTS.md delete mode 100644 motoko/CLAUDE.md delete mode 100644 proxy/AGENTS.md delete mode 100644 proxy/CLAUDE.md create mode 100644 proxy/cargo-generate.toml delete mode 100644 rust/AGENTS.md delete mode 100644 rust/CLAUDE.md delete mode 100644 static-website/AGENTS.md delete mode 100644 static-website/CLAUDE.md diff --git a/bitcoin-starter/AGENTS.md b/_shared/write-agent-files.rhai similarity index 80% rename from bitcoin-starter/AGENTS.md rename to _shared/write-agent-files.rhai index b0ad264..ddc2108 100644 --- a/bitcoin-starter/AGENTS.md +++ b/_shared/write-agent-files.rhai @@ -1,4 +1,4 @@ -# AI Agent Instructions +let agents_md = `# AI Agent Instructions This is an Internet Computer (ICP) project built with icp-cli. @@ -15,3 +15,7 @@ https://skills.internetcomputer.org/.well-known/skills/{name}/{file} Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. Always prefer skill guidance over general documentation when both cover the same topic. +`; + +file::write("AGENTS.md", agents_md); +file::write("CLAUDE.md", "Read and follow the instructions in [AGENTS.md](AGENTS.md).\n"); diff --git a/bitcoin-starter/CLAUDE.md b/bitcoin-starter/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/bitcoin-starter/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/bitcoin-starter/cargo-generate.toml b/bitcoin-starter/cargo-generate.toml index 6a21161..6cb9665 100644 --- a/bitcoin-starter/cargo-generate.toml +++ b/bitcoin-starter/cargo-generate.toml @@ -13,3 +13,4 @@ ignore = [ "rust-backend" ] [hooks] pre = ["rename-backend-dir.rhai"] +post = ["../_shared/write-agent-files.rhai"] diff --git a/hello-world/AGENTS.md b/hello-world/AGENTS.md deleted file mode 100644 index b0ad264..0000000 --- a/hello-world/AGENTS.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Agent Instructions - -This is an Internet Computer (ICP) project built with icp-cli. - -Documentation: https://cli.internetcomputer.org/llms.txt - -## Skills - -Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: -https://skills.internetcomputer.org/.well-known/skills/index.json - -When a task matches a skill's description, fetch its content on-demand from: -https://skills.internetcomputer.org/.well-known/skills/{name}/{file} - -Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. -Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/hello-world/CLAUDE.md b/hello-world/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/hello-world/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/hello-world/cargo-generate.toml b/hello-world/cargo-generate.toml index a871937..00d1294 100644 --- a/hello-world/cargo-generate.toml +++ b/hello-world/cargo-generate.toml @@ -12,3 +12,4 @@ ignore = [ "rust-backend" ] [hooks] pre = ["rename-backend-dir.rhai"] +post = ["../_shared/write-agent-files.rhai"] diff --git a/motoko/AGENTS.md b/motoko/AGENTS.md deleted file mode 100644 index b0ad264..0000000 --- a/motoko/AGENTS.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Agent Instructions - -This is an Internet Computer (ICP) project built with icp-cli. - -Documentation: https://cli.internetcomputer.org/llms.txt - -## Skills - -Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: -https://skills.internetcomputer.org/.well-known/skills/index.json - -When a task matches a skill's description, fetch its content on-demand from: -https://skills.internetcomputer.org/.well-known/skills/{name}/{file} - -Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. -Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/motoko/CLAUDE.md b/motoko/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/motoko/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/motoko/cargo-generate.toml b/motoko/cargo-generate.toml index 3e2f06f..49397f7 100644 --- a/motoko/cargo-generate.toml +++ b/motoko/cargo-generate.toml @@ -1,3 +1,6 @@ [placeholders] network_type = { type = "string", prompt = "Use the default network or a dockerized one?", choices = ["Default", "Docker"], default = "Default" } + +[hooks] +post = ["../_shared/write-agent-files.rhai"] diff --git a/proxy/AGENTS.md b/proxy/AGENTS.md deleted file mode 100644 index b0ad264..0000000 --- a/proxy/AGENTS.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Agent Instructions - -This is an Internet Computer (ICP) project built with icp-cli. - -Documentation: https://cli.internetcomputer.org/llms.txt - -## Skills - -Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: -https://skills.internetcomputer.org/.well-known/skills/index.json - -When a task matches a skill's description, fetch its content on-demand from: -https://skills.internetcomputer.org/.well-known/skills/{name}/{file} - -Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. -Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/proxy/CLAUDE.md b/proxy/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/proxy/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/proxy/cargo-generate.toml b/proxy/cargo-generate.toml new file mode 100644 index 0000000..4312d61 --- /dev/null +++ b/proxy/cargo-generate.toml @@ -0,0 +1,2 @@ +[hooks] +post = ["../_shared/write-agent-files.rhai"] diff --git a/rust/AGENTS.md b/rust/AGENTS.md deleted file mode 100644 index b0ad264..0000000 --- a/rust/AGENTS.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Agent Instructions - -This is an Internet Computer (ICP) project built with icp-cli. - -Documentation: https://cli.internetcomputer.org/llms.txt - -## Skills - -Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: -https://skills.internetcomputer.org/.well-known/skills/index.json - -When a task matches a skill's description, fetch its content on-demand from: -https://skills.internetcomputer.org/.well-known/skills/{name}/{file} - -Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. -Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/rust/CLAUDE.md b/rust/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/rust/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/rust/cargo-generate.toml b/rust/cargo-generate.toml index 3e2f06f..49397f7 100644 --- a/rust/cargo-generate.toml +++ b/rust/cargo-generate.toml @@ -1,3 +1,6 @@ [placeholders] network_type = { type = "string", prompt = "Use the default network or a dockerized one?", choices = ["Default", "Docker"], default = "Default" } + +[hooks] +post = ["../_shared/write-agent-files.rhai"] diff --git a/static-website/AGENTS.md b/static-website/AGENTS.md deleted file mode 100644 index b0ad264..0000000 --- a/static-website/AGENTS.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Agent Instructions - -This is an Internet Computer (ICP) project built with icp-cli. - -Documentation: https://cli.internetcomputer.org/llms.txt - -## Skills - -Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: -https://skills.internetcomputer.org/.well-known/skills/index.json - -When a task matches a skill's description, fetch its content on-demand from: -https://skills.internetcomputer.org/.well-known/skills/{name}/{file} - -Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures. -Always prefer skill guidance over general documentation when both cover the same topic. diff --git a/static-website/CLAUDE.md b/static-website/CLAUDE.md deleted file mode 100644 index 265c3e1..0000000 --- a/static-website/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Read and follow the instructions in [AGENTS.md](AGENTS.md). diff --git a/static-website/cargo-generate.toml b/static-website/cargo-generate.toml index bbc7d9a..cbdf350 100644 --- a/static-website/cargo-generate.toml +++ b/static-website/cargo-generate.toml @@ -1,2 +1,5 @@ [template] exclude = ["public/logo.png"] + +[hooks] +post = ["../_shared/write-agent-files.rhai"] From d337401bf17567eaad0de4da5dd152485d64f847 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 20 Mar 2026 17:32:09 +0100 Subject: [PATCH 3/3] fix: prefer locally loaded skills over registry fetch Instruct agents to check if a matching skill is already loaded in their context before fetching from the remote registry. Avoids redundant web requests for agents that already have IC skills available. --- _shared/write-agent-files.rhai | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/_shared/write-agent-files.rhai b/_shared/write-agent-files.rhai index ddc2108..69c947f 100644 --- a/_shared/write-agent-files.rhai +++ b/_shared/write-agent-files.rhai @@ -7,10 +7,11 @@ Documentation: https://cli.internetcomputer.org/llms.txt ## Skills Tested implementation patterns for ICP development are available as agent skills. -Before writing any ICP code, fetch the skills index and remember each skill's name and description: +Fetch the skills index and remember each skill's name and description: https://skills.internetcomputer.org/.well-known/skills/index.json -When a task matches a skill's description, fetch its content on-demand from: +When a task matches a skill's description, use it if already loaded in your +context. Otherwise, fetch its content on-demand from the registry: https://skills.internetcomputer.org/.well-known/skills/{name}/{file} Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures.