메뉴
Scaffold a new FoundryVTT v13 module repo (Vite + TS + bun + biome, CI, release-please) with basic/app/libwrapper variants. Use when bootstrapping or init-ing a foundry module.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/laurigates/claude-plugins --skill foundryvtt-module-scaffold명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SKILL.md 표시 중
Install, configure and troubleshoot MCP servers. Use when adding/enabling servers, editing .mcp.json, fixing OAuth, or when a server runs stale code after an upstream fix.
FinOps snapshot — org billing, workflow stats, cache usage. Use when you want a high-level view of CI spending or workflow health before diving deeper.
GitHub Actions billing, workflow efficiency, and waste analysis at org or repo level. Use when investigating CI/CD costs, wasted runs, or optimizing triggers.
| created | "2026-06-26T00:00:00.000Z" |
| modified | "2026-07-30T00:00:00.000Z" |
| reviewed | "2026-07-30T00:00:00.000Z" |
| name | foundryvtt-module-scaffold |
| description | Scaffold a new FoundryVTT v13 module repo (Vite + TS + bun + biome, CI, release-please) with basic/app/libwrapper variants. Use when bootstrapping or init-ing a foundry module. |
| allowed-tools | Bash, Read, Write, Edit, Grep, Glob, TodoWrite |
| args | [--name <repo>] [--display <title>] [--desc <text>] [--variant <basic|app|libwrapper>] |
| argument-hint | --name foundryvtt-x --display "X" --desc "…" --variant basic |
Bootstrap a new FoundryVTT v13 module repo built with Vite + TypeScript +
bun + biome, leaving only the actual module logic to implement. The generated
repo passes just check (typecheck + build + lint + test) from the first commit
and distributes via the GitHub-release manifest-URL convention.
| Use this skill when... | Use the alternative when... |
|---|---|
| Starting a new FoundryVTT module repo — CI-green TS toolchain, release-please, and a basic/app/libwrapper skeleton before writing module logic | You want the full pipeline (repo created + seeded + gitops-adopted) → foundryvtt-module |
| Spinning up a FoundryVTT module backlog idea | Adding a feature to an existing module — this creates a new repo |
TypeScript source in src/ (entry src/module.ts), built to dist/<id>.mjs
via Vite library mode. vite-plugin-static-copy places module.json, lang/,
styles/ (and templates/ for the app variant) into dist/, which Foundry
serves as the module root. tsc --noEmit type-checks; Vite emits — decoupled.
bun run typecheck → tsc --noEmit. Foundry globals are typed
by loose local ambient shims (src/foundry-shims.d.ts), so the build is
self-contained and CI-green without the (beta, git-only) fvtt-types. Verify
the real Foundry API before relying on a shape — the shims are deliberately
loose. Opt into fvtt-types later if you want richer types.bun run build → vite build → dist/<id>.mjs + copied assets.bun run dev → Vite dev server on :30001 proxying everything to
Foundry on :30000 except the module's own files (served with HMR).module.json manifest →
, →
. release-please bumps in both
and ; the release job builds, zips , and
attaches the assets. No foundryvtt.com submission is needed to install by URL
(only to be in the in-app package browser).releases/latest/download/module.jsondownloadreleases/latest/download/<id>.zip$.versionpackage.jsonmodule.jsondist/| Variant | Use when | Adds on top of basic |
|---|---|---|
basic (default) | Settings + lifecycle behavior — the minimal well-formed module. | init/ready hooks, a registered world setting, i18n, scoped CSS. |
app | The module has a UI panel. | An ApplicationV2/HandlebarsApplicationMixin window (src/app.ts + templates/app.hbs) and a game.settings.registerMenu button that opens it. |
libwrapper | The module patches a core/system method. | src/patches.ts with a libWrapper.register(...) call and a manual monkey-patch fallback when lib-wrapper is absent; a relationships.recommends entry for lib-wrapper. |
Decision rule: basic for behavior driven by hooks/settings; app when the
module surfaces a window or dialog; libwrapper when it overrides a core method
(the conflict-safe way to do that on Foundry). Variants compose conceptually —
start from the closest one and add the rest by hand.
scaffold.py is stdlib-only. Run from the workspace where the module should
land (e.g. repos/laurigates/foundryvtt-dev/).
Basic settings+hooks module:
python3 ${CLAUDE_SKILL_DIR}/scaffold.py --name foundryvtt-initiative-tweaks --display "Initiative Tweaks" --desc "Small quality-of-life tweaks to the combat initiative tracker."
Module with an ApplicationV2 UI panel:
python3 ${CLAUDE_SKILL_DIR}/scaffold.py --name foundryvtt-party-overview --display "Party Overview" --desc "A dockable party status panel for GMs." --variant app
Module that patches a core method via libWrapper:
python3 ${CLAUDE_SKILL_DIR}/scaffold.py --name foundryvtt-token-vision-tweak --display "Token Vision Tweak" --desc "Adjusts token vision drawing via a libWrapper-guarded patch." --variant libwrapper
Flags: --name (GitHub repo, e.g. foundryvtt-x), --id (Foundry module id;
default = --name minus the leading foundryvtt-), --display (title),
--desc, --variant {basic,app,libwrapper}, --fvtt-min / --fvtt-verified
(compatibility, default 12 / 13), --publisher (default laurigates),
--author, --dir (parent dir, default cwd).
It refuses to overwrite an existing directory.
--verify)python3 ${CLAUDE_SKILL_DIR}/scaffold.py --verify foundryvtt-initiative-tweaks
Re-runs the finishing-pass audit against an existing module and emits a
machine verdict (MODULE_ID_MATCH=, ESMODULES=, MANIFEST_URL=,
DOWNLOAD_URL=, RELEASE_ZIP=, DECLARED_ASSETS=, LOCKFILE=, then
ISSUE_COUNT= and STATUS=). Exit 1 on ERROR.
STATUS= | Meaning |
|---|---|
ERROR | Foundry cannot install, load, or update the published module — the id disagrees across module.json / vite.config.ts / src/constants.ts, esmodules names a file the build never emits, or an install URL resolves to a release asset nobody uploads. |
WARN | It loads, but something is unfinished (a declared asset that 404s, no bun.lock yet). A fresh scaffold is WARN until bun install runs. |
OK | Nothing outstanding. |
The generated repo asserts the same invariants in tests/manifest.test.ts, which
its own test CI job runs on every PR — so a rename that drifts one of the five
places the module id appears fails a PR, not a user's install.
templates/foundryvtt-module/ is a cargo-generate port of scaffold.py whose
emitted files are real files (so tsc/biome/actionlint can check them)
rather than Python strings. Output is byte-identical, enforced by
scripts/tests/test-template-parity.sh.
scaffold.py remains the default. Reach for the template to edit the
scaffold itself, or to try the flow before it is promoted:
cargo generate --path ${CLAUDE_SKILL_DIR}/../../templates/foundryvtt-module --name foundryvtt-initiative-tweaks --vcs none --define 'display_name=Initiative Tweaks' --define 'description=…' --define variant=basic
Needs cargo-generate locally — not in the base image, and the main cost of the
port. CI installs it from the release tarball so the parity gate actually runs
(#2221). See templates/README.md
for the comparison, the one deliberate divergence (a non-kebab-case name), the
Liquid brace-collision fixes, and what promoting the template would take.
A repo where just check passes from the first commit: a real module.json
manifest, package.json (bun scripts), vite.config.ts, strict tsconfig.json,
biome.json, vitest.config.ts + a green Vitest smoke test (Foundry globals
stubbed in tests/setup.ts) and tests/manifest.test.ts (the manifest-vs-build
gate above), .github/workflows/ (ci.yml,
release-please.yml, renovate.yml), release-please-config.json + manifest,
renovate.json, a justfile, src/module.ts + src/settings.ts +
src/constants.ts + src/foundry-shims.d.ts, lang/en.json,
styles/<id>.css, CLAUDE.md, README.md, LICENSE, and an ADR recording the
toolchain decision. The app variant adds src/app.ts + templates/app.hbs;
libwrapper adds src/patches.ts.
The generator prints the exact next steps. In order:
cd foundryvtt-<name>
git init -b main
bun install
just check
Seed main directly (the repo is unprotected until gitops adopts it) — pushing
a feature branch first would leave main missing on origin and force a rename +
default-branch fixup later. bun install writes bun.lock, which the seed
commit must include (CI uses --frozen-lockfile).
Then implement, and wire up infra:
basic, src/module.ts + src/settings.ts;
for app, src/app.ts + templates/app.hbs; for libwrapper, replace the
Token._draw example in src/patches.ts with the real target.gitops/repositories.tf with release_please = true and
a foundryvtt topic (mirror the foundryvtt-mcp entry). On apply, gitops
pushes the release-please App credentials.Or skip steps entirely: run the /foundryvtt-module orchestrator, which
chains scaffold → gh repo create → seed main → the gitops PR.
id is the single source of truth. module.json id, the install
folder, and the release zip name all derive from --id. Lowercase kebab-case
only.esmodules references
<id>.mjs; the Vite output filename is pinned to match. A mismatch is a silent
load failure — tests/manifest.test.ts fails the PR that introduces it.module.json
compatibility.{minimum,verified} in sync with what you test against. Verify
the Foundry API against https://foundryvtt.com/api/ or the live console — not
memory.dist/. It is git-ignored and rebuilt; CI builds it for
releases.CHANGELOG.md or the version fields — release-please
owns them (it bumps both package.json and module.json).| Context | Command |
|---|---|
| Scaffold a basic module | python3 ${CLAUDE_SKILL_DIR}/scaffold.py --name foundryvtt-X --display "X" --desc "…" |
| Scaffold an app module | python3 ${CLAUDE_SKILL_DIR}/scaffold.py --name foundryvtt-X --display "X" --desc "…" --variant app |
| Verify a generated module | cd foundryvtt-X && bun install && just check |
| Gate the finishing pass (machine verdict) | python3 ${CLAUDE_SKILL_DIR}/scaffold.py --verify foundryvtt-X |
| Check the pilot still matches scaffold.py | bash ${CLAUDE_SKILL_DIR}/scripts/tests/test-template-parity.sh |
| Prove the finishing-pass gate still fires | bash ${CLAUDE_SKILL_DIR}/scripts/tests/test-manifest-invariants.sh |
scaffold.py's BIOME_VERSION constant so
biome.json and the CI setup-biome step never drift.renovate.yml (laurigates reusable workflow) bumps them.fvtt-types. This keeps
the build green and self-contained; switch tsconfig types to fvtt-types
(github:League-of-Foundry-Developers/foundry-vtt-types#main) for full API
types once you need them.