docs: update docs to reflect Skills Discovery RFC changes from #65 (#68)

Replace stale references to `.well-known/agent.json` and `/skills/{name}.md`
with the new `.well-known/skills/` endpoints. Also rename ApiTab → AccessTab
in project structure, and add agent-first writing callout to CONTRIBUTING.md.

Author: marc0olo

.claude/CLAUDE.md

@@ -4,7 +4,7 @@ This repository contains agent-readable skill files for the Internet Computer. E
 
 ## Key Rules
 
-- **`llms.txt`, `llms-full.txt`, `.well-known/agent.json`, and `sitemap.xml`** are all generated by Astro at build time into `dist/`. They are NOT committed to git.
+- **`llms.txt`, `llms-full.txt`, `.well-known/skills/`, and `sitemap.xml`** are all generated by Astro at build time into `dist/`. They are NOT committed to git.
 - **Never edit Astro source files to add or update a skill** — the website auto-discovers skills from SKILL.md frontmatter at build time. Only edit `src/` files for site-level UI changes.
 - **One skill = one file** at `skills/<skill-name>/SKILL.md`. No nested directories, no images, no external dependencies within a skill.
 - Skill names are **lowercase, hyphenated** (e.g., `ckbtc`, `https-outcalls`, `stable-memory`) and must match the directory name. This aligns with the [Agent Skills spec](https://agentskills.io/specification).
@@ -72,16 +72,15 @@ src/                           # Astro site source
   layouts/BaseLayout.astro    # HTML shell, meta tags, JSON-LD
   layouts/SiteLayout.astro    # Shared header/nav/footer for main pages
   components/BrowseTab.tsx    # Preact island: search + skill grid
-  components/ApiTab.tsx       # Preact island: access/endpoints reference
+  components/AccessTab.tsx    # Preact island: access/endpoints reference
   components/SkillHeader.tsx  # Preact island: skill detail header
   pages/index.astro           # Browse page
   pages/how-it-works/         # How it works page (fully static)
   pages/access/               # Access reference page (real endpoints)
   pages/skills/[slug]/        # Dynamic skill pages (pre-rendered)
-  pages/skills/[slug].md.ts   # Raw .md endpoint per skill
   pages/llms.txt.ts           # Skills index for agents
   pages/llms-full.txt.ts      # All skills concatenated
-  pages/.well-known/          # Agent discovery manifests
+  pages/.well-known/skills/   # Skills Discovery RFC endpoints (index.json + per-skill SKILL.md)
 public/                        # Static assets (favicon, etc.)
 astro.config.mjs              # Astro configuration
 ```

CONTRIBUTING.md

@@ -22,6 +22,8 @@ npm ci    # Install dependencies
 
 ## Adding a New Skill
 
+> **Skills are written for AI agents, not humans.** Every decision — structure, wording, level of detail — should optimize for machine consumption. Be explicit and literal: exact canister IDs, exact function signatures, exact error strings. Do not summarize, hand-wave, or link out when you can inline the information. An agent cannot click a link or interpret vague guidance.
+
 ### 1. Create the skill directory
 
 ```
@@ -123,7 +125,7 @@ This runs automatically in CI and blocks deployment on errors.
 
 ### 4. That's it — the website auto-discovers skills
 
-The website is automatically generated from the SKILL.md frontmatter at build time. You do **not** need to edit any source file. Astro reads all `skills/*/SKILL.md` files, parses their frontmatter, and generates the site pages, `llms.txt`, `agent.json`, and other discovery files.
+The website is automatically generated from the SKILL.md frontmatter at build time. You do **not** need to edit any source file. Astro reads all `skills/*/SKILL.md` files, parses their frontmatter, and generates the site pages, `llms.txt`, discovery endpoints, and other files.
 
 Stats (skill count, categories) all update automatically.
 

README.md

@@ -69,9 +69,9 @@ The files are plain markdown — paste into any system prompt, rules file, or co
 | Skill index | [`llms.txt`](https://dfinity.github.io/icskills/llms.txt) | Short index with links to each skill |
 | All skills | [`llms-full.txt`](https://dfinity.github.io/icskills/llms-full.txt) | All skills concatenated for direct context injection |
 | Single skill | `https://raw.githubusercontent.com/dfinity/icskills/main/skills/{name}/SKILL.md` | Raw markdown for one skill |
-| Agent discovery | [`.well-known/agent.json`](https://dfinity.github.io/icskills/.well-known/agent.json) | Machine-readable skill manifest |
+| Skills discovery | [`.well-known/skills/index.json`](https://dfinity.github.io/icskills/.well-known/skills/index.json) | Machine-readable skill index ([Cloudflare Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)) |
+| Single skill (API) | `/.well-known/skills/{name}/SKILL.md` | Raw markdown via discovery endpoint |
 | Skill page (HTML) | [`/skills/{name}/`](https://dfinity.github.io/icskills/skills/ckbtc/) | Pre-rendered skill page with full SEO |
-| Skill page (MD) | [`/skills/{name}.md`](https://dfinity.github.io/icskills/skills/ckbtc.md) | Raw markdown served with `text/markdown` content type |
 | CLI | `npx skills add dfinity/icskills` | Browse and install skills via [skills.sh](https://skills.sh) |
 
 ## Contributing
@@ -88,7 +88,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or update skills.
 - **Validation**: Structural linter for frontmatter and code blocks (`npm run validate`)
 - **Schema**: JSON Schema for frontmatter at `skills/skill.schema.json`
 - **SEO**: Per-skill meta tags, JSON-LD (TechArticle), sitemap, canonical URLs
-- **AI Agent Discovery**: `llms.txt`, `llms-full.txt`, `.well-known/agent.json`, per-skill `.md` endpoints
+- **Skills Discovery**: `llms.txt`, `llms-full.txt`, `.well-known/skills/` ([Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc))
 
 ## License