feat: docs-as-skillz

.github/workflows/build-release.yml

@@ -114,6 +114,21 @@ jobs:
         env:
           BUILD_VERSION: ${{ steps.version.outputs.version }}
 
+      - name: Download PostHog docs artifact
+        id: docs_artifact
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.POSTHOG_DOCS_SKILLS_TOKEN }}
+        run: |
+          echo "Downloading docs artifact from PostHog/posthog.com..."
+          gh run download --repo PostHog/posthog.com -n posthog-docs-md --dir /tmp
+          unzip -q /tmp/posthog-docs-md.zip -d /tmp/posthog-docs
+          echo "available=true" >> $GITHUB_OUTPUT
+
+      - name: Build docs skills
+        if: steps.docs_artifact.outputs.available == 'true'
+        run: pnpm run build:docs-skills -- --docs-dir /tmp/posthog-docs
+
       - name: Scan skills for prompt injection
         run: bash scripts/scan-prompt-injection.sh dist/skills
 
@@ -168,6 +183,11 @@ jobs:
           # Upload skill-menu.json (used by the wizard to discover available skills)
           echo "Uploading skill-menu.json..."
           gh release upload "$RELEASE_TAG" dist/skills/skill-menu.json --clobber
+          # Upload docs-skill-menu.json if docs skills were built
+          if [ -f dist/skills/docs-skill-menu.json ]; then
+            echo "Uploading docs-skill-menu.json..."
+            gh release upload "$RELEASE_TAG" dist/skills/docs-skill-menu.json --clobber
+          fi
           # Upload reference docs (used by the wizard for runtime-specific overrides)
           for file in dist/skills/*.md; do
             [ -f "$file" ] || continue

README.md

@@ -87,3 +87,56 @@ The build script automatically discovers, orders, and generates URIs for all res
 - **Version controlled**: Resources evolve with the examples
 
 See `llm-prompts/README.md` for detailed workflow conventions.
+
+## Docs skills
+
+We also auto-generate one [Agent Skill](https://agentskills.io/specification) per section of the PostHog docs. These ship as part of the normal build and release cycle.
+
+### How it works
+
+The build script (`scripts/build-docs-skills.js`) parses `posthog.com/llms.txt`, groups pages by section heading, and reads the raw markdown for every page. Each section becomes its own skill directory under `dist/skills/posthog-docs-{section}/`, with a `SKILL.md` and a `references/` folder of subpages.
+
+The script reads docs from a local directory via `--docs-dir` instead of crawling the live site. In CI, `build-release.yml` downloads a docs artifact produced by the posthog.com repo (a daily GitHub Actions artifact containing all built markdown files + `llms.txt`), extracts it, and runs the build.
+
+### What it generates
+
+| Output | Description |
+|--------|-------------|
+| `dist/skills/posthog-docs-{section}/SKILL.md` | Skill prompt + root page content |
+| `dist/skills/posthog-docs-{section}/references/*.md` | One file per subpage |
+| `dist/skills/docs-skill-menu.json` | Menu index of all generated skills |
+
+### Distribution
+
+Skills are published to GitHub Releases alongside curated skills. The menu is at:
+
+```text
+https://github.com/PostHog/context-mill/releases/latest/download/docs-skill-menu.json
+```
+
+Individual skill ZIPs follow the same pattern:
+
+```text
+https://github.com/PostHog/context-mill/releases/latest/download/posthog-docs-{section}.zip
+```
+
+### Try it locally
+
+```bash
+# Build from a local posthog.com build output
+node scripts/build-docs-skills.js --docs-dir ~/posthog.com/public
+
+# Or fetch from the live site (no --docs-dir)
+pnpm run build:docs-skills
+
+# Build specific sections only
+node scripts/build-docs-skills.js --docs-dir ~/posthog.com/public feature-flags product-analytics
+
+# Test in Claude Code — copy a skill into .claude/skills/
+cp -r dist/skills/posthog-docs-feature-flags .claude/skills/
+# Claude Code picks it up immediately, no restart needed
+```
+
+### Why this is separate from the curated pipeline
+
+The docs skills pipeline and the curated build (`scripts/build.js`) are intentionally independent. They write to different files (`docs-skill-menu.json` vs `skill-menu.json`) and can be built separately. Curated skills change with deliberate PRs. Docs skills are auto-generated from the latest posthog.com documentation.

package.json

@@ -10,6 +10,7 @@
     "test:plugins:watch": "vitest scripts/plugins/tests",
     "test:skills": "vitest run scripts/lib/tests",
     "test:skills:watch": "vitest scripts/lib/tests",
+    "build:docs-skills": "node scripts/build-docs-skills.js",
     "test": "vitest run scripts/plugins/tests scripts/lib/tests"
   },
   "devDependencies": {