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.)

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).

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