feat(cli): add a doctor command that checks the setup before a paid run

Open
#407 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
bash, docker, go, nodejs

Research direction

This is a cross-cutting design task across the Go CLI. Start with the static preflight from #233 and the validate command, then read internal/agent/claude_code.go and internal/judge/script.go to see how credentials and script judges run. Done means skill-up doctor prints an ok, warn or fail line per check, exits non-zero on failure, and supports --json, with the design agreed in the thread first.

Written by the indexing model from the issue text.

Description

Problem / motivation

First runs often fail on environment details, and users find them one at a time in issue threads, after starting a run. Windows shows it most:

  • #160: tokens always 0.
  • #279: "不支持window?" (is Windows not supported?).
  • #292: MSYS2 truncates long arguments, root-caused by the reporter.
  • #354: a junction TEMP, then an OpenCode PWD problem.

skill-up already has a static preflight (#233) and credential checks, but they run only inside run, and validate checks the files, not the machine.

Proposed solution

skill-up doctor [evals/eval.yaml]. It makes no model calls and prints one line per check, each as ok, warn or fail, with a fix hint:

  1. Runtime: for none, the shell skill-up will use. For docker, the daemon is reachable. For opensandbox, the endpoint answers.
  2. Engine: the CLI is found, and its version is shown next to the version skill-up installs by default. On none this is the host; on Docker and OpenSandbox, the check reports what setup will install rather than probing the host.
  3. Credentials: report which of three states applies, without printing a value: credentials injected from config or the environment, a local CLI login detected, or a login that cannot be confirmed without a model call. The last is a warning, not a failure, since Claude Code and Codex deliberately run on an existing login when no key is set (claude_code.go#L108).
  4. Tools the suite needs, where they will run: node for mocked MCP servers and the interpreters script judges need. Script judges run in the case runtime (script.go#L117), so on none this checks the host, and on a container runtime it checks the image or setup steps.
  5. Windows: the Bash that will be used (SKILL_UP_BASH), the temp folder, and known path problems.
  6. With an eval path: the result of validate for that suite.

Add --json output, and a non-zero exit when any check fails, so CI and skill-upper can call it before spending tokens.

Alternatives considered

  • validate plus --dry-run. Neither checks the engine, the credentials or the host.
  • A troubleshooting page in the docs. It helps, but users still find their problem by trial.

Additional context

  • #233 added the static runtime preflight that doctor can reuse.
  • #281 and #287 check the Skill's content. This issue checks the machine.
  • #48 covers Windows end-to-end coverage for the agent CLIs.
Dominant language
Go
Stars
1.5k
Forks
134
Avg merge
1d 22h
Merged PRs (30d)
61

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from alibaba/skill-up

All issues in alibaba/skill-up

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.