repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

add linux skills

219a5c1bc51d28c52127787092855807e0a79012

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

skills/linux-userland/SKILL.md

Added
new file mode 100644
1 +---
2 +name: linux-userland
3 +description: Use when editing or diagnosing Linux user-owned configuration, XDG paths, shell environment, PATH issues, dotfiles, user systemd units, desktop/session config, caches, state dirs, or app config under HOME.
4 +---
6 +# Linux Userland
8 +Linux config work inside the user's ownership boundary.
10 +**Boundary:** operate under `$HOME` and user managers only. If a fix needs `/etc`, `/usr`, `/var/lib`, packages, kernel settings, devices, or `sudo`, stop and use `linux` escalation.
12 +## Workflow
14 +1. Identify app/tool, config file discovery rules, and current user/session.
15 +2. Resolve XDG paths; do not hard-code `~/.config` if env overrides exist.
16 +3. Read installed docs: `man`, `--help`, app config docs in repo/package.
17 +4. Inspect current config/env/state.
18 +5. Back up before edits; make minimal change.
19 +6. Validate with app-specific parser/check command.
20 +7. Reload/restart only user-owned process/service. Provide rollback.
22 +## XDG Paths
24 +| Purpose | Env | Default |
25 +|---|---|---|
26 +| Config | `XDG_CONFIG_HOME` | `$HOME/.config` |
27 +| Data | `XDG_DATA_HOME` | `$HOME/.local/share` |
28 +| State/logs/history | `XDG_STATE_HOME` | `$HOME/.local/state` |
29 +| Cache | `XDG_CACHE_HOME` | `$HOME/.cache` |
30 +| Runtime sockets | `XDG_RUNTIME_DIR` | set by login/session |
32 +Probe safely:
34 +```bash
35 +printf 'HOME=%s\nXDG_CONFIG_HOME=%s\nXDG_DATA_HOME=%s\nXDG_STATE_HOME=%s\nXDG_CACHE_HOME=%s\nXDG_RUNTIME_DIR=%s\n' \
36 + "$HOME" "${XDG_CONFIG_HOME:-$HOME/.config}" "${XDG_DATA_HOME:-$HOME/.local/share}" \
37 + "${XDG_STATE_HOME:-$HOME/.local/state}" "${XDG_CACHE_HOME:-$HOME/.cache}" "${XDG_RUNTIME_DIR:-}"
38 +```
40 +XDG env vars must be absolute paths to be valid.
42 +## Shell + Environment Diagnosis
44 +The agent's tool shell may not equal the user's interactive shell. Detect before giving syntax:
46 +```bash
47 +printf 'SHELL=%s\n' "$SHELL"
48 +getent passwd "$(id -un)" | awk -F: '{print "login_shell=" $7}'
49 +printf 'PATH=%s\n' "$PATH" | tr ':' '\n'
50 +```
52 +Startup files by shell:
54 +| Shell | Common user files | PATH/export syntax |
55 +|---|---|---|
56 +| bash | `~/.bashrc`, `~/.bash_profile`, `~/.profile` | `export NAME=value` |
57 +| zsh | `~/.zshrc`, `~/.zprofile`, `~/.zshenv` | `export NAME=value` |
58 +| fish | `~/.config/fish/config.fish` | `set -gx NAME value`; `fish_add_path DIR` |
59 +| nushell | `~/.config/nushell/env.nu`, `config.nu` | `$env.NAME = value` |
61 +Prefer editing the shell's config file over emitting complex copy-paste snippets. If root is needed, do not craft fish/nushell sudo heredocs; use `linux` script escalation.
63 +## User systemd Units
65 +User units live primarily in `$XDG_CONFIG_HOME/systemd/user` (default `~/.config/systemd/user`).
67 +Read:
69 +```bash
70 +systemctl --user --no-pager --full list-units --failed
71 +systemctl --user --no-pager --full status UNIT
72 +systemctl --user show UNIT -p LoadState -p ActiveState -p SubState -p Result -p ExecMainStatus
73 +systemctl --user cat UNIT
74 +journalctl --user-unit UNIT -b --no-pager --full -n 200
75 +systemd-analyze --user verify "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/UNIT"
76 +```
78 +After editing a user unit:
80 +```bash
81 +systemctl --user daemon-reload
82 +systemctl --user status UNIT --no-pager --full
83 +journalctl --user-unit UNIT -b --no-pager --full -n 100
84 +```
86 +Restart only if the user asked for restart or the service was active before edit:
88 +```bash
89 +systemctl --user restart UNIT
90 +```
92 +Use `enable --now` only when the user asked for autostart.
94 +## Safe Edit Pattern
96 +```bash
97 +file=/path/to/file
98 +backup="$file.bak.$(date +%Y%m%d-%H%M%S)"
99 +cp -a "$file" "$backup"
100 +# edit "$file"
101 +# run validator/reload
102 +# rollback if bad: cp -a "$backup" "$file"
103 +```
105 +Validation examples:
106 +- systemd user unit: `systemd-analyze --user verify FILE`
107 +- shell config: run the shell parser if available (`bash -n FILE`, `zsh -n FILE`); fish/nushell need shell-specific checks.
108 +- app config: use the app's documented `check`, `validate`, `doctor`, or dry-run command.
110 +## Common Mistakes
112 +| Mistake | Fix |
113 +|---|---|
114 +| Editing `/etc` from userland task | Stop; use `linux` escalation |
115 +| Assuming bash syntax | Detect shell; prefer editing files or POSIX `sh` scripts |
116 +| Ignoring XDG overrides | Resolve env/defaults first |
117 +| Restarting system service | Only use `systemctl --user`; escalate otherwise |
118 +| Changing config without rollback | Backup + validate + rollback command |

