Skip to content

levy-street/world-of-claudecraft / .claude/skills/asset-pipeline

asset-pipeline

Verified

FileKindSize
SKILL.mdskill md7.5 KB
---
name: asset-pipeline
description: Generate game-ready 3D assets for World of ClaudeCraft with the AI asset pipeline (Tripo API + optional gpt-image-2). Use when asked to create or generate game assets, a new weapon model, a prop, a creature or mob model, a player-class skin, or any 3D model or texture for the game. Drives scripts/asset_pipeline/pipeline.mjs through the full loop: generate, review the rendered previews, fix orientation, apply the registry wiring, run the guard tests, and finish the manual follow-ups the pipeline cannot judge.
user-invocable: true
---

# Asset pipeline: generate, review, integrate

Full reference: `scripts/asset_pipeline/CLAUDE.md`. This is the operational loop.

## 0. Prerequisites
- `TRIPO_API_KEY` in the repo-root `.env` (gitignored). `OPENAI_API_KEY` optional (better
  concept images, skin `--prompt` repaints). Never commit `.env` or keys.
- Confirm credits before spending: `node scripts/asset_pipeline/pipeline.mjs balance`.
  A P1 image-to-model run is ~40 to 50 credits; rig 25; retarget 10 per animation.

## 1. Pick the lane
| Ask | Lane | Command core |
|---|---|---|
| Held weapon (sword, axe, staff, ...) | weapon | `weapon --name <key_with_family> --prompt "..."` |
| World object / building / scenery | prop | `prop --name <key> --height <units> --prompt "..." [--building]` |
| Mob / NPC / animated character | creature | `creature --name <key> --prompt "..."` |
| Player-class skin (texture swap) | skin | `skin --class <cls> --suffix <x> --tripo --prompt "..."` |
| League-style themed CHARACTER skin | skinmodel | `skinmodel --class <cls> --theme "pool party" --name <key>` |
| Free rig of a raw mesh (KayKit skeleton) | rig-manual | `rig-manual --raw <job>/raw.glb --name <key>` |

skinmodel is the flagship: it renders the REAL base class model, has gpt-image-2 redesign
that exact character around the theme (same identity, chibi proportions), builds it with
Tripo's best model (v3.1 + smart_low_poly), retargets the FULL KayKit clip vocabulary
in-place (so `clips: kaykit([...])` drives it unchanged), and injects calibrated
`handslot.r/.l` bones (pose transplanted from the knight reference) so it holds weapons
through the game's own attach path. Review `preview/held_attack.png` to see it swing a sword.

Weapon keys MUST contain a family token (sword, dagger, staff, hammer, axe, halberd, spear,
scythe, wand) or the `tests/held_weapon_models.test.ts` contract fails. For skins,
`--tripo --prompt "..."` is the RECOMMENDED mode (real re-texturing); `--recolor` is the
cheap deterministic fallback, and a bare `--prompt` repaint needs `OPENAI_API_KEY`
(mode details: `scripts/asset_pipeline/CLAUDE.md`).

## 2. Generate, then ALWAYS review the previews
Run the lane command WITHOUT `--apply` first. Then Read (the Read tool, they are images) the
preview PNGs under `tmp/asset_pipeline/<job>/preview/`: `front.png`, `right.png`, `back.png`,
`left.png`, `hero.png`, plus `clip_<Name>.png` per animation for creatures. Check:
- Weapon: blade/tip up (head up for axe/hammer/staff), looks like the request; the preview
  dir carries `held_hero/right/attack.png` (knight) AND `held_<model>_{hero,right,attack}.png`
  for ALL 7 class bodies with mid-attack frames: a weapon must hold correctly on every
  character. In the live viewer (`library --serve`) use the "held by" dropdown to watch any
  character (including generated skinmodel bodies) swing it.
- Prop: upright, front facing the camera in `front.png`.
- Creature: every clip frame posed (a T-pose clip frame means a broken retarget); for
  non-biped rigs the walk clip is reused for Idle/Run/Attack/Death, judge if that reads OK.

