Add skill-authoring agent skill

.claude/skills/skill-authoring/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: skill-authoring
+description: Authors and reviews agent skills for this repo, enforcing progressive disclosure (metadata → instructions → resources), ≤500-line SKILL.md files, domain-split references, scripts over prose for deterministic work, and specific third-person descriptions. Use when creating a new skill, splitting an oversized SKILL.md, or reviewing an existing skill for structure.
+---
+
+# Skill Authoring
+
+This skill codifies the authoring discipline so every skill loads cheaply and triggers accurately.
+
+## Why progressive disclosure
+
+An agent skill is a folder with `SKILL.md` at its root. The agent loads content across three levels — each step costs
+more context, so keep lower levels lean.
+
+| Level           | When loaded                                       | Budget                     | Content                                 |
+|-----------------|---------------------------------------------------|----------------------------|-----------------------------------------|
+| 1. Metadata     | Always, at startup                                | ~100 tokens per skill      | `name` + `description` from frontmatter |
+| 2. Instructions | When the skill triggers                           | <5,000 tokens (≤500 lines) | `SKILL.md` body                         |
+| 3. Resources    | On demand, via explicit links or script execution | Effectively unlimited      | `references/`, `scripts/`, `assets/`    |
+
+Scripts are especially efficient: the source never enters context — only the **output** does.
+
+## Authoring a new skill
+
+1. **Copy the template.** Copy `templates/SKILL.md.tmpl` from this skill into your new skill's folder as `SKILL.md`,
+   then fill it in. Place the skill wherever skills live in the current repo (e.g. `skills/<your-skill>/`).
+2. **Write the description first.** Third person, include *what* the skill does AND *when* to use it.
+   See [templates/description-examples.md](templates/description-examples.md) for good vs bad examples.
+3. **Draft 3 evaluation scenarios before prose.** Capture concrete prompts the skill should handle (and ones it should
+   decline), alongside the expected behaviour. Real failures drive what you document — this keeps the skill lean.
+4. **Write the minimum SKILL.md needed to pass the evals.** Resist documenting edge cases you haven't seen fail.
+5. **Split early if content grows.** See [references/patterns.md](references/patterns.md) for the four split patterns.
+6. **Lint before committing.** **Run** the linter from this skill against your new skill directory — see the
+   Resources section below for the exact script path.
+7. **Walk the review checklist.** See [references/review-checklist.md](references/review-checklist.md).
+
+## Hard authoring rules
+
+- `SKILL.md` ≤ 500 lines. Target ≤ 200.
+- Description is third person, specific, includes what + when. Vague descriptions don't trigger.
+- References are one level deep — `SKILL.md` links to reference files, references do NOT link to further references.
+  Agents often preview links with `head -100` and miss content past that on chained links.
+- Reference files over ~100 lines start with a Contents / TOC block.
+- Name files by content (`references/finance.md`), not position (`docs/file2.md`).
+- Use forward slashes in paths — backslashes break on Unix.
+- Avoid time-sensitive wording (`"after August 2025..."`) in the main flow. Move legacy content into a collapsed "old
+  patterns" section.
+- Deterministic work belongs in `scripts/`, not Markdown.
+
+## Execution intent: be explicit
+
+When referencing a script, state whether the agent should **run** it or **read** it:
+
+- **Run** `python scripts/fetch_osm.py --bbox ...` — produces GeoJSON on stdout. (Agent executes.)
+- **See** `scripts/fetch_osm.py` for the Overpass query it issues. (Agent reads as reference.)
+
+Execution is almost always what you want — scripts are more reliable than generated code, cheaper in context, and
+consistent across runs.
+
+## When to split SKILL.md
+
+Three signals:
+
+1. **Length.** File is pushing 500 lines.
+2. **Mutually-exclusive contexts.** Two user tasks never need the same sections. Example: a Bo-Kaap question never needs
+   Camps Bay lore.
+3. **Code vs prose.** Long inline code blocks the agent will re-type anyway — move to `scripts/`.
+
+The four split patterns, with worked examples specific to this repo's skills, live
+in [references/patterns.md](references/patterns.md).
+
+## Folder layout
+
+```
+<skill-name>/
+├── SKILL.md          # Required
+├── references/       # Optional — loaded on demand via explicit link
+├── scripts/          # Optional — executed, source never loaded
+├── templates/        # Optional — starter files users copy
+└── assets/           # Optional — images, palettes, map files
+```
+
+## Review and maintenance
+
+- Before merging a new or edited skill: run the linter and walk the checklist.
+- If a reference file grows past ~100 lines, add a TOC.
+- If `SKILL.md` grows past ~300 lines, plan a split before it hits 500.
+- If a skill stops triggering when expected, tighten its description — add concrete keywords from real user prompts.
+
+## Resources
+
+- [references/patterns.md](references/patterns.md) — the four split patterns with repo-specific examples.
+- [references/review-checklist.md](references/review-checklist.md) — pre-merge checklist.
+- [templates/SKILL.md.tmpl](templates/SKILL.md.tmpl) — starter template to copy.
+- [templates/description-examples.md](templates/description-examples.md) — good vs bad description examples.
+- **Run** `python scripts/lint_skill.py <skill-dir>` — lints a skill directory for the rules above.

