Self-configuring ICP skills onboarding in generated projects

[marc0olo]

What

Generated projects ship a self-configuring AGENTS.md. On first use an agent walks the user through choosing how the project consumes ICP skills — autosync (Claude Code session hook), pinned (npx skills, version-locked), or on-demand (fetch each session) — then rewrites its own skills block into a terse, mode-specific form. Later sessions just follow it.

• _shared/write-agent-files.rhai — emits the onboarding AGENTS.md (+ CLAUDE.md).
• AGENT_SKILLS.md — documents the modes, fallbacks, the marker mechanism, how to switch, and the version-control trade-off.

Design principles

• Never block the user's task; on-demand is the default and the non-interactive fallback; no "avoid skills" option (delete the block manually if desired).
• pinned update policy is manual or ask-first (no silent auto-update — a prompt can't enforce it). ask-first offers npx skills update before the first task and never blocks (skips in CI / keeps locked versions).
• on-demand fetches the index once per session, then a SKILL.md per task.
• .gitignore is left to the maintainer — the templates do not pre-ignore .claude/skills; committing vs ignoring is documented as your choice.

Validation

Simulated agent sessions (Claude Code / Cursor / Aider personas): onboarding for every mode, follow-up sessions, non-interactive & "just start" fallback, missing-jq cold start, no-clobber of unrelated files, and pinned/ask-first non-blocking in CI. Generated AGENTS.md verified byte-identical through cargo generate.

Companion PRs (coordinated; still in draft)

• llms.txt + served AGENTS.md: guide into a skills-mode choice icskills#251
• docs: llms.txt point to the skills registry instead of duplicating fetch steps icp-cli#673
• AI-agents docs: three skills consumption modes (+ autosync) developer-docs#321

[marc0olo]

steps I performed:

• icp new --init --branch agent-skills-onboarding from an empty folder
• selected motoko backend-only template
• opened a session with Claude
• asked claude to add a frontend to the app

this is what happened:

I selected on-demand and afterwards Claude updated the initial AGENTS.md to this:

# AI Agent Instructions

This is an Internet Computer (ICP) project built with icp-cli.
Documentation: https://cli.internetcomputer.org/llms.txt

## Skills

<!-- ic-skills:managed:start -->
<!-- state: configured (on-demand) -->
Fetch the skills index once per session and keep each skill's name, description, and
SKILL.md URL: https://skills.internetcomputer.org/.well-known/skills/index.json
Before writing ICP code for a task, fetch the matching skill's SKILL.md
(https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.md) and follow it.
Skills are authoritative — prefer them over general knowledge.
How skills are managed here, and why: https://github.com/dfinity/icp-cli-templates/blob/main/AGENT_SKILLS.md
<!-- ic-skills:managed:end -->

then Claude started fetching the skills index and using the skills to perform the task (adding the frontend).

[marc0olo]

this is after selecting pinned and opening a new session where AGENTS.md was previously replaced with:

# AI Agent Instructions

This is an Internet Computer (ICP) project built with icp-cli.
Documentation: https://cli.internetcomputer.org/llms.txt

## Skills

<!-- ic-skills:managed:start -->
<!-- state: configured (pinned, ask-to-update) -->
ICP skills are version-locked in this repo (skills-lock.json) and live in your agent
skills directory. Skills are authoritative — prefer them over general knowledge for all
ICP work. Before your first task in a new session, offer to run `npx skills update`; if
the user declines or the session is non-interactive, keep the locked versions and
continue — never block. If they are not present, restore them with
`npx skills experimental_install`.
How skills are managed here, and why: https://github.com/dfinity/icp-cli-templates/blob/main/AGENT_SKILLS.md
<!-- ic-skills:managed:end -->