How to use the Stuck Session Diagnostics agent skill

What is an agent skill, and what does the stuck skill make the agent do?

An agent skill is a folder of instructions that an AI agent loads when a request matches it. The stuck skill is defined in a single SKILL.md file, and its purpose is narrow: investigate another Qwen Code session that the user believes is frozen, stuck or very slow.

The skill tells the agent to scan for other Qwen Code processes, excluding the one running the skill. It looks for signs such as sustained high CPU, uninterruptible sleep, a stopped state, a zombie state, very high memory use, or a stuck child process, then presents a diagnostic report. If you give it a process ID, it focuses on that process.

• Checks CPU use and samples it twice, 1-2 seconds apart, to confirm a spike is not transient.
• Checks process state to spot I/O hangs, accidental Ctrl+Z pauses and zombie processes.
• Checks memory use against a 4GB threshold.
• Looks for hung child processes such as git, node or shell subprocesses.
• Reads runtime and debug log files to help explain what went wrong.

How do you install the stuck skill?

Download the ZIP file for the skill from this page and unzip it. The skill's files, including SKILL.md, need to end up in a skills folder that Qwen Code can read. You can install it for yourself across all projects or only for one project.

For a personal install, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the stuck skill?

You can ask for it in plain language, or use the slash command. The skill's description says to use /stuck to scan generally, or /stuck <PID> to focus on one specific process. The argument can be a process ID made only of digits. Any other text is treated as a description of the symptom, which guides the report but is never placed into shell commands.

To find a process ID, look at the session you suspect, or check the runtime sidecar files the skill uses to map process IDs to sessions.

• /stuck to scan all Qwen Code sessions for this user
• /stuck 12345 to focus on process ID 12345 (digits only)
• /stuck the screen stopped updating to describe a symptom instead of a PID

What do natural requests look like?

You do not have to type the command. A request that describes the problem should also match the skill, because its description covers frozen, stuck, slow and high CPU or memory sessions. Be specific about which session you mean if you run several at once.

• My other Qwen Code session has frozen. Can you check whether it is stuck?
• I think I pressed Ctrl+Z in another Qwen session. Is it just paused?
• Is my slow Qwen Code session using a lot of CPU or memory?
• One of my Qwen Code sessions stopped responding. Find out why.

What does the report tell you, and what does the skill not do?

The skill reports what it found and what the process state suggests. It is written to diagnose and report, not to fix. It does not change or kill processes, so if the report says a session is stuck, you decide what to do next.

Process state explains some cases directly. A stopped state usually means a session was paused by Ctrl+Z, while a sustained high CPU reading suggests a possible loop. The skill reads debug logs to help explain the cause, but the report is a guide rather than a guarantee.

• Stopped state (T): often an accidental Ctrl+Z.
• Sustained CPU of 90% or more: possible infinite loop.
• Uninterruptible sleep (D on Linux, U on macOS): often an I/O hang.
• Zombie state (Z): the parent process is not reaping it.
• Low CPU in sleep state: a possible hung request to the model API, checked with a network check.

What does the skill need, and what are the safety notes?

The skill needs Node.js, because Qwen Code requires it. It also needs a POSIX shell with ps, grep and standard tools, so it is meant for macOS or Linux. jq is optional and is used only to read settings if present. The skill runs scripts, and it does not use the network.

The skill only looks at processes owned by the current user, so it does not expose other users' process details on shared machines. Command lines can contain credentials passed as arguments, and the skill is written to redact values such as API keys before quoting them. Still, do not use it on a shared machine where you should not inspect another person's session details without permission.

• Runs scripts: yes. Uses network: no.
• Requires Node.js, a POSIX shell with ps and grep (macOS or Linux), and optionally jq.
• Only inspects Qwen Code processes owned by the current user.
• Not for problems with other programs or the operating system in general.
• Not for shared machines where inspecting session details is not allowed.