feat: add @deck.gl-community/ai-skills — AI agent helpers for deck.gl

[charlieforward9]

Summary

Picks up the thread from #534 and the discussion with @ibgreen and @akre54.

The module takes the position that both approaches are valid — for different jobs — and ships them together with a single llms.txt that makes the distinction explicit.

Note on scope: I checked what GeoDA AI / OpenAssistant and @kepler.gl/ai-assistant are doing before building this. GeoDA's OpenAssistant is visualization-agnostic (Kepler.gl and Leaflet are the current targets; deck.gl is listed as wip). Kepler's @kepler.gl/ai-assistant provides function-calling tools (addLayer, mapBoundary, etc.) scoped to the Kepler UI rather than raw deck.gl. Neither covers the "help an LLM write deck.gl code directly" use case — so this fills a real gap rather than duplicating existing work.

Pattern A — native TypeScript (for LLM code generation)

Typed factory functions (scatterplotLayer, arcLayer, etc.) returning correct props with sensible defaults. This directly addresses @akre54's point that agents work best writing native code backed by clean docs. The llms.txt is that doc.

Pattern B — JSON descriptors (for serializable configs / low-code UIs)

Fully JSON-serializable layer descriptors with dot-path accessor strings, validateDescriptor, and hydrateDescriptor. Preserves the noodle/IR approach from #534 for the cases where it genuinely belongs: low-code builders, saved dashboards, server-side LLM output that can't execute code.

Files

File	Purpose
src/layer-factories.ts	Typed factory functions for Scatterplot, Path, Polygon, Text, Arc, Heatmap
src/layer-descriptors.ts	createDescriptor / validateDescriptor / hydrateDescriptor with dot-path resolution
src/deck-builder.ts	Fluent DeckBuilder composing layers + view state into a serializable DeckConfig
src/viewport-skills.ts	fitViewport, getBoundingBox, createViewState
llms.txt	Agent reference doc — worked examples, full layer reference, decision guide

llms.txt is included in the npm files list and ships with the package.

On the Zod direction

validateDescriptor is a natural slot for Zod schemas. @ibgreen — if you share more on the Zod layer schema direction, it would integrate cleanly here without a breaking API change.

Test plan

• 14 unit tests — factories, descriptor validation, hydration, DeckBuilder, viewport helpers
• All 57 repo test files pass
• Prettier + ESLint hooks pass
• Diff is clean — only modules/ai-skills/, tsconfig.json, .eslintignore, .prettierignore, yarn.lock

Supersedes #551 (wrong base branch) and #534 (Copilot-generated).

🤖 Generated with Claude Code

[charlieforward9]

Closing — shelving this for now.