linux-troubleshooting
Diagnoses problems on Linux machines in a structured, read-only-first way. Use whenever the user reports a slow or frozen system, full disk, out-of-memory kills, a service that will not start, a port that is not reachable, DNS or network failures, permission denied or SELinux err
Install
npx skills add https://github.com/MehranQadirian/skills/tree/main/devops/linux-troubleshooting
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
git clone https://github.com/MehranQadirian/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.
README
linux-troubleshooting
A Claude skill for diagnosing Linux problems with a read-only snapshot and clear playbooks.
What it does
- Takes a read-only health snapshot with
sysdiag.shand flags thresholds: load, memory, swap, disk, inodes, failed units, no default route - Maps symptoms to playbooks: slow machine, full disk, failing service, closed port, DNS, permissions and SELinux
- Insists on logs first, one change at a time and an undo for each step
- Handles Fedora and Debian family differences
Try it
My laptop is very slow and the fan is loud. Help me find out why.
The disk shows full but I deleted a lot of files.
My service fails to start after the update.
Install
Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.
Claude Code:
cp -r devops/linux-troubleshooting ~/.claude/skills/
Structure
linux-troubleshooting/
├── SKILL.md skill instructions for Claude
├── scripts/sysdiag.sh read-only health snapshot
└── references/playbooks.md symptom playbooks
Skill manifest
linux-troubleshooting
Find the cause before changing anything. A read-only snapshot gives facts in seconds; the playbooks turn symptoms into the next command.
linux-troubleshooting/
├── SKILL.md
├── scripts/
│ └── sysdiag.sh load, memory, swap, disk and inodes, failed units, journal errors, network, ports
└── references/
└── playbooks.md slow machine, disk full, services, ports, DNS, permissions, SELinux, logs, safety
When to use
- Slow, frozen or overheating machine
- Disk or inode exhaustion, memory pressure, OOM kills
- A systemd service fails or keeps restarting
- Something cannot connect, or a port does not answer
- Permission or SELinux denials
- A routine health check of a server or workstation
Workflow
- Get the facts: run
bash scripts/sysdiag.sh(use--brieffor warnings only). It never uses sudo and never changes anything. Thresholds can be adjusted withDISK_WARN,INODE_WARN,MEM_WARN,SWAP_WARN,LOAD_FACTOR. - Read the verdict: each warning names the subsystem. Pick the matching playbook in
references/playbooks.md. - State a hypothesis and the command that would disprove it, then run only read-only commands first. Ask the user for the output and wait; do not guess results.
- Check logs before restarting:
journalctl -u NAME -b,journalctl -b -p err. A restart can destroy the evidence. - Change one thing at a time, with a backup (
cp file file.bak) and a way to undo. Explain what the command does and the risk before the user runs it. - Verify the fix with the same observation that showed the problem, and say what else to watch.
Rules
- Read-only commands first; confirm before
rm,kill -9,chmod -R,dd,mkfs, firewall or SELinux changes - Never recommend
chmod -R 777, disabling SELinux or turning off the firewall as a diagnostic shortcut - Match the distribution: Fedora and RHEL use
dnf,firewalld, SELinux; Debian and Ubuntu useapt,ufw, AppArmor - Do not run commands for the user; give them, with expected output and what it means
- Say what you could not see (no sudo, no journal access) instead of guessing
- Remote servers: warn before any command that could cut the SSH session (network, firewall, sshd)
What to report back
| Field | Content |
|---|---|
| Symptom | what was observed, with the numbers |
| Evidence | commands and the lines that matter |
| Cause | the most likely one, and how sure |
| Fix | steps in order, with undo for each |
| Verification | how to confirm, and what to monitor |
Related skills
systematic-debugging: the general reproduce, isolate, prove methoddocker-basics: container disk usage, ports and permissionsshell-scripting: write the checks you will run repeatedly as safe scriptstermux-setup: Android specific problems
Files (skills)
-
references
-
playbooks.md 4.1 KB
Loading…
-
-
scripts
-
sysdiag.sh 4.3 KB
Loading…
-
-
README.md 1.1 KB
# linux-troubleshooting A [Claude skill](../../README.md) for diagnosing Linux problems with a read-only snapshot and clear playbooks. ## What it does - Takes a read-only health snapshot with `sysdiag.sh` and flags thresholds: load, memory, swap, disk, inodes, failed units, no default route - Maps symptoms to playbooks: slow machine, full disk, failing service, closed port, DNS, permissions and SELinux - Insists on logs first, one change at a time and an undo for each step - Handles Fedora and Debian family differences ## Try it > My laptop is very slow and the fan is loud. Help me find out why. > The disk shows full but I deleted a lot of files. > My service fails to start after the update. ## Install **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload. **Claude Code:** ```bash cp -r devops/linux-troubleshooting ~/.claude/skills/ ``` ## Structure ``` linux-troubleshooting/ ├── SKILL.md skill instructions for Claude ├── scripts/sysdiag.sh read-only health snapshot └── references/playbooks.md symptom playbooks ``` -
SKILL.md 3.3 KB
--- name: linux-troubleshooting description: Diagnoses problems on Linux machines in a structured, read-only-first way. Use whenever the user reports a slow or frozen system, full disk, out-of-memory kills, a service that will not start, a port that is not reachable, DNS or network failures, permission denied or SELinux errors, or asks to check the health of a server or laptop, even if they only say "my Fedora is acting weird". Starts with a read-only snapshot script and never suggests destructive commands as a first step. --- # linux-troubleshooting Find the cause before changing anything. A read-only snapshot gives facts in seconds; the playbooks turn symptoms into the next command. ``` linux-troubleshooting/ ├── SKILL.md ├── scripts/ │ └── sysdiag.sh load, memory, swap, disk and inodes, failed units, journal errors, network, ports └── references/ └── playbooks.md slow machine, disk full, services, ports, DNS, permissions, SELinux, logs, safety ``` ## When to use - Slow, frozen or overheating machine - Disk or inode exhaustion, memory pressure, OOM kills - A systemd service fails or keeps restarting - Something cannot connect, or a port does not answer - Permission or SELinux denials - A routine health check of a server or workstation ## Workflow 1. **Get the facts**: run `bash scripts/sysdiag.sh` (use `--brief` for warnings only). It never uses sudo and never changes anything. Thresholds can be adjusted with `DISK_WARN`, `INODE_WARN`, `MEM_WARN`, `SWAP_WARN`, `LOAD_FACTOR`. 2. **Read the verdict**: each warning names the subsystem. Pick the matching playbook in `references/playbooks.md`. 3. **State a hypothesis and the command that would disprove it**, then run only read-only commands first. Ask the user for the output and wait; do not guess results. 4. **Check logs before restarting**: `journalctl -u NAME -b`, `journalctl -b -p err`. A restart can destroy the evidence. 5. **Change one thing at a time**, with a backup (`cp file file.bak`) and a way to undo. Explain what the command does and the risk before the user runs it. 6. **Verify the fix** with the same observation that showed the problem, and say what else to watch. ## Rules - Read-only commands first; confirm before `rm`, `kill -9`, `chmod -R`, `dd`, `mkfs`, firewall or SELinux changes - Never recommend `chmod -R 777`, disabling SELinux or turning off the firewall as a diagnostic shortcut - Match the distribution: Fedora and RHEL use `dnf`, `firewalld`, SELinux; Debian and Ubuntu use `apt`, `ufw`, AppArmor - Do not run commands for the user; give them, with expected output and what it means - Say what you could not see (no sudo, no journal access) instead of guessing - Remote servers: warn before any command that could cut the SSH session (network, firewall, sshd) ## What to report back | Field | Content | |-------|---------| | Symptom | what was observed, with the numbers | | Evidence | commands and the lines that matter | | Cause | the most likely one, and how sure | | Fix | steps in order, with undo for each | | Verification | how to confirm, and what to monitor | ## Related skills - `systematic-debugging`: the general reproduce, isolate, prove method - `docker-basics`: container disk usage, ports and permissions - `shell-scripting`: write the checks you will run repeatedly as safe scripts - `termux-setup`: Android specific problems
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.