Hero Skills

Claude Code skills and shell tools for Hero ecosystem development.

Quick Install

curl -sSfL https://forge.ourworld.tf/lhumina_code/hero_skills/raw/branch/development/tools/install.sh | bash

This will:

• Clone hero_skills to ~/hero/code/hero_skills (or pull if already present)
• Install nushell and set it as your default shell
• Configure nushell modules (agent, forge, secrets, installers)
• Set up zoxide and fzf integrations

---

Environment Setup

Run once to configure your environment:

init setup    # first-time wizard: sets ROOTDIR, FORGE_TOKEN, writes secrets.nu
init main     # load Hero environment into current shell

Required Environment Variables

These must be set (done by init main) — all modules fail explicitly if missing:

Variable	Description
ROOTDIR	Root of your Hero filesystem (e.g. /Volumes/T7)
CODEROOT	Always $ROOTDIR/code0 — where repos live
BUILDDIR	Always $ROOTDIR/build — Cargo and build artifacts

FORGE_URL defaults to https://forge.ourworld.tf. FORGE_TOKEN is required for any API operations.

---

Modules (tools/modules/)

Coding Conventions

• Every module function that uses ROOTDIR, CODEROOT, or BUILDDIR calls ensure_env_vars first — it fails with a clear message if any are missing. Never use | default fallbacks for these vars inside functions.
• Repo resolution always goes through forge_resolve $name — never construct $CODEROOT/name paths directly. forge_resolve is offline-first: searches local code0 before hitting the API.
• Positional args, not flags for nr (worktree number) and search terms — follow the forge cd pattern: name first, nr second, both optional.

---

forge cd — Navigate code directories

forge cd                  # cd to $CODEROOT (code0)
forge cd hero             # cd to matching dir in code0
forge cd 2                # cd to $ROOTDIR/code2 (created if missing)
forge cd hero 2           # cd to matching dir in code2 (runs forge worktree if missing)

• If nr given and $ROOTDIR/codeN doesn't exist, it is created automatically.
• If a search term is given but no match found in the target dir, forge worktree <name> <nr> is called automatically.

---

forge worktree — Clone and manage worktrees

forge worktree hero_lib       # clone into $CODEROOT (code0), cd to it
forge worktree hero_lib 1     # clone into $CODEROOT, create worktree in $ROOTDIR/code1
forge worktree hero_lib 2     # clone into $CODEROOT, create worktree in $ROOTDIR/code2

• If the repo already exists locally, just cd to it.
• nr is positional (not a flag): forge worktree hero_lib 2, not forge worktree hero_lib --nr 2.

---

forge workmerge — Merge worktree back into code0

forge workmerge               # auto-detect repo and nr from cwd, confirm, then merge
forge workmerge hero_lib 1    # merge $ROOTDIR/code1/hero_lib back into $CODEROOT
forge workmerge hero_lib 2    # merge $ROOTDIR/code2/hero_lib back into $CODEROOT

• nr must be > 0 (a worktree, not the main clone).
• When run from inside a worktree (e.g. /Volumes/T7/code2/hero_lib), detects repo name and nr automatically and asks confirmation.
• On merge conflicts: calls a 1 -i "..." (Claude Sonnet) with instructions to resolve each conflict, git add, and git commit --no-edit.
• After successful merge: removes the worktree and deletes the branch.

---

forge pull / forge push — Sync repos

forge pull zinit              # clone if missing, otherwise pull (auto-resolves conflicts)
forge push hero_lib "fix: x"  # add → commit → pull → push

On conflict: auto-launches Claude to resolve, git add, and git commit --no-edit.

---

forge find / forge list / forge info — Discover repos

forge list                          # all repos
forge list hero                     # repos with 'hero' in name
forge list lhumina/hero             # partial org + partial name
forge find --org lhumina_code       # all repos in org
forge find --search zinit --one     # single match → returns URL
forge info hero_lib                 # details: branch, stars, forks, clone URLs, local path

Name matching — all commands accept a partial name (hero) or org/repo (lhumina/hero). Errors if 0 or >1 match. Local paths resolve to $CODEROOT/<reponame>.

---

forge edit / forge add / forge commit

forge edit geomind/zinit        # cd + open $EDITOR
forge add hero_lib              # git add -A in repo path
forge commit hero_lib "fix: x"  # git commit in repo path

---

forge secrets — Personal secrets repo

secrets init                    # clone/pull your private secrets repo, create secrets.nu
secrets source                  # load secrets.nu into current shell
secrets edit                    # open secrets.nu in $EDITOR
secrets push                    # commit + push secrets repo

Secrets live at $ROOTDIR/code0/secrets/secrets.nu — a private repo on Forgejo.

---

init — Environment initialization

init setup    # first-time wizard
init main     # load env: ROOTDIR, CODEROOT, BUILDDIR, FORGE_URL, EDITOR, sccache

init main sources ~/hero/cfg/init.sh then secrets.nu, derives CODEROOT and BUILDDIR from ROOTDIR, and fails if any critical variable cannot be set.

---

a — AI model launcher

a 0                          # Claude Haiku
a 1                          # Claude Sonnet
a 2                          # Claude Opus
a 1 -i "refactor this file"  # Sonnet with opening instruction
a 6                          # OpenRouter: MiniMax M2.5

#	Model
0	Claude Haiku
1	Claude Sonnet
2	Claude Opus
4	OpenRouter: Mercury-2
5	OpenRouter: Kimi K2
6	OpenRouter: MiniMax M2.5
7	Groq: Kimi K2 (requires GROQ_API_KEY)

---

Installers

install_base    # yazi, fzf, zoxide, curl
install_ai      # Claude Code
install_py      # Python via uv + ipython, pudb, openai

---

skills_edit — Edit hero_skills repo

skills_edit     # Open ~/hero/code/hero_skills in $EDITOR

Opens the hero_skills repository in your default editor (zed, code, etc.) so you can browse or edit skills and tools.

---

skills_sync — Sync skills and nushell modules

skills_sync     # Pull latest hero_skills, update ~/.claude/skills/, and refresh nushell modules

This command:

• Pulls the latest hero_skills repo from ~/hero/code/hero_skills
• Auto-resolves merge conflicts (if any) using Claude Sonnet
• Installs/updates skills to ~/.claude/skills/
• Refreshes nushell modules by running install.nu
• Prompts you to restart nushell to activate changes

---

Utilities

y               # Yazi file manager (cd to navigated dir on exit)