Back to search
terracotta-courtyard-3d
SkillWorks with Claude CodeGitHub
Build a cozy, desktop-first 3D miniature diorama with React 18, TypeScript, Three.js/R3F, procedural canvas textures, warm studio lighting, post-processing, and a catalog of 12 beveled/lathe-turned animated 1x1 courtyard props with zero external assets. Use when asked for a terracotta courtyard, procedural miniature/prop library, R3F diorama lighting study, or a Phase 1→2 3D web build with docs, QA, GitHub release and state file.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/yx0128--terracotta-courtyard-3d-skill)HTML
<a href="/listings/yx0128--terracotta-courtyard-3d-skill"><img src="/api/listings/yx0128--terracotta-courtyard-3d-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 168 lines
- ---
- name: terracotta-courtyard-3d
- description: Build a cozy, desktop-first 3D miniature diorama with React 18, TypeScript, Three.js/R3F, procedural canvas textures, warm studio lighting, post-processing, and a catalog of 12 beveled/lathe-turned animated 1x1 courtyard props with zero external assets. Use when asked for a terracotta courtyard, procedural miniature/prop library, R3F diorama lighting study, or a Phase 1→2 3D web build with docs, QA, GitHub release and state file.
- ---
- # Terracotta Courtyard 3D
- A field-tested playbook for building the **Terracotta Courtyard** app: a warm,
- floating miniature diorama built entirely from code, plus twelve modular
- miniatures — and the release engineering around it.
- Reference implementation: https://github.com/yx0128/terracotta-courtyard-3d
- ## What this skill produces
- 1. Vite + React 18 + TypeScript + Tailwind app.
- 2. **Phase 1** studio: cream backdrop + fog, warm sun, hemisphere fill,
- procedural Lightformer environment, contact shadows, N8AO + Bloom + ACES,
- damped orbit camera, drifting leaves, and a floating 3×3 beveled terracotta
- patch (`?view=study`).
- 3. **Phase 2** library: 12 procedural `1×1` items (structure, water, flora/life)
- with foam, ripples, koi, a pouring spout, candle flame and a hopping bird,
- arranged on a curated 4×3 showcase grid.
- 4. Cached, seeded canvas textures: terracotta grain + bump, water foam, foliage.
- 5. Pure metadata + component registry, tests, strict TS, lint, CI.
- 6. Professional docs: README, AGENTS, architecture, art direction, catalog, QA,
- reproduction, ADRs, contribution/security/conduct, release state file.
- 7. Verified GitHub release + a separately published skill backup repo.
- ## Use when
- - The user asks for a cozy 3D miniature courtyard, diorama, or prop library.
- - The user wants a procedural R3F lighting/material study with no external art.
- - The user wants a complete Phase 1→2 web build with docs and release steps.
- - Do **not** use for a generic dashboard, a Phaser/2D game, or work that allows
- GLB/HDR assets as the primary art pipeline.
- ## Non-negotiables
- - **Zero external assets.** No GLB/GLTF/HDR/images/audio/fonts/CDNs. Paint
- textures in `<canvas>`; build geometry with Three.js, `RoundedBoxGeometry`,
- `SplineCurve`+`LatheGeometry`, `TubeGeometry`, custom buffers.
- - **Pin React 18 + R3F 8 + drei 9 + @react-three/postprocessing 2.** R3F 9 /
- postprocessing 3 require React 19.
- - Every prop fits `1×1`, base at `y=0`, height ≈ 0.35–1.3.
- - Bevels everywhere: `radius ≈ 0.04` (clamp for thin parts). No bare sharp boxes
- or cones as finished props.
- - Palette: warm cream `#F3ECE0`, terracotta, limestone, olive, teal, brass,
- charcoal. No neon, pure white or pure black.
- - Deterministic art: seeded `mulberry32`; never `Math.random()` in textures,
- layout or animation.
- - Desktop-first; overlays `pointer-events-none` except links.
- ## Workflow
- ### 1. Protect credentials and confirm environment
- ```bash
- node --version && npm --version
- gh auth status # once
- ```
- At release time read the token once: `export GH_TOKEN="$(gh auth token)"`.
- Never repeat Keychain reads; push via `GIT_ASKPASS` (recipe in references).
- ### 2. Scaffold and pin dependencies
- Create `src/{components/items,data,lib,theme,utils}`, `docs`, `.github`,
- `skill/<name>/references`. Use Vite/TS/Tailwind/ESLint/Vitest configs from the
- reference repo. Install with `npm install --no-audit --no-fund`; approve
- esbuild's install script if npm blocks it.
- ### 3. Build pure foundations first
- `palette.ts` → `random.ts` (mulberry32/randRange/hashSeed) → `terraceLayout.ts`
- (tile 0.94, gap 0.06, pitch 1.0, centred slots) → tests.
- ### 4. Procedural textures
- Terracotta 256² colour + grayscale bump (radial clay base, mottling, ~3,600
- mineral specks, worn edges). Water foam 256² transparent wobbled rings. Foliage
- 128² olive dapple. Cache as lazy singletons; SRGB for colour, NoColorSpace for
- bump. **Keep UVs upright** — per-tile rotation of a RepeatWrapping map on a
- two-triangle face creates diagonal X seams.
- ### 5. Studio scene
- `<Canvas shadows flat ...>`, cream background + fog, sun 2.2 @ [12,18,10] with
- 2048² ±10 PCF soft shadows, hemisphere 0.85, `<Environment resolution=256
- frames={1}>` with warm Lightformers and `scene.environmentIntensity = 0.35`,
- `ContactShadows` frames=1, damped orbit, 8–10 drifting leaves. Composer:
- N8AO(0.6, 1.8, 0.8) → Bloom(1.05, 0.4, mipmap) → ACES ToneMapping. `<Canvas
- flat>` means tone mapping happens **once**. Exposure ≈ 0.96.
- ### 6. 3×3 study
- Nine `RoundedBoxGeometry(0.94, 0.18, 0.94, 4, 0.04)` pavers, pitch 1, shared
- cached maps, tint + sub-degree mesh rotation. Add a DOM HUD with texture swatches
- and click-through. This is the inspection view.
- ### 7. Item helpers and catalog
- `BeveledBox` (clamp radius; omit `args`/`children` from `MeshProps` before adding
- your args, or `position` becomes `never`), `Lathe` (SplineCurve profile), water
- material, expanding-ring effect, reusable songbird. Split geometry hooks into
- their own file for Fast Refresh/lint.
- Twelve items, exact costs: brick tile 10, limestone 10, stair 15, balustrade 25,
- birdbath 45, koi basin 50, spout 55, hedge 20, roses 25, column 30,
- candle+cushion 20, bench+bird 30 (total 335). Metadata in pure specs; components
- in a registry; 4×3 showcase with tinted pads. See references for part breakdown.
- ### 8. Verify
- ```bash
- npm run typecheck && npm run lint && npm test && npm run build
- ```
- Then headless Chrome 1440×900 for `/` and `/?view=study`; assert no console
- errors, all items visible, animations differ between frames. Full script in
- references.
- ### 9. Docs and state
- README (hero screenshot, views, catalog, controls, architecture, credits),
- AGENTS.md, architecture, art direction, catalog, QA, reproduction, ADRs,
- contribution/conduct/security/changelog/license, CI + templates, STATE.md with
- session id, model, cost, all five token columns, wall-clock time, exact SQL and
- the caveat that the snapshot excludes the final reply. Credit OpenCode and the
- model.
- ### 10. Publish safely
- One `GH_TOKEN` read, `gh repo create ... --public`, then push with
- `GIT_TERMINAL_PROMPT=0 git -c credential.helper= push` and a temporary
- `GIT_ASKPASS` script. Never put the token in the remote URL or repo. Publish the
- skill folder as its own repo with the same flow, then install copies into
- `~/.claude/skills/` and `~/.config/opencode/skills/`.
- ## Traps that cost time
- | Symptom | Fix |
- | --- | --- |
- | Diagonal X on every paver | Do not rotate/offset shared UV maps per tile; vary tint/mesh rotation |
- | Washed double-toned clay | `<Canvas flat>` + single composer ToneMapping |
- | React 19 peer errors | Stay on React 18 / R3F 8 / drei 9 / postprocessing 2 |
- | `position` typed `never` in helper | Omit `args`/`children` from `MeshProps` before extending |
- | Stale QA screenshots | Failed `tsc -b` hidden by `tail`; check build exit code |
- | Spout arc invisible | Start the Bézier outside the frog mouth; use a dark teal core + foam sleeve |
- | Catch-basin water hidden | Place water above the lathe surface, not inside the solid profile |
- | Keychain prompt loop | One `gh auth token`; `GIT_ASKPASS` for every push |
- ## Reference files
- - [references/build-playbook.md](references/build-playbook.md) — full Phase 1/2
- implementation recipe with dimensions, profiles and camera setups.
- - [references/art-and-lighting.md](references/art-and-lighting.md) — palette,
- lighting rig, material and motion rules.
- - [references/catalog.md](references/catalog.md) — exact item parts, dimensions
- and animations.
- - [references/release-checklist.md](references/release-checklist.md) — gates,
- screenshot QA, GitHub/askpass, state SQL, skill publication.
- ## Definition of done
- A stranger can clone the repo, run `npm ci && npm run dev`, switch between the
- study and showcase views, understand every item and animation, verify the build
- and reproduce the release — without asking you anything.
README.md · README · 18 lines
- # Terracotta Courtyard 3D — agent skill
- A reusable playbook for building a cozy procedural 3D miniature courtyard with
- React 18, TypeScript, Three.js/R3F, canvas textures, warm studio lighting,
- post-processing, twelve beveled/lathe-turned animated 1×1 props, professional
- docs, QA, and a verified GitHub release.
- - **Skill:** [`SKILL.md`](SKILL.md)
- - **Reference app:** https://github.com/yx0128/terracotta-courtyard-3d
- - **Skill repo:** https://github.com/yx0128/terracotta-courtyard-3d-skill
- - **References:** build playbook, art/lighting rules, release checklist.
- Install by copying this folder to `~/.claude/skills/terracotta-courtyard-3d/`
- (and optionally `~/.config/opencode/skills/`). Load it when a task asks for a
- procedural miniature diorama, R3F lighting/material study, or a complete
- Phase 1→2 3D web build with no external assets.
- MIT © 2026 Terracotta Courtyard contributors.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.