Troubleshooting — Runtime & Skills

/orchestrator (or another slash command) not found in Claude Code

1. Confirm skills are installed where Claude Code looks:

   ls .claude/skills/          # project scope (default)
   ls ~/.claude/skills/        # user scope (--global installs)

2. If empty, run the init from the project root:

   sdtk init --runtime claude --force

3. Restart the Claude Code session — skills are loaded at session start.

Codex doesn't see the skills

Codex resolves skills from $CODEX_HOME/skills/ (default ~/.codex/skills/).

echo $CODEX_HOME
ls "${CODEX_HOME:-$HOME/.codex}/skills/"

Common causes:

• Project-scope install, user-scope launch. If you initialized with CODEX_HOME=<project>/.codex, you must also launch Codex with that same variable: CODEX_HOME=$(pwd)/.codex codex. See the launch contract.
• Skills never installed. Run sdtk init --runtime codex (user scope) and check again.

Expecting an /agent or wiki slash command

There isn't one — by design. SDTK-WIKI and SDTK-AGENT install no skills; they are CLI-driven:

sdtk-wiki atlas open
sdtk-agent run status --run-id <run_id>

If a session invents an /agent command, that's a hallucination — the supported surface is the sdtk-agent CLI.

Skills are stale after sdtk update

Updating npm packages does not touch installed skills. Refresh them per project:

sdtk update
sdtk init --runtime claude --force    # or --runtime codex

Skills installed to the wrong scope

Re-run init with an explicit scope; --force overwrites the previous install:

sdtk init --runtime claude --runtime-scope user --force     # move to ~/.claude/skills/
sdtk init --runtime claude --runtime-scope project --force  # move into the repo

(Remove the old location's sdtk-* skill folders if you want a clean single-scope setup.)

Status line missing on one account but not the other

Almost always one of two deliberate no-ops in sdtk statusline install, not a broken install. Ask the CLI which:

sdtk statusline status

• not installed on the account you expected — install targets only the account you ran it under ($CLAUDE_CONFIG_DIR, else ~/.claude), so running it once does not cover a second account. Since v1.51.0 the install output names the accounts it skipped.
• other command: … — that account already has a statusLine pointing somewhere else (typically a hand-written script predating SDTK). Install refuses to clobber it.

One command covers both. Each settings.json is backed up to settings.json.bak.<timestamp> first:

sdtk statusline install --all --force

Then open a new session — the status line is read at session start, so an already-open one will not pick it up. Note that logging out and back in changes nothing here: the status line lives in settings.json, which is config, not credentials.

If a row says installed and you still see nothing, check sdtk statusline render runs (it needs sdtk on PATH — see sdtk: command not found), and confirm your Claude Code version supports statusLine.

Sessions ignore SDTK routing

Init writes session guidance (CLAUDE.md for Claude Code, AGENTS.md for Codex) at the project root. If routing (discovery gate, phase pipeline, orchestrator intake) isn't happening:

• confirm those files exist at the project root and are not overridden by conflicting instructions;
• start the session from the project root, not a subdirectory;
• invoke the orchestrator explicitly (/orchestrator in Claude Code, "Use the orchestrator skill." in Codex).

sdtk init refuses a repo that already has AGENTS.md / CLAUDE.md / SDTK config

Full init writes those managed files, so it refuses roots where they are repo-owned rather than SDTK-managed. If you only need the slash-command skills there, use the skills-only path — it touches nothing but the skills directory:

sdtk runtime install --runtime claude    # skills into <repo>/.claude/skills, nothing else
sdtk runtime status --runtime claude     # verify per-kit install state

See sdtk runtime for all options.

A command the docs don't list

If a session suggests a verb that isn't in the command reference — e.g. sdtk-ops deploy (no such verb) — check Maturity & Versions. SDTK docs only document the installable surface; anything else is either unpublished, gated, or invented.

Diagnostics to attach to a bug report

sdtk --version
sdtk-spec runtime status
sdtk-code doctor
node --version

Issues: github.com/codexsdtk/sdtk-toolkit