ubox-init

Scaffolds a new Ubox experience directory, downloads the latest library docs and agent skills from GitLab, and writes a pre-filled agent config file.

By default targets Claude Code (CLAUDE.md + .claude/commands/). Pass --gemini to target Gemini CLI (GEMINI.md + .agent/skills/) instead.

Use --update in an existing project to refresh docs and skills in-place without re-scaffolding.

Requires Node.js 18+. No external dependencies.

Usage

npx @ubox-tools/ubox-init [--gemini] <name> [theme]
npx @ubox-tools/ubox-init --update [--gemini]

Arguments

| Argument | Required | Description | |---|---|---| | name | Yes (scaffold) | Experience name, used as the directory name. Quoted strings with spaces are used as-is; single words are converted to Title Case. | | theme | No | One-sentence description of what the experience does. Defaults to "A Ubox interactive experience: <name>." |

Options

| Option | Description | |---|---| | --update | Re-download docs and skills into the current directory. Auto-detects agent mode from existing CLAUDE.md/.claude/commands/ or GEMINI.md/.agent/skills/. Mutually exclusive with <name>. | | --gemini | Target Gemini CLI instead of Claude Code. Writes GEMINI.md and installs skills to .agent/skills/. In --update mode, overrides auto-detection. | | -h, --help | Show usage help. |

Examples

# Claude Code (default)
npx @ubox-tools/ubox-init "Slide Puzzle" "A Kinect-controlled sliding puzzle game."

# Gemini CLI
npx @ubox-tools/ubox-init --gemini "Slide Puzzle" "A Kinect-controlled sliding puzzle game."

# Update docs and skills in an existing project (auto-detects agent)
npx @ubox-tools/ubox-init --update

# Update, forcing Gemini CLI target
npx @ubox-tools/ubox-init --update --gemini

What gets created / updated

Claude Code (default):

<name>/
├── CLAUDE.md                      pre-filled with project name, theme, and doc links
├── assets/
├── apps/
├── .claude/
│   └── commands/
│       └── build-xperience.md     downloaded from GitLab
└── docs/
    ├── Ubox.md                    downloaded from GitLab
    ├── ubox-machine.md            downloaded from GitLab
    ├── ubox-human.md              downloaded from GitLab
    ├── ubox-data-xpace.md         downloaded from GitLab
    └── ubox-xcreen.md             downloaded from GitLab

Gemini CLI (--gemini):

<name>/
├── GEMINI.md                      pre-filled with project name, theme, and doc links
├── assets/
├── apps/
├── .agent/
│   └── skills/
│       └── build-xperience/
│           └── SKILL.md           downloaded from GitLab
└── docs/
    ├── Ubox.md                    downloaded from GitLab
    ├── ubox-machine.md            downloaded from GitLab
    ├── ubox-human.md              downloaded from GitLab
    ├── ubox-data-xpace.md         downloaded from GitLab
    └── ubox-xcreen.md             downloaded from GitLab

Files are downloaded fresh from the GitLab repo each time, so the project always starts with (or is updated to) the latest docs and skills.

In --update mode, only the docs/ and skills/commands files are touched — CLAUDE.md/GEMINI.md, assets/, and apps/ are left unchanged.