Guide · Agent skill

How to use the qzcli Qizhi GPU Job Manager agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

qzcli is an agent skill that teaches an AI agent to operate qzcli, a kubectl-style command-line tool for GPU compute jobs on the Qizhi (启智) platform. This guide explains what the skill lets the agent do, how to install it, how to ask for things in plain language, and what to check before the agent submits real jobs. It is aimed at readers who already have a Qizhi account and have not used agent skills before.

Qizhi GPU Job Managerwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
2Install qzcli. Install the Python packages rich, requests, prompt_toolkit and mcp, then clone tianyilt/qzcli_tool and run pip install -e . inside it.
3Add your credentials. Create ~/.qzcli/.env with QZCLI_USERNAME and QZCLI_PASSWORD, or export them as environment variables.
4Log in and cache resources. Run qzcli login, then qzcli res -u to cache workspaces and compute groups.
5Check nodes and jobs. Run qzcli avail to see free nodes and qzcli ls -c -r to list running jobs.
6Ask the agent in plain language. Use a request containing a trigger phrase such as submit job or list jobs, naming the workspace or job ID.
7Dry-run before submitting. Ask for --dry-run on create or batch, review the preview, then approve the real submission.

What an agent skill is and what qzcli lets the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific task. When the request matches the skill's description, the agent reads those instructions and runs the commands they describe.

Once qzcli is installed, the agent can log in to a Qizhi instance, check which compute nodes are free, list running jobs, and submit single, batch, or CPU/Slurm jobs. The skill's own description says it is for managing distributed training jobs on a Qizhi instance.

Check available compute nodes (avail)
List and watch jobs, and check job status
Create single jobs, including interactive selection
Submit batches from a JSON config file
Submit CPU/Slurm (HPC) jobs
Stop a job by ID

Install the qzcli skill

Download the qzcli ZIP from this page and unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings → Capabilities → Skills and upload the ZIP there.

Personal: unzip into ~/.claude/skills/
Per project: unzip into .claude/skills/ in the project folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the qzcli tool and its requirements

The skill calls the qzcli command-line tool, which must be installed separately. The SKILL.md lists these Python packages: rich, requests, prompt_toolkit and mcp. The tool itself is installed from its GitHub repository (tianyilt/qzcli_tool) in editable mode.

The MCP integration is optional. It lets Claude Code or Codex call qzcli as a tool directly.

Python with the packages rich, requests, prompt_toolkit and mcp
The qzcli_tool package installed from GitHub with pip install -e
Optional: Claude Code or Codex for MCP integration

pip install rich requests prompt_toolkit mcp
git clone https://github.com/tianyilt/qzcli_tool
cd qzcli_tool && pip install -e .

# Optional, Claude Code
claude mcp add qzcli -- qzcli-mcp

Set up your Qizhi credentials

You need a Qizhi platform account with a username and password. The skill cannot reach the service without them. The source recommends storing them in an env file at ~/.qzcli/.env. You can also set them as environment variables.

Credentials are read in this order: CLI arguments, --password-stdin, environment variables, the QZCLI_ENV_FILE file, ~/.qzcli/config.json, then interactive input. Config files live in ~/.qzcli/ and include config.json, .cookie, resources.json and jobs.json.

Recommended: ~/.qzcli/.env with QZCLI_USERNAME and QZCLI_PASSWORD
Alternative: export the same variables, and QZCLI_API_URL if your instance uses its own address

mkdir -p ~/.qzcli
cat > ~/.qzcli/.env <<'EOF'
QZCLI_USERNAME="your_username"
QZCLI_PASSWORD="your_password"
EOF

Run the first-time setup and check nodes

Run these steps once. Log in, then cache your workspaces and compute groups so that names can be resolved. Re-run the cache refresh after you join a new workspace. Then check free nodes and list running jobs.

Once this works, you can ask the agent for the same things in plain language.

qzcli login
qzcli res -u
qzcli avail
qzcli ls -c -r

Trigger the skill with natural requests

The skill activates on phrases such as "qzcli", "启智平台", "submit job", "stop job", "查计算组", "avail", "list jobs" and "batch submit", or when you need to manage distributed training jobs on a Qizhi instance. Name the action and the workspace or job when you can.