skills/linux/SKILL.md

Added
new file mode 100644
1 +---
2 +name: linux
3 +description: Use when diagnosing Linux system issues, asking about host state, systemd/journal logs, services, boot/session problems, permissions, devices, networking, or when a task may need root escalation.
4 +---
6 +# Linux
8 +Safe Linux diagnosis for agents without root.
10 +**Boundary:** read system state; do not mutate system config. For user-owned config under `$HOME`, also use `linux-userland`.
12 +## Non-Negotiables
14 +- No `sudo`, `su`, `doas`, `pkexec`, package manager install/remove, service mutation, `/etc` edits, kernel/sysctl changes, or device writes from the agent.
15 +- Read-only probes first. Prefer commands with `--no-pager`, `--full`, bounded output, and explicit units/time ranges.
16 +- Prefer installed truth: `man`, `--help`, distro files. Web docs may not match host version.
17 +- Redact secrets from env, tokens, key files, URLs, logs, and command output.
18 +- If root is required, explain why and give a copy-paste command or script for the human to run.
20 +## Workflow
22 +1. Classify: user config? → `linux-userland`. system state/root/service/device/package? → continue here.
23 +2. Inventory host facts before hypotheses.
24 +3. Inspect installed docs for exact command/config behavior.
25 +4. Gather bounded logs/status.
26 +5. State root cause confidence + evidence. If changing system state is needed, escalate to human.
28 +## Read-Only Inventory
30 +```bash
31 +uname -a
32 +cat /etc/os-release
33 +id
34 +printf 'SHELL=%s\n' "$SHELL"
35 +getent passwd "$(id -un)"
36 +systemctl --version 2>/dev/null || true
37 +loginctl show-user "$(id -un)" 2>/dev/null || true
38 +```
40 +## Installed Documentation
42 +```bash
43 +MANWIDTH=100 MANPAGER=cat man systemctl | col -b | head -120
44 +MANWIDTH=100 MANPAGER=cat man 5 systemd.service | col -b | rg -n 'ExecStart|Type=|Restart='
45 +man -k 'journal|systemd|network'
46 +<command> --help 2>&1 | head -80
47 +```
49 +Use section numbers: `man 1 command`, `man 5 config-file`, `man 7 topic`, `man 8 admin-command`.
51 +## systemd Diagnosis
53 +System manager is OS-level. User manager is per-user; see `linux-userland` for editing user units.
55 +```bash
56 +systemctl --no-pager --full status UNIT
57 +systemctl --no-pager --full list-units --failed
58 +systemctl show UNIT -p LoadState -p ActiveState -p SubState -p Result -p ExecMainStatus
59 +systemctl cat UNIT
60 +systemd-analyze verify /path/to/unit.service
61 +```
63 +`systemctl status` is for humans. `systemctl show` is for parseable properties.
65 +## Network Read-Only Probes
67 +```bash
68 +ip addr
69 +ip route
70 +resolvectl status 2>/dev/null || true
71 +```
73 +## journalctl Diagnosis
75 +Always bound logs:
77 +```bash
78 +journalctl -b --no-pager -n 200
79 +journalctl -b -u UNIT --no-pager --full -n 200
80 +journalctl -b --since '1 hour ago' -p warning..alert --no-pager
81 +journalctl --list-boots --no-pager
82 +```
84 +Unprivileged users may not read system journal. If denied, report the permission boundary; do not try `sudo`.
86 +## Root Escalation
88 +Escalate only after read-only evidence shows user privileges are insufficient.
90 +Prefer direct commands with no shell syntax:
92 +```text
93 +Please run:
95 +sudo systemctl status UNIT --no-pager --full
96 +```
98 +For multi-step or shell-sensitive actions, write a POSIX shell script in a user-owned path and ask the human to run:
100 +```text
101 +Please review, then run:
103 +sudo sh /tmp/pi-root-action.sh
104 +```
106 +Write the script to a path without spaces, e.g. `/tmp/pi-root-action.sh` or `$HOME/.cache/pi-root-action.sh`; quote the path if needed. This avoids bash/zsh/fish/nushell syntax differences. Include:
107 +- what it changes
108 +- pre-checks
109 +- backup path when editing
110 +- rollback command
111 +- verification command
113 +If inline syntax is unavoidable, detect likely login shell first:
115 +```bash
116 +getent passwd "$(id -un)" | awk -F: '{print $7}'
117 +printf '%s\n' "$SHELL"
118 +```
120 +Then provide syntax for that shell only, plus a POSIX `sh` alternative when possible.
122 +## Common Mistakes
124 +| Mistake | Fix |
125 +|---|---|
126 +| Running unbounded `journalctl` | Add `-b`, `-n`, `--since`, `--no-pager` |
127 +| Treating web docs as exact | Check installed `man`/`--help` |
128 +| Using `sudo` from agent | Stop; give human command/script |
129 +| Editing `/etc` directly | Escalate with backup + rollback |
130 +| Guessing before inventory | Collect host facts + logs first |