Troubleshooting

In the quoted lines, a word in angle brackets stands for the value the CLI prints there, and … stands for detail it appends, usually git’s own message.

#Setup and GitHub

#The GitHub CLI is missing or logged out

GitHub authentication is required to create a team: run `gh auth login` and retry, or create the team against an existing empty remote with `npx -y terum-skills@latest team create <name> --remote <url>`.

Creating a team on GitHub, invite, team remove and downloading the app all run through the GitHub CLI. Install gh if it is missing, run gh auth login, and try again. Joining, publishing, installing and evals do not need it.

#A command needs a terminal

Cannot ask "<question>": this command needs an interactive terminal (stdin is not a TTY).

Nothing could answer the command’s question: Claude Code’s Bash tool and scripts have no terminal. Run it yourself in a terminal. A command can write before its first question, so read what it printed first.

#This machine is already on a team

One team per machine: This machine is on team <name> (<remote>). Terum Skills keeps one team per machine: run `npx -y terum-skills@latest team leave <name>` first, then re-run `<command>`.

A machine holds one team. Leaving is local, and your membership stays. If your team moved to a new repository, use team move instead (see Joining).

$ npx -y terum-skills@latest team leave <name>

#An invitation is refused

Could not invite @<login> (GitHub status 403). …

Adding a collaborator needs GitHub repository admin permission; ask an admin. When the line adds GitHub caps invitations at 50 per repository per day., you hit GitHub’s daily cap, and waiting is the only fix. See Team admin.

#Joining

#The clone fails with “Repository not found”

Could not clone <remote>: …
Git could not access <remote>.
"Repository not found" can mean:

The URL is wrong, the invitation is not accepted yet, or git’s HTTPS credentials lack access even though gh is logged in. Accept the invitation at https://github.com/<org>/<repo>/invitations. If your gh account has access, let it supply git’s credentials, which also fixes Git has no usable HTTPS credentials for github.com (this changes git’s global settings for github.com):

$ gh auth setup-git --hostname github.com

#No pending invitation

No pending GitHub invitation to <org>/<repo> for your account. Your account cannot read that repository either: if the next step cannot reach it, the person who invited you has not added you on GitHub yet; ask them, then run this again.

GitHub has no invitation to that repository for the account gh uses. Check that gh auth status shows the login the admin invited.

#Your handle is taken

Handle <handle> is already in use by an active member.

Join asks again, up to three attempts, so pick another. A second machine of yours reclaims your entry when the GitHub login or email matches. See Join a team.

#Your team’s repository no longer exists

Team <team>'s repository <url> no longer exists on GitHub.

The repository was deleted or recreated elsewhere. setup with the new repository, and sync at a terminal, both offer to move this machine. To move it yourself:

$ npx -y terum-skills@latest team move <org>/<repo>

#Publishing

#The skill is not in your Library

No local skill folder named <name> in your library. Inspect it with `npx -y terum-skills@latest ls --local`, or add the project holding it with `npx -y terum-skills@latest project add`.

publish and eval read only your Library: Global and the projects you registered. Your working directory does not count until you add it:

$ npx -y terum-skills@latest project add <path>

#Hygiene refuses the folder

HYG<n> <path>[:<line>]: <message>

A hygiene gate failed and nothing was published; eval prints the same findings under Hygiene failed for <name>:. skill fix <path> repairs the mechanical ones and lists the rest. validate requires the four fields publish writes, so a folder you have never published fails on those, as expected. See Hygiene checks.

#Another command holds the write lock

Another terum-skills operation holds the write lock on <team>; retry when it finishes.

Another terum-skills command on this machine is using the team clone. Wait for it and retry. If the line says the lock is stamped in this machine’s future, it is a clock problem: once no terum-skills command is running, remove the directory it names.

#The name belongs to another skill

<name> is no longer in the repository as <id>; run sync and retry.

The team’s newest version of that name carries a different skill id: someone published that name meanwhile, or two people have different skills with the same folder name. Run sync, check ls, and skill rename your folder if it is a different skill. See Versions and identity.

