Improve repo structure, CI pipeline, and contributor experience

.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/_checks.yml

@@ -0,0 +1,55 @@
+name: Checks
+
+on:
+  workflow_call:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    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
+        run: |
+          if [ -n "${{ github.base_ref }}" ]; then
+            base="origin/${{ github.base_ref }}"
+          else
+            base="HEAD~1"
+          fi
+          changed=$(git diff --name-only "$base" -- 'skills/*/SKILL.md')
+          if [ -z "$changed" ]; then
+            echo "No SKILL.md files changed"
+            exit 0
+          fi
+          fail=0
+          for file in $changed; do
+            if ! git show "$base":"$file" > /dev/null 2>&1; then
+              echo "NEW: $file (no version check needed)"
+              continue
+            fi
+            old_version=$(git show "$base":"$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

.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+name: PR
+
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    uses: ./.github/workflows/_checks.yml

.github/workflows/deploy.yml

@@ -5,18 +5,19 @@ on:
     branches: [main]
   workflow_dispatch:
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 concurrency:
   group: pages
   cancel-in-progress: true
 
 jobs:
+  checks:
+    uses: ./.github/workflows/_checks.yml
+
   build:
+    needs: checks
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -32,6 +33,9 @@ jobs:
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

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. |
-| **Prerequisites** | Exact versions. `icp-cli >= 0.1.0`, `ic-cdk >= 0.18`. |
-| **Mistakes that break your build** | Numbered pitfalls that prevent hallucinations. |
+| **What This Is** | One paragraph. What the technology does. |
+| **Prerequisites** | Exact versions. `icp-cli >= 0.1.0`, `ic-cdk >= 0.19`. |
+| **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": {