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

• Worktree is based on the current branch in code0 (not hardcoded to development)
• Branch named <current_branch>_<nr> (e.g. development_1)
• If the repo already exists locally, just cd to it.

---

forge workspace — Create worktree from current code0 repo

forge workspace 1    # create worktree in $ROOTDIR/code1 for current repo
forge workspace 2    # create worktree in $ROOTDIR/code2 for current repo

• Must be run from inside code0/<repo>
• Auto-detects repo name and current branch from cwd

---

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, detects repo name and nr automatically and asks confirmation.
• On merge conflicts: calls a 0 agent to resolve, git add, and git commit --no-edit.
• After successful merge: removes the worktree and deletes the branch.

---

forge workdiscard — Discard a worktree

forge workdiscard             # auto-detect from cwd (must be inside codeN)
forge workdiscard 1           # list all repos in code1, ask to discard each
forge workdiscard 2           # same for code2
forge workdiscard 1 hero_proc # discard code1/hero_proc specifically

• Shows workspace path and branch, warns about data loss, asks [y/N]
• cd back to code0/<repo> after discarding
• Removes the worktree and deletes the branch (-D force delete)

---

forge new — Create a repo on Forgejo

forge new lhumina_c/my_repo            # create repo with Apache 2.0, README, Rust .gitignore
forge new lhumina_c/my_repo --private  # same, private repo
forge new lhumina_c/my_repo --no-agent # skip agent setup after creation
forge new lhumina_c/my_repo --instruction "build a hero_proc client"

• Partial org name matching (lhumina_c matches lhumina_code)
• Auto-initializes with Apache 2.0 license, README.md, and Rust .gitignore (via Forgejo templates)
• If the remote repo already exists: warns with a danger message and asks to delete + recreate
• If the local directory already exists and is not empty: asks to delete it
• Sets up a development branch and launches a 0 to scaffold the Rust project

---

forge delete — Delete a repo

forge delete lhumina_code/my_repo   # delete local dir and/or remote repo
forge delete my_repo                # partial name also works

• Checks locally ($CODEROOT/<name>) — if found, asks [y/N] to delete
• Checks remote on Forgejo — if found, warns with danger message and asks [y/N] to delete
• Each step is independent (can delete one without the other)
• cds out of the directory first if you're currently inside it

---

forge pull / forge push — Sync repos

forge pull                    # pull current repo (auto-detects from cwd)
forge pull hero_proc              # clone if missing, otherwise pull (auto-resolves conflicts)
forge push                    # add → commit (agent writes message) → pull → push
forge push hero_lib           # same, for a named repo

• No message argument — the agent reads the diff and writes a meaningful commit message
• Auto-detects repo from current directory (walks up to find .git root)
• On conflict: auto-launches a 0 agent 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 hero_proc --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                      # cd + open $EDITOR for current repo (auto-detects)
forge edit geomind/hero_proc        # cd + open $EDITOR for named repo
forge add hero_lib              # git add -A in repo path
forge commit hero_lib "fix: x"  # git commit in repo path

forge edit, forge pull, and forge push all auto-detect the repo from the current directory — they walk up from pwd to find the .git root and use that repo name.

---

forge secrets — Personal secrets repo

secrets source                  # load secrets into current shell
secrets_edit                    # open secrets.toml in $EDITOR
secrets push                    # commit + push secrets repo (agent writes commit message)
secrets_sync                    # clone/pull your private secrets repo from Forgejo

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	Groq: Kimi K2 (requires GROQ_API_KEY)
6	OpenRouter: MiniMax M2.5
7	DeepGram: Nemotron 3 120B (requires DEEPGRAM_API_KEY)
10	Groq: Kimi K2 (requires GROQ_API_KEY)

---

Installers

install_base    # curl, fzf, zoxide, yazi, p7zip + yazi plugins & keymaps
install_ai      # Claude Code AI assistant
install_py      # Python via uv + ipython, pudb, openai SDK

install_base installs essential utilities with yazi plugins (chmod, git) and custom keymaps (c m for chmod, n u for nushell).

install_ai downloads Claude Code from claude.ai/install.sh.

install_py installs Python via uv with ipython, pudb, and the openai SDK for AI library access.

---

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
• Backs up removed skills to ~/.claude/backups/
• Installs/updates skills to ~/.claude/skills/ via rsync
• Refreshes nushell modules by running install.nu
• Prompts you to restart nushell to activate changes

---

hero_utils — Utility functions

y                       # Yazi file manager (cd to navigated dir on exit)
ls-big [path] --top N   # List largest files in dir (default: top 10)
to bytes                # Convert filesize string to bytes
str stats               # Count lines, words, characters in string
to md-table             # Convert table records to markdown table

---

services — Hero service management

service_hero_proc       # Clone lhumina_code/hero_proc and run make run
service_hero_aibroker   # Clone lhumina_code/hero_aibroker and run make run
service_browser_mcp     # Clone lhumina_code/hero_browser_mcp and run make run (starts hero_proc first)

Ensures required services are running for Hero ecosystem.