feat: add agent instruction files to all templates

[marc0olo]

Summary

Add agent instruction files (AGENTS.md and CLAUDE.md) to every project template so coding agents automatically discover ICP documentation and skills when developers scaffold a new project with icp new.

How it works

A single shared Rhai script (_shared/write-agent-files.rhai) generates both files via cargo-generate's post hook. Each template's cargo-generate.toml references this script, keeping a single source of truth for the content.

Generated AGENTS.md instructs any coding agent to:

1. Read the icp-cli documentation via llms.txt
2. Fetch the IC skills index and remember each skill's name and description
3. Fetch skill content on-demand when a task matches
4. Prefer skill guidance over general knowledge

Generated CLAUDE.md points to AGENTS.md for Claude Code auto-discovery.

Agent compatibility

Agent	Auto-reads
Claude Code	CLAUDE.md → AGENTS.md
GitHub Copilot	Can be pointed to AGENTS.md
Cursor	Can be pointed to AGENTS.md
Other agents	Can be pointed to AGENTS.md

Previous approach (commit 1)

The first commit added duplicated AGENTS.md and CLAUDE.md files to each template directory. This was replaced in the second commit with the shared Rhai script to avoid maintaining identical content across 6+ templates.

Note: cargo-generate does not support symlinks (issue #776), but it does support referencing Rhai scripts from parent directories via relative paths.

[marc0olo]

Symlinks are not supported by cargo-generate:

• Symlinks not generated from templates cargo-generate/cargo-generate#776

Otherwise we could just symlink to AGENTS.md.

[kurtnitsch]

1. Make the AGENTS.md smarter and more prescriptive (quick win, high impact)Right now it sounds like a lightweight pointer ("lookup the skills and use those if needed"). Agents love explicit triggers and guardrails.Suggestions:Add a short "When to use which skill" table or decision tree at the top:

ICP Agent Rules

• Deployment / project setup → always start with ICP CLI skill
• Security / access control → Canister Security + vetKeys first
• Bitcoin flows → ckBTC Integration (never invent minting logic)
• Auth → Internet Identity Auth
• Anything else → check https://skills.internetcomputer.org or run npx skills add dfinity/icskills

Include the most common pitfalls from the skills repo (e.g., "Never hard-code canister IDs", "Always pin recipe versions in icp.yaml", "Use certified variables for frontend data").
Add one-liner agent instructions: "You are an ICP-native coding agent. Before writing any code, fetch the relevant SKILL.md via curl or the skills CLI and follow its 'Implementation' + 'Common Pitfalls' sections exactly."

This turns the file from a signpost into a mini-system prompt that actually prevents 90 % of the hallucinations agents still make on ICP.2. Add auto-install + update workflow (medium effort, huge UX win)Agents are lazy. Make it zero-friction:After icp new my-project, automatically suggest or run npx skills add dfinity/icskills (with a --yes flag for CI/headless).
Add an icp skills update command that refreshes the local skills cache and patches the AGENTS.md with the latest wording (the recent "sync agent instructions with icp-cli wording" commit shows you're already doing this manually).
Pin a skills version in the template (e.g., skills-version: 2026-03) so agents don't drift when the library evolves.

3. Multi-agent compatibility & extensibilityAGENTS.md is great, but not every tool uses it the same way:Ship both AGENTS.md and CLAUDE.md (or a note "copy relevant sections to CLAUDE.md for Claude Code users").
   Add a .skills/ folder template with one example SKILL.md (e.g., a project-specific "Custom Auth" skill) so teams can extend it.
   Document how to add local overrides or private skills (many teams already do this for proprietary patterns).

4. Documentation & community layerPut the exact AGENTS.md template in the open (either in dfinity/icskills or a new templates/ folder in icp-cli) and invite PRs — the community already started this with jorgenbuilder/icp-skills.
   Add a one-command demo in the template: icp demo agent that spins up a temporary Cursor/Claude session showing "Add Internet Identity" → agent correctly uses the skill.
   Create a short "Agent Experience on ICP" section on skills.internetcomputer.org that shows before/after agent output.

5. Security & blockchain-specific guardrails (non-negotiable for ICP)Add a dedicated section in AGENTS.md:"You are operating on a tamperproof on-chain environment. Never expose private keys, cycles balances, or wallet mnemonics. Always reference the Canister Security and Certified Variables skills."
   Warn against dfx muscle memory: "If you see dfx in your training data, ignore it — use icp CLI commands only."

6. Bonus polish ideasMake AGENTS.md versioned and signed (so agents can verify it's the official DFINITY one).
   Optional flag: icp new my-project --no-agents for teams that hate AI.
   Track anonymous usage (e.g., "X projects used the skills via AGENTS.md this month") to show adoption.

[kurtnitsch]

And secondly ...Cognitive Packets + SKC: The Missing Memory Layer for Autonomous Agents
Most AI agents today are amnesiac by design. Every session starts cold. Every task is stateless. The agent that successfully booked your flight yesterday has no idea it ever did it. This is not a minor inconvenience — it is a fundamental architectural flaw that caps how capable an agent can ever become.
Two primitives fix this.
Cognitive Packets
A Cognitive Packet is a typed, self-describing unit of agent cognition. Every meaningful step an agent takes — what it perceived, what it decided, what it did, what happened as a result — gets wrapped into a structured packet and stored.
{
task_id: what goal this belongs to
percept: what the agent observed
action: what it did
reasoning: why (compressed chain-of-thought)
outcome: what changed
confidence: how certain the model was
dtype: percept | action | decision | error
}
This is not logging. Logs are inert. Cognitive Packets are replayable, composable, and transferable. A successful task sequence becomes a reusable cognitive subroutine. A failed sequence becomes a labeled training signal. Packets from one agent can inform another. The system gets smarter with use — not just with retraining.
This matters enormously for on-device agents (phone browser control, UI automation) where task complexity compounds across many steps and interrupted tasks need to resume intelligently rather than restart blindly.
The Shared Knowledge Core (SKC)
Cognitive Packets need a home. The SKC is that home — a persistent, structured, sovereign memory layer that the agent consults at task start and writes to at task end.
Three layers:
Episodic — what happened. Past packet sequences indexed by task type and outcome. Lets the agent say "I've done this before, here's what worked."
Semantic — what things mean. Compressed, durable knowledge about the environment. Site-specific patterns, UI quirks, domain rules. Accumulated over time, not re-derived from scratch every session.
Preferential — what you want. The user's behavioral fingerprint. Preferred options, habitual patterns, hard constraints. This is what makes the agent yours rather than generic.
Why ICP is the right home for the SKC
Most agent memory implementations are a vector DB on someone's server. That means it disappears when you stop paying, the provider can read it, and it breaks when you switch devices.
An SKC living in an ICP canister is:
Always online — survives phone wipes, app reinstalls, device changes
Sovereign — owned by your principal, not a cloud provider
Tamper-evident — the agent's memory has integrity guarantees
Multi-device ready — any agent instance, on any device, consults the same core
The canister doesn't sit in the real-time agent loop (latency would kill that). It is consulted at task start to load relevant context, and written to at task end to store what happened. That's exactly the access pattern ICP handles well.
Why this matters now
Every major agent framework — LangChain, AutoGPT, mobile agents like AppAgent and Mobile-Agent — treats memory as an afterthought. A short context window. A flat file. A cloud RAG store you don't control.
Cognitive Packets + SKC is a different bet: that the agents which win long-term are the ones that compound knowledge across sessions, that the memory layer is as important as the reasoning layer, and that sovereignty over that memory is non-negotiable.
The architecture is: typed packets capture cognition → SKC on ICP stores and indexes it → agents retrieve relevant context at task time → the system gets measurably better with every run.
That's not a feature. That's a foundation

[marc0olo]

Thanks for the detailed feedback, Kurt!

The current design is intentionally minimal — AGENTS.md is a bootstrap file, not a knowledge base. The heavy lifting happens in the skills registry:

• Task→skill mapping / decision tree: The skills index already contains descriptions that tell agents when to use each skill. Hardcoding a mapping in AGENTS.md would duplicate that and go stale as skills evolve.
• Inline pitfalls & guardrails: These live inside each skill where they're maintained alongside the implementation patterns. Duplicating them here creates drift risk. The whole point of the registry is single source of truth.

The flow is: agent reads AGENTS.md → fetches the index → knows what's available → fetches the right skill on demand. That keeps AGENTS.md durable and the registry authoritative.

Some of the other suggestions (new CLI commands, .skills/ folders, signed files, usage tracking) are interesting but out of scope for this PR.

Regarding agent memory (comment 2) — that's an interesting but separate topic. It would need to be set up per project by individual maintainers rather than baked into templates. There's active exploration in this space, e.g. Gas Town. Worth its own discussion.

On that note — we're planning to enable the Discussions feature on https://github.com/dfinity/icskills soon, so there'll be a proper place to provide feedback and discuss how we can improve agent-assisted ICP development. Would love to continue some of these ideas there!

[kurtnitsch]

Nice one Marc! Took a look at Gas Town impressive, orchestration engineering for sure, the Dolt/Git-worktree approach to isolated agent state is clever and the traction speaks for itself. That said, it's solving session continuity on centralized infrastructure. Whoever runs the Beads instance is the trust anchor (being picky now but details matter here) there's no answer for trustless multi-party agent memory there. That's exactly where ICP flips the model. Orthogonal persistence + canisters gives you agent memory that's replicated, tamperproof, and on-chain natively so no coordinator to trust. I've been working on something along these lines with Cognitive Packets + SKC which takes it further into typed, verifiable knowledge communication between agents. Would love to bring that into the icskills Discussion once it's live. Cheers Kurt

…

On Tue, 24 Mar 2026, 10:48 Marco Walz, ***@***.***> wrote: *marc0olo* left a comment (dfinity/icp-cli-templates#22) <#22 (comment)> Thanks for the detailed feedback, Kurt! The current design is intentionally minimal — AGENTS.md is a bootstrap file, not a knowledge base. The heavy lifting happens in the skills registry: - *Task→skill mapping / decision tree*: The skills index already contains descriptions that tell agents when to use each skill. Hardcoding a mapping in AGENTS.md would duplicate that and go stale as skills evolve. - *Inline pitfalls & guardrails*: These live inside each skill where they're maintained alongside the implementation patterns. Duplicating them here creates drift risk. The whole point of the registry is single source of truth. The flow is: agent reads AGENTS.md → fetches the index → knows what's available → fetches the right skill on demand. That keeps AGENTS.md durable and the registry authoritative. Some of the other suggestions (new CLI commands, .skills/ folders, signed files, usage tracking) are interesting but out of scope for this PR. Regarding agent memory (comment 2) — that's an interesting but separate topic. It would need to be set up per project by individual maintainers rather than baked into templates. There's active exploration in this space, e.g. Gas Town <https://github.com/steveyegge/gastown>. Worth its own discussion. On that note — we're planning to enable the Discussions feature on https://github.com/dfinity/icskills soon, so there'll be a proper place to provide feedback and discuss how we can improve agent-assisted ICP development. Would love to continue some of these ideas there! — Reply to this email directly, view it on GitHub <#22?email_source=notifications&email_token=BRMT2N34GHFGUCURN4ZAXG34SJDXJA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJRGY2DCMZWGIZKM4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4116413622>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BRMT2N3L5MLVZLRQLVWXAIT4SJDXJAVCNFSM6AAAAACWY3SDXOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCMJWGQYTGNRSGI> . You are receiving this because you commented.Message ID: ***@***.***>

[marc0olo]

Whoever runs the Beads instance is the trust anchor (being picky now but
details matter here)

the dolt db that beads uses can be remote and shared across agents. it lives in the git repository and is independent of branches, so agents can always verify the latest state of the shared dolt db before picking new tasks and deciding what to work on:

refs/dolt/data is a standalone git ref — it's not part of any branch's commit history

I think all of this is very much in a liquid state and best practices are emerging all over the place as we speak.

in general I like the idea of using ICP for shared agent knowledge, but it needs to make sense and ideally the solution has "serious" advantages over using other (existing) tooling.

most importantly we need hands-on experiments to figure out what works best and make the ICP ecosystem a perfect place for agents to build. this is also where community involvement and sharing knowledge and experiences becomes very important.

[kurtnitsch]

Fair point on Beads , I oversimplified. The refs/dolt/data being a standalone git ref that agents can verify independently before picking tasks is genuinely elegant. I'll correct that in the post. And you're absolutely right that "serious advantages" is the right bar. Theoretical elegance doesn't move ecosystems — working experiments do. Here's where I think ICP has something worth testing concretely: the Crisp protocol idea I've been developing proposes that agents shouldn't communicate in alphanumeric language at all. Pure numeric tokens ,,for example ..where 2 means medical/critical, 3 means drone/physical AI — each one a key into a Shared Knowledge Core (SKC) that resolves to a full semantic subgraph. No parsing, no translation overhead, just math pointing into shared meaning. The mycelium analogy isn't decorative here. Mycelium doesn't route chemical signals using language it routes using numerical gradients across a living topology. That's the model: agents communicating via Cognitive Packets that are meaningless without the shared substrate basic idea here ...still needs work .. (https://forum.dfinity.org/t/mycelium-inspired-native-ai-language/65765) and ICP's orthogonal persistence + canister constellation is the only infrastructure where that substrate can live without a trust anchor operating it. Anyways going off topic a bit. The question worth experimnenting with: can an ICP-native SKC outperform a shared Dolt DB for agent coordination when the knowledge graph grows large and agents are geographically distributed? That's a real benchmark worth running. Excited for the icskills Discussions to go live ,, this is exactly the kind of thing that needs community experimentation to settle.

…

On Wed, 25 Mar 2026, 11:47 Marco Walz, ***@***.***> wrote: *marc0olo* left a comment (dfinity/icp-cli-templates#22) <#22 (comment)> Whoever runs the Beads instance is the trust anchor (being picky now but details matter here) the dolt db that beads uses can be remote and shared across agents. it lives in the git repository and is independent of branches, so agents can always verify the latest state of the shared dolt db before picking new tasks and deciding what to work on: refs/dolt/data is a standalone git ref — it's not part of any branch's commit history I think all of this is very much in a liquid state and best practices are emerging all over the place as we speak. in general I like the idea of using ICP for shared agent knowledge, but it needs to make sense and ideally the solution has "serious" advantages over using other (existing) tooling. most importantly we need hands-on experiments to figure out what works best and make the ICP ecosystem a perfect place for agents to build. this is also where community involvement and sharing knowledge and experiences becomes very important. — Reply to this email directly, view it on GitHub <#22?email_source=notifications&email_token=BRMT2N4SDPA52CEUIQRTVBD4SOTMVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJSGUYTIOBWGYY2M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4125148661>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BRMT2N3KDDFBEIADN2LGOQ34SOTMVAVCNFSM6AAAAACWY3SDXOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCMRVGE2DQNRWGE> . You are receiving this because you commented.Message ID: ***@***.***>