Docs site: publish the repo's Markdown to GitHub Pages

.github/workflows/docs.yml

@@ -0,0 +1,88 @@
+name: docs
+
+# Builds the MyST site on every PR and publishes it to GitHub Pages on main.
+# A PR gets build + link check and never deploys, so a broken docs change is
+# caught before it can replace the live site.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# One deploy at a time, but never cancel a running main deploy — a cancelled
+# deployment can leave Pages serving a half-published site.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      # Pinned: an unpinned docs toolchain turns an upstream release into a
+      # surprise failure on an unrelated PR.
+      - name: Install MyST
+        run: npm install -g mystmd@1.10.1
+
+      # The site is served from a subpath (quantecon.github.io/skills), so the
+      # built asset URLs have to carry it. PR builds use the root, since they
+      # are only ever checked for whether they build.
+      - name: Build
+        run: myst build --html
+        env:
+          BASE_URL: ${{ github.event_name == 'push' && '/skills' || '' }}
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _build/html
+
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Checked against the Markdown sources rather than the built site: the
+      # theme renders as a single-page app, so its HTML holds no crawlable
+      # link graph, and the sources are what has to stay correct in both
+      # contexts anyway — the GitHub repo view and the published site.
+      #
+      # Offline only. Several links point at private QuantEcon repos, which
+      # answer 404 to an unauthenticated checker; failing CI on those would
+      # teach everyone to ignore this job.
+      - name: Check relative links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --offline
+            --no-progress
+            --exclude-path node_modules
+            --exclude-path _build
+            "**/*.md"
+          fail: true
+
+  deploy:
+    # Only main deploys, and only after both gates pass.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [build, links]
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -7,3 +7,7 @@ __pycache__/
 benchmark/references/examples/*/results/as_used.json
 benchmark/references/examples/*/results/cold_start.json
 benchmark/references/examples/*/results/env.json
+
+# MyST docs site build output
+_build/
+node_modules/

README.md

@@ -4,6 +4,8 @@ A [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-market
 
 Each plugin bundles one area of work — a skill (the instructions Claude follows) plus the deterministic scripts it drives — so the same versioned toolkit works locally for authors and RAs, and headlessly in CI.
 
+📖 **[quantecon.github.io/skills](https://quantecon.github.io/skills)** — the documentation, rendered and navigable. It is built from the files in this repository, so reading either one gets you the same content.
+
 ## Plugins
 
 | Plugin | For | Covers |

docs/developing-skills.md

@@ -77,6 +77,17 @@ Two things to know:
 
 Confirm with `/plugin marketplace list` (the source should read `QuantEcon/skills`, not your local path) and `/plugin list` (the version should match the merged `plugin.json`). Routine setup and updating for end users is covered in [using-skills.md](using-skills.md).
 
+## The documentation site
+
+These guides, the plugin guides, and the shared reference material are published to [quantecon.github.io/skills](https://quantecon.github.io/skills) by [`.github/workflows/docs.yml`](../.github/workflows/docs.yml) on every push to `main`. Preview it before you push:
+
+```bash
+npm install -g mystmd
+myst start          # live-reloading preview
+```
+
+Two things follow from how it is wired. **Pages are rendered from the files where they already live** — [`myst.yml`](../myst.yml) points at `benchmark/README.md` and `audit/references/*.md` in place, never a copy — so editing a plugin's docs updates the site, and no plugin loses documentation it needs to ship with it. And **the sources have to stay readable on GitHub**, since the repo view is the other half of the audience: prefer plain Markdown, and keep relative links relative, because CI checks that every one of them resolves.
+
 ## Versioning and releases
 
 Bump the version in **both** `plugin.json` and the plugin's `marketplace.json` entry — the validator enforces they match. Scaffolding → first usable content is a minor bump (the benchmark plugin's evaluation-system landing was 0.1.0 → 0.2.0).

myst.yml

@@ -0,0 +1,47 @@
+# MyST site configuration — renders the repo's existing Markdown as a
+# navigable site at https://quantecon.github.io/skills.
+#
+# Content is never moved here. Every entry below points at the file where it
+# already lives, so the repo view and the published site render from one
+# source (AGENTS.md, "Single source of truth") and an installed plugin keeps
+# shipping its own documentation inside its own directory.
+version: 1
+
+project:
+  id: quantecon-skills
+  title: QuantEcon Skills
+  description: >-
+    QuantEcon's shared Claude Code skills and the deterministic scripts they
+    drive — style checks for authors, acceleration evaluation, and bulk
+    repository audits.
+  github: https://github.com/QuantEcon/skills
+  toc:
+    - file: README.md
+    - title: Guides
+      children:
+        - file: docs/using-skills.md
+        - file: docs/developing-skills.md
+        - file: docs/tutorial-run-an-evaluation.md
+    - title: Plugins
+      children:
+        - file: benchmark/README.md
+          title: Benchmark plugin
+          children:
+            - file: benchmark/references/EVALUATION_FRAMEWORK.md
+        - file: audit/README.md
+          title: Audit plugin
+          children:
+            - file: audit/references/doctrine.md
+            - file: audit/references/quantecon-context.md
+            - file: audit/references/deliverables.md
+    - title: Project
+      children:
+        - file: CATALOG.md
+        - file: FUTURE-IDEAS.md
+
+site:
+  template: book-theme
+  title: QuantEcon Skills
+  options:
+    logo_text: QuantEcon Skills
+    hide_outline: false

reviews/benchmark-design-2026-07-21-independent.md

@@ -3,7 +3,7 @@
 **Date:** 2026-07-21
 **Branch reviewed:** `docs-skills-usage`
 **Scope:** the full evaluation system in `benchmark/` — rubric dimensions and weights, metrics, aggregation and verdict method, thresholds and calibration, measurement architecture. Everything treated as open to revision; the goal is the best possible evaluation system for QuantEcon, where lectures are teaching materials first.
-**Method:** read every design document ([README.md](benchmark/README.md), [EVALUATION_FRAMEWORK.md](benchmark/references/EVALUATION_FRAMEWORK.md), [scripts/README.md](benchmark/scripts/README.md), [SKILL.md](benchmark/skills/review-acceleration/SKILL.md), [examples README](benchmark/references/examples/README.md)), the scoring engine ([rubric.py](benchmark/scripts/scoring/rubric.py), [score.py](benchmark/scripts/scoring/score.py)), both worked evaluations (evidence, results, reports), and the measurement scripts; then ran the rubric against synthetic edge cases to test the aggregation empirically. The numbered edge-case results below (A–D) were produced by executing `rubric.score_all` directly on constructed evidence.
+**Method:** read every design document ([README.md](../benchmark/README.md), [EVALUATION_FRAMEWORK.md](../benchmark/references/EVALUATION_FRAMEWORK.md), [scripts/README.md](../benchmark/scripts/README.md), [SKILL.md](../benchmark/skills/review-acceleration/SKILL.md), [examples README](../benchmark/references/examples/README.md)), the scoring engine ([rubric.py](../benchmark/scripts/scoring/rubric.py), [score.py](../benchmark/scripts/scoring/score.py)), both worked evaluations (evidence, results, reports), and the measurement scripts; then ran the rubric against synthetic edge cases to test the aggregation empirically. The numbered edge-case results below (A–D) were produced by executing `rubric.score_all` directly on constructed evidence.
 
 ## Bottom line