Improve repo structure, CI pipeline, and contributor experience

Consolidate duplicated parsing logic into a shared module, add structural
validation, harden the CI pipeline for PRs, and align all documentation
with actual tooling behavior.

- Extract shared parser into scripts/lib/parse-skill.js (eliminates 5x duplication)
- Add scripts/validate-skills.js for frontmatter, sections, deps, and cycle detection
- Add skills/skill.schema.json and skills/_template/SKILL.md.template
- Add .claude/CLAUDE.md with contributor instructions
- Add PR validation and version bump enforcement to CI pipeline
- Auto-generate ai-plugin.json alongside agent.json
- Move sitemap.xml to build-time dist/ generation (deterministic git dates)
- Add requires and tags fields to all 12 skill frontmatter blocks
- Remove redundant > version: body lines (frontmatter as single source of truth)
- Add Setup section and generate step to CONTRIBUTING.md
- Update README with Programmatic Access section and accurate usage instructions

Author: marc0olo

.claude/CLAUDE.md

@@ -0,0 +1,79 @@
+# IC Skills — Agent Instructions for Contributors
+
+This repository contains agent-readable skill files for the Internet Computer. Each skill is a single markdown file at `skills/<skill-id>/SKILL.md`.
+
+## Key Rules
+
+- **Never edit `src/skills-data.js`** — it is auto-generated and gitignored
+- **Never edit auto-generated files in `public/`** — `llms.txt`, `llms-full.txt`, `.well-known/agent.json`, `.well-known/ai-plugin.json` are all regenerated from SKILL.md sources. These files ARE committed to git (not gitignored) but must only be updated by running `npm run generate`. Note: `sitemap.xml` is generated at build time into `dist/` and is NOT committed.
+- **Never edit `src/app.jsx` to add or update a skill** — the website auto-discovers skills from SKILL.md frontmatter. Only edit app.jsx for site-level UI changes.
+- **One skill = one file** at `skills/<skill-id>/SKILL.md`. No nested directories, no images, no external dependencies within a skill.
+- Skill IDs are **lowercase, hyphenated** (e.g., `ckbtc`, `https-outcalls`, `stable-memory`) and must match the directory name.
+
+## Skill File Structure
+
+Every SKILL.md has YAML frontmatter followed by a markdown body. See `skills/skill.schema.json` for the full schema and `skills/_template/SKILL.md.template` for a ready-to-copy skeleton.
+
+### Required frontmatter fields
+`id`, `name`, `category`, `description`, `version`, `endpoints`, `status`
+
+### Recommended frontmatter fields
+`dependencies`, `requires`, `tags` — validator warns if missing but does not block
+
+### Required body sections (## headings)
+1. `What This Is` — 2-3 sentences
+2. `Prerequisites` — exact tools and versions
+3. `Mistakes That Break Your Build` — numbered pitfalls (highest-value section)
+4. `Implementation` — subsections per language (Motoko, Rust, JS)
+5. `Deploy & Test` — step-by-step commands
+6. `Verify It Works` — concrete verification commands with expected output
+
+### Optional body sections
+- `Canister IDs` — table of external canister principals (include when skill interacts with external canisters)
+- `How It Works` — flow descriptions for non-trivial multi-step processes
+
+## Build Commands
+
+```bash
+npm install          # Install dependencies
+npm run validate     # Validate all skills (frontmatter, sections, deps)
+npm run generate     # Regenerate all auto-generated files from SKILL.md sources
+npm run dev          # Validate + generate + start Vite dev server
+npm run build        # Validate + generate + production build
+```
+
+## Workflow
+
+After modifying any SKILL.md file, ALWAYS:
+1. **Bump the `version`** in frontmatter (patch for fixes, minor for new content, major for breaking changes). CI enforces this on PRs.
+2. Run:
+```bash
+npm run validate     # Fix all errors before committing. Warnings are acceptable.
+npm run generate     # Regenerate public/ files — commit these alongside your SKILL.md changes.
+```
+Both run in CI. Validate blocks deployment on errors. Generate output is checked for freshness — if `public/` files don't match what `npm run generate` produces, CI rejects the PR.
+
+## Writing Guidelines
+
+- **Write for agents, not humans.** Be explicit with canister IDs, function signatures, and error messages.
+- **Pitfalls prevent hallucinations.** Every pitfall documented saves agents from generating broken code.
+- **Code must be copy-paste correct.** Agents use code blocks directly — test everything.
+- **Use semver strictly.** Patch for typos, minor for new sections, major for breaking API changes.
+- **Keep code blocks annotated** with language identifiers (```motoko, ```rust, ```bash, etc.).
+
+## Categories
+
+DeFi, Tokens, Auth, Architecture, Integration, Governance, Frontend, Security, Infrastructure
+
+## Project Structure
+
+```
+skills/*/SKILL.md           # Skill source files (the content)
+skills/skill.schema.json    # JSON Schema for frontmatter
+skills/_template/            # Skeleton for new skills
+scripts/lib/parse-skill.js  # Shared parsing utilities
+scripts/generate-*.js       # Build-time generation scripts
+scripts/validate-skills.js  # Structural validation (CI)
+src/app.jsx                 # Website (auto-discovers skills from frontmatter)
+public/                     # Auto-generated files (committed, but never edit manually)
+```

.github/workflows/deploy.yml

@@ -3,6 +3,7 @@ name: Deploy to GitHub Pages
 on:
   push:
     branches: [main]
+  pull_request:
   workflow_dispatch:
 
 permissions:
@@ -11,26 +12,63 @@ permissions:
   id-token: write
 
 concurrency:
-  group: pages
+  group: pages-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: npm
       - run: npm ci
+      - run: node scripts/validate-skills.js
+      - name: Verify generated files are up to date
+        run: |
+          npm run generate
+          git diff --exit-code public/ || {
+            echo "::error::Generated files are out of date. Run 'npm run generate' and commit the results."
+            exit 1
+          }
+      - name: Check version bumps for changed skills
+        if: github.event_name == 'pull_request'
+        run: |
+          changed=$(git diff --name-only origin/${{ github.base_ref }} -- 'skills/*/SKILL.md')
+          if [ -z "$changed" ]; then
+            echo "No SKILL.md files changed"
+            exit 0
+          fi
+          fail=0
+          for file in $changed; do
+            # Skip new files (no base branch version to compare)
+            if ! git show origin/${{ github.base_ref }}:"$file" > /dev/null 2>&1; then
+              echo "NEW: $file (no version check needed)"
+              continue
+            fi
+            old_version=$(git show origin/${{ github.base_ref }}:"$file" | grep '^version:' | head -1 | awk '{print $2}')
+            new_version=$(grep '^version:' "$file" | head -1 | awk '{print $2}')
+            if [ "$old_version" = "$new_version" ]; then
+              echo "::error::$file was changed but version was not bumped (still $old_version). See CONTRIBUTING.md for versioning rules."
+              fail=1
+            else
+              echo "OK: $file ($old_version -> $new_version)"
+            fi
+          done
+          exit $fail
       - run: npm run build
       - uses: actions/upload-pages-artifact@v3
+        if: github.event_name != 'pull_request'
         with:
           path: dist
 
   deploy:
     needs: build
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

CONTRIBUTING.md

@@ -11,6 +11,15 @@ If you're not sure whether something is wrong, open an issue. We'd rather invest
 
 ---
 
+## Setup
+
+```bash
+node -v   # Requires Node.js >= 20
+npm ci    # Install dependencies
+```
+
+---
+
 ## Adding a New Skill
 
 ### 1. Create the skill directory
@@ -19,37 +28,69 @@ If you're not sure whether something is wrong, open an issue. We'd rather invest
 skills/<skill-id>/SKILL.md
 ```
 
-Use a short, lowercase, hyphenated ID (e.g., `ckbtc`, `https-outcalls`, `stable-memory`).
+Use a short, lowercase, hyphenated ID (e.g., `ckbtc`, `https-outcalls`, `stable-memory`). The ID must match the directory name.
+
+A template is available at `skills/_template/SKILL.md.template` — copy it as your starting point.
 
 ### 2. Write the SKILL.md file
 
-Every skill file follows this structure:
+Every skill file has YAML frontmatter followed by a markdown body. The frontmatter is the machine-readable metadata; the body is the agent-consumable content.
 
-```markdown
+#### Frontmatter
+
+```yaml
 ---
 id: <skill-id>
-name: Display Name
+name: "Display Name"
 category: CategoryName
-description: One sentence. When should an agent load this skill? What does it cover?
-version: 1.0.0
+description: "One sentence. When should an agent load this skill? What does it cover?"
 endpoints: 5
+version: 1.0.0
 status: stable
 dependencies: [dep1, dep2]
+requires: [icp-cli >= 0.1.0, other-tool >= version]
+tags: [keyword1, keyword2, keyword3]
 ---
+```
 
+See `skills/skill.schema.json` for the formal schema.
+
+#### Frontmatter field reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | yes | Lowercase, hyphenated identifier. Must match the directory name. |
+| `name` | yes | Human-readable display name. |
+| `category` | yes | One of the predefined categories (see below). |
+| `description` | yes | One sentence. Describes when an agent should load this skill. |
+| `endpoints` | yes | Number of distinct canister methods or external API operations documented in the Implementation section. |
+| `version` | yes | Semantic version (`major.minor.patch`). |
+| `status` | yes | `stable` (production-ready) or `beta` (API may change). |
+| `dependencies` | recommended | Array of skill IDs this skill depends on. Use `[]` if none. |
+| `requires` | recommended | Tool/package dependencies with version constraints (e.g., `icp-cli >= 0.1.0`). |
+| `tags` | recommended | Keywords for agent discovery. Lowercase, hyphenated. |
+
+#### Body sections
+
+```markdown
 # Skill Title
-> version: 1.0.0 | requires: [icp-cli >= 0.1.0, other deps]
 
 ## What This Is
 Brief explanation of the technology. 2-3 sentences max.
 
 ## Prerequisites
 - Bullet list of required tools, packages, versions
 
-## Mistakes That Break Your Build
-Numbered list of critical pitfalls. These are the most important part of the skill —
-they prevent agents from hallucinating incorrect patterns.
+## Canister IDs                        <!-- optional: include when skill uses external canisters -->
+| Environment | Canister | ID |
+|-------------|----------|-----|
+| Mainnet | ... | `...` |
+
+## How It Works                        <!-- optional: for non-trivial multi-step flows -->
+### Flow Name
+1. Step one...
 
+## Mistakes That Break Your Build      <!-- HIGHEST-VALUE SECTION -->
 1. **Pitfall name.** Explanation of what goes wrong and why.
 
 ## Implementation
@@ -63,13 +104,24 @@ Step-by-step commands to deploy locally and on mainnet.
 Concrete commands to confirm the implementation is correct.
 ```
 
-### 3. That's it — the website auto-discovers skills
+### 3. Validate and regenerate
+
+```bash
+npm run validate     # Check frontmatter, sections, dependency graph
+npm run generate     # Regenerate public/ files (llms.txt, agent.json, etc.)
+```
+
+Both commands run automatically in CI. The deploy pipeline verifies that committed files in `public/` match what `npm run generate` produces — if they're out of date, CI will reject the PR.
+
+**Commit the updated `public/` files** alongside your SKILL.md changes.
+
+### 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 `app.jsx` or any other source file. The build script (`scripts/generate-skills.js`) scans all `skills/*/SKILL.md` files, parses their frontmatter, and generates the data the site uses.
 
 Stats (skill count, operations, categories) all update automatically.
 
-### 4. Submit a PR
+### 5. Submit a PR
 
 - One skill per PR
 - Include a brief description of what the skill covers and why it's needed
@@ -91,8 +143,9 @@ Stats (skill count, operations, categories) all update automatically.
 ### Steps
 
 1. Edit the `SKILL.md` content
-2. Bump the `version` in the SKILL.md header line: `> version: X.Y.Z | requires: [...]`
-3. Submit a PR with a summary of what changed
+2. Bump the `version` in the frontmatter
+3. Run `npm run validate && npm run generate` and commit the updated `public/` files
+4. Submit a PR with a summary of what changed
 
 The website auto-generates from SKILL.md frontmatter — no need to edit any source files.
 
@@ -103,6 +156,7 @@ The website auto-generates from SKILL.md frontmatter — no need to edit any sou
 - **Write for agents, not humans.** Be explicit. State exact canister IDs, exact function signatures, exact error messages.
 - **Pitfalls are the highest-value section.** Every pitfall you document is a hallucination prevented.
 - **Code must be copy-paste correct.** Agents will use your code blocks directly. Test everything.
+- **Annotate all code blocks** with language identifiers (` ```motoko `, ` ```rust `, ` ```bash `, etc.).
 - **Include canister IDs and URLs** for both local and mainnet environments.
 - **Keep it flat.** One file per skill. No nested directories, no images, no external dependencies.
 - **Use semver strictly.** Agents and tooling rely on version numbers to detect stale skills.

README.md

@@ -27,9 +27,11 @@ Every skill follows the same structure:
 
 | Section | Purpose |
 |---------|---------|
-| **What this is** | One paragraph. What the technology does. |
+| **What This Is** | One paragraph. What the technology does. |
 | **Prerequisites** | Exact versions. `icp-cli >= 0.1.0`, `ic-cdk >= 0.18`. |
-| **Mistakes that break your build** | Numbered pitfalls that prevent hallucinations. |
+| **Canister IDs** *(optional)* | External canister principals for mainnet/testnet. |
+| **How It Works** *(optional)* | Flow descriptions for multi-step processes. |
+| **Mistakes That Break Your Build** | Numbered pitfalls that prevent hallucinations. |
 | **Implementation** | Tested, copy-paste-correct code blocks. |
 | **Deploy & Test** | Step-by-step commands for local and mainnet. |
 | **Verify It Works** | Concrete commands to confirm it works. |
@@ -65,12 +67,11 @@ curl -s https://raw.githubusercontent.com/dfinity/icskills/main/skills/ckbtc/SKI
 
 ### Claude Code
 
-Copy skills into `.claude/skills/` — they're automatically loaded into context:
+Fetch the raw skill and paste it into context, or use it as a custom slash command:
 
 ```bash
-mkdir -p .claude/skills/ckbtc
-curl -sL https://raw.githubusercontent.com/dfinity/icskills/main/skills/ckbtc/SKILL.md \
-  > .claude/skills/ckbtc/SKILL.md
+# Fetch directly in conversation
+curl -sL https://raw.githubusercontent.com/dfinity/icskills/main/skills/ckbtc/SKILL.md
 ```
 
 ### OpenCode
@@ -126,9 +127,16 @@ curl -sL https://raw.githubusercontent.com/dfinity/icskills/main/skills/ckbtc/SK
 
 The files are plain markdown. Copy the content into whatever instructions, rules, or context file your tool supports.
 
-## API (Planned)
+## Programmatic Access
+
+| Resource | URL | Description |
+|----------|-----|-------------|
+| 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/{id}/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 |
 
-The website documents a REST API for programmatic access:
+## REST API (Planned)
 
 | Endpoint | Description |
 |----------|-------------|
@@ -150,6 +158,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or update skills.
 - **Site**: [Preact](https://preactjs.com/) + [Vite](https://vite.dev/) — 3kb runtime, ~16kb gzipped total
 - **Hosting**: GitHub Pages via Actions
 - **Skills**: Plain markdown files in `skills/*/SKILL.md`
+- **Validation**: Structural linter for frontmatter, sections, and dependency graph (`npm run validate`)
+- **Schema**: JSON Schema for frontmatter at `skills/skill.schema.json`
 
 ## License
 

package.json

@@ -6,9 +6,10 @@
   "license": "MIT",
   "type": "module",
   "scripts": {
-    "generate": "node scripts/generate-skills.js && node scripts/generate-llms-full.js && node scripts/generate-llms.js && node scripts/generate-agent-json.js && node scripts/generate-sitemap.js",
-    "dev": "npm run generate && vite",
-    "build": "npm run generate && vite build && node scripts/generate-skill-pages.js",
+    "validate": "node scripts/validate-skills.js",
+    "generate": "node scripts/generate-skills.js && node scripts/generate-llms-full.js && node scripts/generate-llms.js && node scripts/generate-agent-json.js",
+    "dev": "npm run validate && npm run generate && vite",
+    "build": "npm run validate && npm run generate && vite build && node scripts/generate-skill-pages.js && node scripts/generate-sitemap.js",
     "preview": "vite preview"
   },
   "dependencies": {

public/.well-known/agent.json

@@ -19,6 +19,11 @@
       "wallet"
     ]
   },
+  "endpoints": {
+    "list": "https://dfinity.github.io/icskills/llms.txt",
+    "full": "https://dfinity.github.io/icskills/llms-full.txt",
+    "skill": "https://raw.githubusercontent.com/dfinity/icskills/main/skills/{id}/SKILL.md"
+  },
   "defaultInputModes": [
     "text/plain"
   ],

public/.well-known/ai-plugin.json

@@ -2,8 +2,8 @@
   "schema_version": "v1",
   "name_for_human": "IC Skills",
   "name_for_model": "ic_skills",
-  "description_for_human": "Agent-readable skill files for Internet Computer (ICP) development. Covers ckBTC, ICRC ledger, Internet Identity, stable memory, HTTPS outcalls, EVM RPC, SNS, and more.",
-  "description_for_model": "Retrieve structured skill files for Internet Computer (ICP) development. Each skill is a markdown document with prerequisites, pitfalls, tested code blocks, and deploy commands. Use the raw GitHub URLs to inject skills directly into context. Available skills: ckbtc, icrc-ledger, internet-identity, multi-canister, stable-memory, https-outcalls, evm-rpc, asset-canister, certified-variables, sns-launch, vetkd, wallet.",
+  "description_for_human": "Agent-readable skill files for Internet Computer (ICP) development. Covers 12 capabilities including ckBTC, ICRC ledger, Internet Identity, stable memory, HTTPS outcalls, EVM RPC, SNS, and more.",
+  "description_for_model": "Retrieve structured skill files for Internet Computer (ICP) development. Each skill is a markdown document with prerequisites, pitfalls, tested code blocks, and deploy commands. Use the raw GitHub URLs to inject skills directly into context. Available skills: asset-canister, certified-variables, ckbtc, evm-rpc, https-outcalls, icrc-ledger, internet-identity, multi-canister, sns-launch, stable-memory, vetkd, wallet.",
   "auth": {
     "type": "none"
   },