Add CLAUDE.md with repo guidance for Claude Code

Author: avillar

CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A collection of reference skills for LLM tooling, covering OGC standards and tooling. Skills follow the [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) format: a directory with a `SKILL.md` entry point (YAML frontmatter + Markdown body) and supporting `.md` files.
+
+## Testing the site build locally
+
+```bash
+python3 .github/scripts/build_site.py _site <any-sha> <repo-url> <site-url>
+# e.g.
+python3 .github/scripts/build_site.py _site abc123 https://github.com/ogcincubator/ogc-llm-skills https://ogcincubator.github.io/ogc-llm-skills
+```
+
+This writes `_site/` with all skill zips, `index.html`, `manifest.json`, and `llms.txt`. No other build step exists; there are no tests.
+
+## Publishing
+
+Every push to `master` triggers `.github/workflows/publish.yml`, which runs `build_site.py` and deploys to GitHub Pages. No manual step needed.
+
+## Adding a skill
+
+1. Create a directory under a namespace (e.g. `bblocks/consuming/`).
+2. Add `SKILL.md` with frontmatter:
+   ```markdown
+   ---
+   name: kebab-case-name          # max 64 chars
+   description: "What it covers and when to use it."   # max 1024 chars, plain text
+   ---
+   ```
+3. Add supporting `.md` files in the same directory.
+
+The zip name is derived from the directory path with slashes replaced by hyphens (`bblocks/authoring/` → `bblocks-authoring.zip`).
+
+## Skill content design principles
+
+These are non-obvious and important for maintaining quality:
+
+- **SKILL.md is a router, not a tutorial.** It must give enough signal per entry that the LLM can decide which sub-file to read without actually reading it — closer to an annotated bibliography than a table of contents.
+- **One lookup unit per file.** Each file answers a set of questions a developer would look up together. Target 400–1500 words. If two topics always need each other to be actionable, merge them.
+- **Hierarchical navigation on demand.** The LLM reads `SKILL.md` first, then fetches sub-files via tool calls. Sub-files should be self-contained enough to be read independently.
+- **Schemas by URL, not copied.** Config file schemas live at `https://raw.githubusercontent.com/opengeospatial/bblocks-postprocess/master/ogc/bblocks/schemas/` — reference by URL so they stay current.
+
+## Machine-readable entrypoints
+
+The published site exposes two entrypoints for agent-driven installation:
+- `manifest.json` — structured JSON with absolute zip URLs for each skill
+- `llms.txt` — Markdown summary following the [llmstxt.org](https://llmstxt.org) convention
+
+Both are generated by `build_site.py` alongside `index.html`.