.claude/skills/skill-authoring/references/patterns.md

@@ -0,0 +1,136 @@
+# Skill Split Patterns
+
+## Contents
+
+- Pattern 1: High-Level Guide with References
+- Pattern 2: Domain-Specific Organisation
+- Pattern 3: Conditional Detail
+- Pattern 4: Scripts Instead of Prose
+- Choosing a pattern
+- Combining patterns
+
+---
+
+## Pattern 1: High-Level Guide with References
+
+Keep `SKILL.md` as a lightweight overview and link out to deeper material. The agent loads additional files only when the specific feature is needed.
+
+```
+pdf-processing/
+├── SKILL.md         # Overview + quick start
+├── FORMS.md         # Form-filling guide
+├── REFERENCE.md     # Full API reference
+└── EXAMPLES.md      # Common patterns
+```
+
+In `SKILL.md`:
+
+```markdown
+## Advanced features
+
+**Form filling**: see FORMS.md
+**API reference**: see REFERENCE.md
+**Examples**: see EXAMPLES.md
+```
+
+**When to use:** the skill covers one cohesive domain but has distinct deep-dive features most users won't need.
+
+**Example:** a game skill's `SKILL.md` links out to `references/tilemap-loading.md`, `references/player-movement.md`, `references/npc-dialogue.md`, `references/camera.md`. A question about camera bounds pulls in `SKILL.md` + `camera.md` only.
+
+---
+
+## Pattern 2: Domain-Specific Organisation
+
+Split references by domain so the agent only pulls in the relevant slice.
+
+```
+bigquery-skill/
+├── SKILL.md
+└── reference/
+    ├── finance.md   # Revenue, ARR, billing
+    ├── sales.md     # Pipeline, opportunities
+    ├── product.md   # API usage, features
+    └── marketing.md # Attribution, campaigns
+```
+
+A question about sales pipeline reads `SKILL.md` + `reference/sales.md`. The other three files never enter context.
+
+**When to use:** the skill spans domains where one user's questions are irrelevant to another's.
+
+**Example:** a city-lore skill with one reference file per neighbourhood (`bo-kaap.md`, `sea-point.md`, `camps-bay.md`, …). Bo-Kaap content never loads for a Camps Bay question, and vice versa. The SKILL.md acts as a navigation map.
+
+---
+
+## Pattern 3: Conditional Detail
+
+Show the common path in `SKILL.md`; link out to rare-but-important paths.
+
+```markdown
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: see REDLINING.md
+**For OOXML internals**: see OOXML.md
+```
+
+**When to use:** there's a clear 80/20 split between the common path and rare edge cases. Keeping edge cases inline bloats every activation for the 80% who don't need them.
+
+**Example:** a tiled-map authoring skill's `SKILL.md` covers the happy path for adding a tile layer; `references/collision-authoring.md` covers the less common collision-shape authoring; `references/event-triggers.md` covers POI interaction objects.
+
+---
+
+## Pattern 4: Scripts Instead of Prose
+
+Deterministic logic belongs in a script, not in Markdown. The script's source never enters context — only its output does.
+
+```
+pdf-skill/
+├── SKILL.md
+└── scripts/
+    ├── analyze_form.py
+    ├── fill_form.py
+    └── validate.py
+```
+
+In `SKILL.md`, be explicit about execution intent:
+
+```markdown
+Run: `python scripts/analyze_form.py input.pdf > fields.json`
+```
+
+versus
+
+```markdown
+See `scripts/analyze_form.py` for the extraction algorithm.
+```
+
+The first tells the agent to execute. The second tells it to read as reference. **Execution is almost always what you want** — pre-made scripts are more reliable than generated code, cheaper in context, and consistent across runs.
+
+**When to use:** the work is deterministic (parsing, querying, projecting, validating). If a prompt would ask the agent to re-type the same code every time, it belongs in a script.
+
+**Example:** a map-data skill's `scripts/fetch_osm.py` issues an Overpass API query and emits GeoJSON. The agent runs it, consumes the output, never reads the script body.
+
+---
+
+## Choosing a pattern
+
+| Signal in the content | Pattern |
+|-----------------------|---------|
+| SKILL.md has distinct feature deep-dives | 1 |
+| Content splits cleanly by audience or sub-domain | 2 |
+| 80/20 happy path vs rare edge cases | 3 |
+| Same deterministic code re-typed across uses | 4 |
+
+---
+
+## Combining patterns
+
+A mature skill often uses all four at once:
+
+- `SKILL.md` is a thin overview (Pattern 1).
+- References are split by sub-domain (Pattern 2).
+- Rare edge cases are linked-out from each section (Pattern 3).
+- Deterministic steps live in `scripts/` with explicit "Run:" instructions (Pattern 4).
+
+A map-data skill is a natural candidate for all four once it grows — thin SKILL.md, references split by feature type (e.g. `overpass-queries.md`, `projection.md`), edge cases for unusual POI types linked out, and all fetch/convert work in scripts.