## 3. Fix by resuming the job (paid stages never re-run)
- Weapon upside down: rerun the same command with `--flip --job <id>`.
- Prop facing the wrong way: rerun with `--rotate-y <deg> --job <id>`.
- Crash or timeout: rerun with `--job <id>` (the `job.json` ledger skips finished steps).
- Force specific steps to re-run after a parameter change: `--redo <step1,step2> --job <id>`
  (e.g. `--redo retarget,assemble`); cleared paid steps re-pay, so prefer the targeted flags.
- Wrong shape entirely: new run with a sharper `--prompt` or a `--image` concept
  (T-pose reference for creatures). This is a new paid generation; check `balance`.
- `status [--job id]` lists jobs; `validate` / `inspect` / `inplace-check` re-check a GLB.
- Lane and viewer detail beyond this loop (the `library` viewer and `--serve` live 3D
  inspector, `skin --tripo` real re-texturing vs the `--recolor` filter, `skinset` whole
  roster sets and their SKINS/SKIN_COUNTS lockstep) lives in the full reference,
  `scripts/asset_pipeline/CLAUDE.md`; read the matching section there before running those
  lanes. One rule worth repeating: skins are texture swaps on the SAME rig; a radically
  new body silhouette is the cosmetic-body path (`SkinCatalog` union change, not automated
  by the skin lanes).

## 3b. QA gate (mandatory before apply)
```
node scripts/asset_pipeline/pipeline.mjs qa --job <id>
```
Lane-aware structural re-verification (rig + required clips, grip convention + HUD icon +
held-on-all-7-characters renders for weapons, handslots + KayKit vocabulary for skinmodels,
preview coverage) plus the REAL itemized cost: each recorded Tripo task is priced from the
API's own `credits_consumed` (1 credit = $0.01) and gpt-image-2 usage at token rates.
PASS/WARN/FAIL scorecard; `qa.json` in the job dir; exits 1 on FAIL (fix with `--redo` or a
regenerate before integrating). ALWAYS report the printed TOTAL cost per asset to the user.

## 4. Apply, guard tests, manifest
Rerun with `--apply` (still `--job <id>` so nothing regenerates). Then:
- weapon: `npx vitest run tests/held_weapon_models.test.ts`
- skin: `npx vitest run tests/skin_event.test.ts`
- creature/prop: place the printed snippet (step 5), then `npx tsc --noEmit`
- All lanes: `node scripts/build_media_manifest.mjs generate` (auto in `npm run build`; dev
  needs no regen). Never hand-edit `src/render/assets/manifest.generated.ts`.
- CREDITS.md was auto-appended by `--apply`; `npm run asset:budget` is advisory.

## 5. Manual follow-ups per lane (the pipeline will not do these)
- weapon: place the printed ItemDef snippet in `src/sim/content/items.ts` (or map existing
  item ids via `--items`); real vanilla-style stats are your judgment.
- prop: add the printed `PROP_ASSET_DEFS` entry (`src/render/props.ts`) and place it, either
  `ZonePropsDef` in `src/sim/content/zone*.ts` with a collider matched to the visuals
  (`src/sim/colliders.ts`), or the `GROUND_OBJECTS` interactable lane (no collision).
- creature: add the printed VisualDef to `VISUALS` and wire the mob template in `MOB_KEYS`
  (`src/render/characters/manifest.ts`); set the real world-unit height and tint.
- New player-facing entities also need: `src/ui/world_entity_i18n.ts` name entries and wiki
  regen (`npm run wiki:content`, `npm run wiki:stills` for models). Every new ITEM id also
  owes committed WebP art (`tests/item_art_consistency.test.ts`) in the same change, and a
  wordy English name owes its M16 non-Latin fills too (root `CLAUDE.md` i18n bullet);
  "English only at PR tier" does not cover those two.
- Never extend `SkinCatalog` (`src/sim/types.ts`): it is a closed sim/wire union. Class
  variants go through the skin lane; new bodies are mobs/NPCs.
- Verify in game: `npm run dev`, screenshot the asset in place.

## 6. Commit
Conventional Commits with a scope, e.g. `feat(assets): add emberfang sword weapon variant`.
Commit the GLB/texture/icon under `public/`, the registry edits, CREDITS.md, and your
snippet placements. Never commit `tmp/asset_pipeline/` artifacts, `.env`, or keys.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall