Stuck Session Diagnosis

Use when another Claude Code session appears frozen, stuck, or abnormally slow and needs process-level diagnosis and reporting.

Security Scan

The skill's instructions and requirements are consistent with a local-process diagnostic helper; it asks for no credentials or installs and stays within its stated purpose, though the instructions are somewhat open-ended about which logs to inspect.

Purpose & Capability

The name/description (diagnose frozen or slow local agent sessions) match the SKILL.md workflow steps (list processes, check CPU/RSS/state/children, sample, inspect debug logs, produce report). No unrelated credentials, binaries, or installs are requested.

Instruction Scope

Instructions stay on-topic (process inspection and log review) and include guardrails (do not kill processes by default). However, they are permissive about which debug logs to inspect ('when possible') and do not explicitly constrain file paths or data collection — this could lead the agent to read broader system or user logs while diagnosing.

Install Mechanism

Instruction-only skill with no install spec and no code files. Lowest-risk delivery: nothing is written to disk by an installer.

Credentials

No environment variables, credentials, or config paths are required. This is proportionate to a local diagnostic skill.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide configuration or elevated/ongoing privileges. The agent may run it autonomously per platform defaults, which is expected for skills.

Assessment

This skill appears to be a straightforward helper for inspecting local agent processes and assembling a diagnosis report. Before installing or invoking it, be aware that diagnosing a process often requires reading process tables and debug logs — those logs can contain sensitive information. If you run this on a multi-user machine or a system with sensitive application logs, consider: (1) running diagnostics interactively rather than allowing autonomous invocation, (2) restricting which log directories the agent may read, and (3) ensuring the agent runs with the minimum necessary permissions. If you need more assurance, ask the skill author to (a) list the exact commands/paths it will read, or (b) scope log inspection to specific known agent log locations.

Use this skill to investigate slow or frozen local agent sessions.

Workflow

1. List candidate agent processes.
2. Check CPU, RSS, state, uptime, and child processes.
3. Sample suspicious processes again to confirm sustained issues.
4. Inspect related debug logs when possible.
5. Produce a concise diagnosis and escalation-ready report.

Guardrails

• Diagnostic only: do not kill or signal processes unless asked.
• Confirm suspicious metrics are sustained, not transient.
• Keep the final report focused on actionable symptoms.

Example Requests

• Find out why another Claude session on this machine is frozen.
• Inspect local agent processes and tell me if one is hung.

Inputs

• Observed symptom
• Process state
• Optional target PID

Outputs

• Diagnosis summary
• Evidence from process inspection
• Escalation-ready report

Success Criteria

• Suspicious sessions were confirmed rather than guessed.
• Supporting process data was captured.
• The report is concise and actionable.

Non-Goals

• Killing processes by default
• Reporting transient blips as confirmed hangs

Source Provenance

Derived from src/skills/bundled/stuck.ts.