Migrate skills discovery from v0.1 to v0.2 (agent-skills-discovery-rfc)

[marc0olo]

Context

The Cloudflare Agent Skills Discovery RFC published draft v0.2.0 (PR #8, merged 2026-03-12) with breaking changes from v0.1.

We currently serve a v0.1-style index. We should migrate to v0.2 to stay spec-compliant and benefit from the improvements — notably the required url field, which directly prevents the URL construction failures we've observed (agents guessing wrong filenames instead of using SKILL.md).

What changed in v0.2

	v0.1 (current)	v0.2
Well-known path	/.well-known/skills/	/.well-known/agent-skills/
Version field	version	$schema (URI)
Skill entry fields	name, description, files	name, type, description, url, digest
files array	Present	Removed — single artifact per skill
type	N/A	Required: "skill-md" or "archive"
digest	N/A	Required: sha256:{hex} integrity hash

Path rename rationale: IANA's RFC 8615 discourages generic well-known paths. "skills" is too broad. Google's A2A had the same issue (agent.json → agent-card.json).

Migration checklist

Endpoints

• Add new endpoints at /.well-known/agent-skills/index.json and /.well-known/agent-skills/{name}/SKILL.md
• Update index.json schema: replace version with $schema, add type, url, digest fields, remove files array
• Keep /.well-known/skills/index.json alive serving identical content for backwards compatibility (old consumers follow url fields to new paths naturally)
• Plan deprecation of old path once external references are updated

llms.txt

• Update index URL to /.well-known/agent-skills/index.json
• Instructions should direct agents to use the url field from the index (already done in current improvements, just needs path update)

Multi-file skills

• icp-cli (references) and canhelp (scripts): use type: "skill-md" — agents discover references via relative paths in the SKILL.md body. No need for type: "archive" at this stage.
• The SKILL.zip endpoint can optionally be kept as a convenience but is not required by the spec.

External references to update

• icp-cli docs llms.txt — see Update llms.txt skills discovery instructions icp-cli#478
• icp-cli-templates AGENTS.md — see Update AGENTS.md skills discovery instructions icp-cli-templates#24
• Any other llms.txt or AGENTS.md files referencing /.well-known/skills/

Validation

• Ensure skill-validator supports v0.2 index format (or update it)
• Verify npx skills add dfinity/icskills still works after migration

Recommended external instructions format

For AGENTS.md and external llms.txt files, the skills section should be:

## Skills

Tested implementation patterns for ICP development are available as agent skills.

1. Fetch the skills index and remember each skill's name, description, and url:
   https://skills.internetcomputer.org/.well-known/agent-skills/index.json

2. When a task matches a skill\'s description, use it if already loaded in your
   context. Otherwise, fetch the skill content from its url.
   Do not construct skill URLs manually.

   Example: for the skill named "internet-identity", its url is:
   https://skills.internetcomputer.org/.well-known/agent-skills/internet-identity/SKILL.md

   If a response contains HTML instead of markdown, the URL is wrong.

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

Key principles:

• No URL templates ({name}/{file}) — agents misinterpret these and guess wrong filenames
• Direct agents to the url field in the index — machine-readable, no construction needed
• Concrete example anchors SKILL.md as a literal filename
• HTML detection hint helps agents identify wrong URLs (asset canister SPA fallback returns HTML for 404s)