Skip to content
Skills Library
Programming · Automation

foundryvtt-module

/foundryvtt-module

FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.

Original author description

FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.

How it works

  1. Delegated: the gitops repo-adoption procedure
  2. When to Use This Skill
  3. Preconditions
  4. Phase 0 — Derive and confirm the spec
  5. Phase 1 — Preflight
  6. Phase 2 — Scaffold, init, and get to green
  7. FoundryVTT deltas
  8. Phase 6 — Verify the finishing pass, then hand back
  9. Failure modes specific to FoundryVTT
  10. Notes
Original SKILL.md headings · 205 lines, 1,385 words
SKILL.md preview
---
created: 2026-06-26
modified: 2026-07-30
reviewed: 2026-07-30
name: foundryvtt-module
description: >-
  FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the
  repo, open the gitops adoption PR. Use when releasing or spinning up a new
  foundry module.
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite, AskUserQuestion
---

# foundryvtt-module

Drives a FoundryVTT **module idea** to a release-ready, gitops-adopted GitHub
repository in one pass, pausing at exactly one human approval.

Reach for `foundryvtt-module-scaffold` on its own when all you want is the local
file tree. Reach for **this** skill when the remote repo should also exist, be
seeded, and be under Terraform management by the time you stop.

## Delegated: the gitops repo-adoption procedure

The second half of this pipeline — creating and seeding the GitHub repo, opening
the gitops adoption PR, the human merge gate, and the import-block-removal
follow-up — is **not duplicated here**. It is identical for every laurigates repo
class and is owned by:

> **`comfyui-plugin:comfy-node`, Phases 3 → 5** (plus its branch-protection hook
> note and its generic failure-mode rows).

That skill's *Adapting Phases 3–5 to another repo class* section names every
value to substitute. Run Phases 0 → 2 here, apply the deltas in
[FoundryVTT deltas](#foundryvtt-deltas), then execute Phases 3 → 5 there.

Two consequences of that procedure worth stating up front, because they shape
what you do in Phase 2 below:

- The seed commit lands on `main` with no intervening branch or PR — read the
  owner's Phase 3 for *why* that ordering is load-bearing, not just convenient.
- A Claude Code session will hit a `branch-protection` hook block on that seed.
  The owner's note explains the hand-off; do not invent a workaround.

## When to Use This Skill

| Reach for this skill | Reach elsewhere |
|---|---|
| An idea needs to become a live repo — files, remote, gitops entry, release pipeline | Only local files are wanted → `foundryvtt-module-scaffold` |
| Nothing exists yet under that module name | The module already exists → work in its repo |
| Someone asks to "spin up" or "stand up" a Foundry module | A release is due → release-please and the release workflow already handle it |

## Preconditions

- Work from the FoundryVTT workspace (`repos/laurigates/foundryvtt-dev/`), so the
  new checkout sits beside `foundryvtt-mcp` / `foundryvtt-mediasoup-webrtc`. The
  gitops clone is therefore at `../gitops`.
- The remaining preconditions (a **personal** `gh auth` that may create repos, and
  an uncommitted-change-free gitops clone) are stated once in the owner skill —
  satisfy them before Phase 3.

## Phase 0 — Derive and confirm the spec

From the idea, derive and **show the user** before creating anything external:

| Field | How to derive | Example |
|-------|---------------|---------|
| `--name` | `foundryvtt-<kebab>` (the GitHub repo). | `foundryvtt-initiative-tweaks` |
| `--id` | Foundry module id; default = `--name` minus `foundryvtt-`. | `initiative-tweaks` |
| `--display` | Title-case. | `Initiative Tweaks` |
| `--desc` | One line, manifest-facing. | `Small quality-of-life tweaks to the combat initiative tracker.` |
| `--variant` | `app` for a UI window; `libwrapper` to patch a core method; else `basic`. | `basic` |
| `--fvtt-verified` | The major Foundry version the harness pins. | `13` |
| topics | `["foundryvtt", "module", …]` + facet tags. | `…,"combat","initiative"` |

Get explicit user sign-off on **name, id, and variant** — renaming any of the
three after the repo exists is expensive.

## Phase 1 — Preflight

Three lookups; every one must come back free before you continue. Any collision
is a full stop — report it and wait.

```sh
test ! -e foundryvtt-initiative-tweaks && echo "local: free" || echo "local: EXISTS"
```

```sh
grep -q '"foundryvtt-initiative-tweaks"' ../gitops/repositories.tf && echo "gitops: EXISTS" || echo "gitops: free"
```

```sh
gh repo view laurigates/foundryvtt-initiative-tweaks >/dev/null 2>&1 && echo "github: EXISTS" || echo "github: free"
```

(`../gitops` assumes the foundryvtt-dev layout; point it at wherever the gitops
clone actually lives.)

## Phase 2 — Scaffold, init, and get to green

```sh
python3 ${CLAUDE_SKILL_DIR}/../foundryvtt-module-scaffold/scaffold.py --name foundryvtt-initiative-tweaks --display "Initiative Tweaks" --desc "Small quality-of-life tweaks to the combat initiative tracker." --variant basic
```

```sh
cd foundryvtt-initiative-tweaks
```

```sh
git init -b main
```

```sh
bun install
```

```sh
just check
```

Notes specific to this stack:

- **`git init -b main` precedes `bun install`** — the install step wires git
  tooling and expects a repository to already be present.
- **`bun.lock` belongs in the seed commit.** `bun install` writes it and CI runs
  `--frozen-lockfile`; a seed without it fails on the first workflow run.
- `just check` is typecheck + build + lint + test. A red module never reaches
  GitHub — repair it here and re-run.

## FoundryVTT deltas

Substitutions to apply while executing `comfyui-plugin:comfy-node` Phases 3 → 5.
Everything the owner skill states that is not listed here applies verbatim.

| Owner's step | FoundryVTT value |
|---|---|
| Repo name | `foundryvtt-initiative-tweaks` |
| gitops clone path | `../gitops` — so `git -C ../gitops …` throughout, and `grep … ../gitops/repositories.tf` |
| Seed commit subject | `feat: scaffold foundryvtt-initiative-tweaks (basic module)` |
| `repositories.tf` entry | `release_please = true` and **no registry flag** — see below |
| PR title | `feat: adopt foundryvtt-initiative-tweaks` |
| What merging the PR pushes | The release-please App credentials only (no registry token) |
| Phase 5 verification | `gh api repos/laurigates/foundryvtt-initiative-tweaks/actions/variables/RELEASE_PLEASE_APP_ID --jq .name` — it should echo the variable name. Skip the owner's `gh secret list` probe; there is no registry secret to find. |

The entry to add under the active repositories `locals` block, beside the other
`foundryvtt-*` entries (mirror `foundryvtt-mcp`):

```hcl
    "foundryvtt-initiative-tweaks" = {
      description    = "Small quality-of-life tweaks to the combat initiative tracker"
      visibility     = "public"
      release_please = true
      topics         = ["foundryvtt", "module", "combat", "initiative"]
    }
```

**Why no registry flag:** Foundry modules are distributed as GitHub release
assets, not through a package registry, so there is no analogue of a ComfyUI
pack's `comfy_registry`. `release_please = true` is the whole adoption surface.

## Phase 6 — Verify the finishing pass, then hand back

**Run the gate before declaring done** — do not close on a self-authored summary:

```sh
python3 ${CLAUDE_SKILL_DIR}/../foundryvtt-module-scaffold/scaffold.py --verify foundryvtt-initiative-tweaks
```

Read `STATUS=`; the exit code is 1 on ERROR.

| `STATUS=` | Action |
|-----------|--------|
| `ERROR` | **Not done.** The ERROR rows are install-blocking — the module 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 that does not exist. Fix and re-run. |
| `WARN` | Deferrable. Log each WARN to `project:foundryvtt` in taskwarrior and say so in the hand-back. |
| `OK` | Hand back. |

An ERROR is never a follow-up item: every one of them ships a module Foundry
either refuses to install or loads to nothing, with no error anywhere in CI. The
same invariants run in the module's own `test` job (`tests/manifest.test.ts`), so
a later drift fails a PR rather than a user's install.

Once the apply lands, the delivery chain is live: conventional-commit PRs →
release-please PR → tag → the release workflow builds, zips `dist/`, and attaches
`<id>.zip` plus `module.json` (the manifest URL) to the GitHub release.

Remaining work to hand over:

- Write the module logic — `basic`: `src/module.ts` + `src/settings.ts`; `app`:
  `src/app.ts` + `templates/app.hbs`; `libwrapper`: swap the `Token._draw`
  example in `src/patches.ts` for the real patch.
- Exercise it against the local `foundryvtt-harness` (`bun run dev`, or build and
  symlink `dist/` into `Data/modules/<id>`). Keep `module.json` `compatibility`
  aligned with the Foundry version the harness pins.
- The first `feat:`/`fix:` merge triggers the first release-please PR.

Record durable follow-ups in the user's FoundryVTT taskwarrior project per
`taskwarrior-cross-session`.

## Failure modes specific to FoundryVTT

The gitops-side failures (empty release-please `app-id`, `403 Resource not
accessible by integration`, a plan that *creates* instead of *imports*, a red
`just check` in gitops) are diagnosed in the owner skill's table. Foundry adds
one of its own:

| Symptom | Cause | Fix |
|---------|-------|-----|
| Module fails to load in Foundry | `esmodules` path ≠ Vite output, or `id` ≠ install folder | The scaffold pins both; confirm `dist/<id>.mjs` exists and the installed folder is named `<id>` |
| CI fails on the very first run with a lockfile error | `bun.lock` missing from the seed commit | Commit it — `--frozen-lockfile` has nothing to check against |

## Notes

- Playwright integration tests against the harness, and a Quench in-Foundry
  suite, are deliberately not scaffolded. Add them when the module earns them.
- Local gitops work stays read-only (`plan` / `validate`); the owner skill
  explains why applies only ever run through `tofu-apply.yml`.

Versions

The database has no other skills named foundryvtt-module.

Database snapshot: 13.11.2026 · package version 1402013f6f90 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100foundryvtt-module-scaffold
    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.
  • 100comfy-node
    Orchestrate a ComfyUI node pack from idea to registry: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new comfyui node pack.
  • 95module-scaffold
    Use when creating a brand new module file in modules/ for a new tool category. Generates the boilerplate with correct array prefix, install_module_<name>() function, and ensures it integrates with install.sh, profiles, and MCP server. Triggers on "new module", "add a module for…
  • 91foundry-vtt-system-dev
    Covers building, extending, and maintaining Foundry VTT game systems for v14+. This skill applies when scaffolding a new system, declaring Actor/Item types with documentTypes + TypeDataModel, customizing dice mechanics, implementing combat & initiative, building character…
  • 100get-started
    Get this person set up for the hackathon, from a fresh clone to their app live through GitOps, and lay out the day, the way a coach at the Radar table would. Use when they ask to get set up, check their setup, or what to do first, when they ask what they're looking at in Radar,…
  • 100gitops-status
    Monitor GitOps application health, sync status, and manage ArgoCD deployments via Harness MCP. Use when user says "gitops status", "argocd status", "application sync", "gitops health", "is my app in sync", or asks about GitOps applications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.