Good requests say what you want and where. Vague requests make the agent ask follow-up questions, which is fine.

"Use qzcli to check which compute groups in My Workspace have 4 free nodes."
"List my running jobs on Qizhi."
"Preview a batch submit from batch_config.json with --dry-run."
"Stop job JOB_ID on the Qizhi platform."

Preview before any real submission

The agent can submit real jobs, so a wrong command can use quota or start work you did not intend. The tool supports a --dry-run flag on create and batch. Ask for a dry run first and read the output before approving the real submit.

Batch configs expand a matrix into the Cartesian product of its values. A 2 by 2 matrix produces 4 jobs, so check the count in the dry run.

Always dry-run create and batch requests first
Check workspace, compute group, spec ID and image in the preview
Confirm the job count for batch submissions

qzcli batch batch_config.json --dry-run

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its allowed tools include Bash(*), Read and Write, so the agent can run shell commands on your machine. It talks to your Qizhi instance over the network using your credentials.

Keep credentials in ~/.qzcli/.env or environment variables rather than in chat or in shared files. Only use the skill where the compute is yours to spend. Review commands the agent proposes, especially those that submit or stop jobs.

Runs scripts and uses network access
Credentials are sent to your Qizhi instance; store them in the env file or environment variables
Shared or paid compute: a wrong or un-previewed submit may consume quota

Tips for smoother use

Run qzcli res -u after joining a workspace, or when you see a workspace-not-found error. For interactive selection, qzcli create -i shows GPU type, availability and spec status at each level.

When you run scripts that depend on environment variables, pass them directly on the command line rather than exporting them first. Remote shells may be zsh, so wrap complex commands in bash -c or use Python if glob errors appear.

Refresh the resource cache with qzcli res -u when names fail to resolve
Use --json for scripting output
Use qzcli watch -i 10 to refresh running jobs every 10 seconds

WORKSPACE_ID="ws-YOUR_WORKSPACE_ID" LCG_ID="lcg-YOUR_LCG_ID" bash YOUR_SUBMIT_SCRIPT.sh

What people use it for

Checking which compute groups have enough free nodes before launching a distributed training run.
Submitting a parameter sweep of evaluation jobs from a batch JSON config with a matrix of checkpoints and steps.
Listing running jobs in a workspace and stopping one that is stuck, by job ID.
Submitting CPU-only Slurm jobs through the qzcli hpc command for data processing or preprocessing.
Watching running jobs and GPU utilization with qzcli watch and qzcli ws.

Frequently asked questions

How do I install the qzcli agent skill?

Download the qzcli ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills. You also need to install the qzcli_tool package from GitHub.

What do I need to use qzcli?

You need Python with rich, requests, prompt_toolkit and mcp, the qzcli_tool package installed with pip install -e, and a Qizhi platform account with a username and password. Claude Code or Codex is optional, for MCP integration.

Is qzcli free to use?

The source does not state a licence fee or pricing for the Qizhi platform. The skill's repository is listed under the MIT licence. Your compute costs depend on your Qizhi account and organisation, so check those terms directly.

Where do I store my Qizhi password?

The source recommends a file at ~/.qzcli/.env containing QZCLI_USERNAME and QZCLI_PASSWORD, or the same values as environment variables. Credentials can also be passed on the command line or read from stdin with --password-stdin.

Why does qzcli say a workspace is not found?

The workspace name is probably missing from the local cache. Run qzcli res -u to refresh the cache, and run qzcli login first if the cache is empty. The source lists these as the fixes for the workspace-not-found and empty-resource errors.

Can I use qzcli without an agent?

Yes. qzcli is a command-line tool, and the commands in the skill can be run directly in a terminal, for example qzcli avail or qzcli ls -c -r. The skill simply lets an agent run them for you.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

qzcli suits researchers and teams who already have a Qizhi platform account and regularly submit GPU training, evaluation or batch jobs there. It is a poor fit if you have no account, or if you want an agent to act without reviewing previews on shared or paid compute, since the agent can submit and stop real jobs.

Download the skill