.claude/skills/skill-authoring/references/review-checklist.md

@@ -0,0 +1,46 @@
+# Skill Review Checklist
+
+Walk this list before merging any new skill or edit. Lint runs first; the checklist catches things the linter can't.
+
+## Frontmatter
+
+- [ ] `name` present, lowercase-hyphenated, matches the folder name exactly.
+- [ ] `description` present, third person, ≤ 2 sentences.
+- [ ] Description includes **what** the skill does AND **when** to use it.
+- [ ] Description includes concrete keywords an agent can match on (tool names, formats, file types, domain terms) — not just vague categories.
+
+## SKILL.md body
+
+- [ ] `wc -l SKILL.md` ≤ 500. Target ≤ 200.
+- [ ] No time-sensitive wording in the main flow ("after August 2025", "until we migrate"). Move legacy content to a collapsed section.
+- [ ] All relative links use forward slashes.
+- [ ] All relative links stay within the skill folder (no `../` into other skills). Duplicate a short snippet if needed; let the other skill trigger separately for longer content.
+- [ ] Every script reference is explicit about intent — **Run** (execute) vs **See** (read as reference).
+
+## References
+
+- [ ] References are one level deep — SKILL.md links to them; references do NOT link to further reference files.
+- [ ] Reference files over ~100 lines open with a Contents / TOC block.
+- [ ] Filenames describe content (`collision-authoring.md`, `finance.md`), not position (`doc2.md`, `ref1.md`).
+
+## Scripts
+
+- [ ] Each script starts with a docstring or one-line comment stating its purpose.
+- [ ] SKILL.md shows the exact invocation (`python scripts/foo.py <args>`) and the expected output shape.
+- [ ] Scripts take inputs from args or stdin — no paths hardcoded to the author's machine.
+- [ ] Scripts exit with non-zero on failure; success is silent or produces the documented output.
+
+## Assets
+
+- [ ] Binary assets are small enough to ship in the repo (target ≤ 100 KB each).
+- [ ] Asset filenames describe content.
+
+## Evaluation
+
+- [ ] At least one concrete scenario (a real prompt + expected behaviour) exercises this skill's main path.
+- [ ] Scenarios were written **before** SKILL.md prose, or at minimum drove the prose content.
+
+## Lint
+
+- [ ] `python <path-to>/skill-authoring/scripts/lint_skill.py <path-to>/<skill>` exits 0.
+- [ ] Any warnings are either fixed or explicitly justified in the PR description.