Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download mehranqadirian-skills-devops_linux-troubleshooting-c88187d.zip · 6 KB

Install

skills CLI npx skills add https://github.com/MehranQadirian/skills/tree/main/devops/linux-troubleshooting
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
Git 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.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:

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

  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
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.

No comments yet.

Reviews (0)

No reviews yet.