#Installing and managing

#Install refuses a version

Installing a previous version is not supported yet; install installs the latest version.

Install always takes the latest version, so drop the @<version>. The pinning hint in setup’s closing cheat sheet is out of date.

#A folder with that name is already there

You already have a skill named <name>.
Your copy is kept at <path>.
Replace it with Version <N>? [y/N]

Yes moves your folder to old-skills beside the skills root and places the team’s version; no changes nothing. If your folder already holds a published version’s exact bytes, install --adopt <path> records it as installed without copying.

#Install asks you to approve tools

Approve these tools for <name>? [y/N]

Install asks once per skill and set of allowed-tools grants, and remembers the answer. Scripts and Claude Code’s Bash tool cannot answer, so run it in a terminal or from the app. With projects registered, a non-interactive install also needs --into global or --into <project root>. See Install and manage.

#Evals

#Claude Code is not ready

`claude` is not runnable (…) — is Claude Code installed and on PATH?
preflight agent task failed — check that `claude` is logged in and the model '<model>' is available: …

Before any paid work, eval runs claude --version and a one-turn task. Install Claude Code, or run claude in a terminal and log in. On Windows the first line can name an npm batch shim the CLI cannot launch; Claude Code’s native Windows installer avoids it.

#Nothing can answer the heavy question

Cannot ask "Use the one-session heavy evaluation mode?": this command needs an interactive terminal (stdin is not a TTY).

The skill looks like it calls subagents, so eval asks about heavy mode. From a script or an agent session, pass --heavy or --no-heavy. The answer is recorded and does not change how the run executes.

#Generation fails

Could not generate execution cases: <reason>. Retry the command or pass --no-gen.
The generated eval assets for <name> failed hygiene, so nothing was written:

Both are defects in generation, not in your skill, and nothing was written to your folder: run the eval again. The exception is the reason SKILL.md metadata.eval.shape must be 'suite' or 'cases', which comes from your frontmatter; fix the value or remove the key. See Generated evals.

#The verdict is partial

verdict: NEUTRAL [partial — 4/6 scored]
skipped (environment): hybrid-review — missing codex

Some rows never scored: a case needed a tool this machine lacks, its setup failed, or an arm died. A hole never counts as a zero. Install the tool or fix the case, then run again for a complete receipt. See Results and receipts.

#The run was refused for contamination

arm '<arm>' resolved skills [<skills>] — '<name>' leaked into an arm that did not stage it; refusing the run (§7.3)

The engine checks which skills each arm’s session loaded. The skill under test must load only where it was staged, or the comparison measures nothing, so the whole eval is refused, after the arms ran and were billed. Each arm’s transcript in the run tree shows what it loaded.

#The queued bytes changed

The queued bytes of <skill> are no longer what is on disk; dequeue it and queue it again.

A queued eval is tied to the folder’s bytes when it was queued, and the folder has changed since:

$ npx -y terum-skills@latest eval --dequeue <skill>
$ npx -y terum-skills@latest eval <skill> --window overnight

#Sync and the app

#A team was not refreshed

<team>: not refreshed (unreachable) — remote: Repository not found.

sync names the state and carries on with your other teams.

• unreachable: git could not reach the remote. The advice that follows matches the clone failure under Joining.
• busy: another command held the clone’s write lock. Run sync again.
• no-clone: the clone is missing or incomplete, and sync never re-clones. status prints the team join command that restores it.

#The app cannot find terum-skills

The desktop app could not find where terum-skills is installed. Run `terum-skills app` from a terminal once; it records the location and opens this app.

The app runs the CLI that the app command recorded, so opened before app ever ran, it has nothing to run. Run it once. Running it again after you install or move Claude Code records the new PATH the app’s evals use.

$ npx -y terum-skills@latest app

#There is no app on Linux or WSL

There is no Linux desktop app yet; everything works from the terminal.

Nothing failed: the app is built for macOS and Windows, and every command works from the terminal. Inside WSL, install terum-skills on the Windows side and run app there. See Desktop app.