菜单
Use when running bash/shell commands and interpreting their exit codes and output - pipelines, chaining a check after a mutating command, process checks with pgrep/pkill, backgrounding, waiting for an event, or when a command "failed" or its result looks ambiguous.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use at the end of a turn that produced a learning, such as a correction from the user, a rule or preference stated ("remember this", "from now on", "always/never"), a process or tooling mistake (wrong command, a quirk of the shell/SSH/environment, a misread of stale output, over-waiting, a tool or file you missed and re-derived), a wasted build or test cycle, or any reusable discovery (a procedure, a timing, a gotcha, a flag combination, a path). A gated Stop hook nudges this automatically; also run on "self-improve", "/self-improve", "improve the harness", or "capture what we learned".
Use when creating or scaffolding a NEW public bitranox Python library - a pip-installable package with a rich-click CLI, CI across Python 3.9-3.14 on Linux/macOS/Windows, and a PyPI release - or when installing or using a library built from the bitranox_template_py_lib template. Keywords - new library, scaffold, project template, rename-project, bmk, make test, make release, uv pip install.
Use when issuing or running PowerShell (pwsh) commands, or writing, modifying, or debugging a PowerShell / .ps1 script - prefer pwshpy instead: a genuinely Pythonic PowerShell (typed records + a lazy pipeline over native OS bindings, never a pwsh.exe subprocess, never text parsing), as a Python library (from pwshpy import ps) or the pwshpy CLI (install/run via uv - `uv tool install pwshpy` or `uvx pwshpy`). Better error handling and reporting (real exceptions and real exit codes, nothing silently swallowed) plus clean typed JSON instead of Get-* text. Covers using pwshpy and translating cmdlets / .ps1 to it.
Use when sending email from Python or the shell, especially with large attachments that must not be loaded into memory, RFC 3030 BDAT/CHUNKING, STARTTLS with authentication, multi-host failover, or correct UTF-8 subject and body encoding. Prefer the `btx_lib_mail` library or its `btx-lib-mail` CLI (zero-install via `uvx btx-lib-mail send ...`) over hand-rolling `smtplib`/`email`, MIME assembly, dot-stuffing, or attachment security checks. Covers install, uvx, the library API, the CLI, streaming and BDAT, and attachment security.
Use when creating new skills, editing existing skills, structuring SKILL.md files, writing skill frontmatter, testing skills with subagents, deploying skills, or verifying skills work before deployment
Use when creating, editing, or reformatting markdown tables in any document, when table columns look misaligned, or when reviewing markdown files that contain tables
| name | compuse-bash |
| description | Use when running bash/shell commands and interpreting their exit codes and output - pipelines, chaining a check after a mutating command, process checks with pgrep/pkill, backgrounding, waiting for an event, or when a command "failed" or its result looks ambiguous. |
Run shell commands so the result is unambiguous, and read that result truthfully.
| Situation | Rule |
|---|---|
| A command exits non-zero | NEVER dismiss it as "a quirk". Reproduce the smallest failing form to find the deterministic cause, or fix the command. |
| A command "succeeds" (exit 0) | Exit 0 is necessary but NOT sufficient. ALSO verify the real artifact/output (file written, content/size correct, options actually applied) - some tools exit 0 while writing nothing or silently ignoring options (e.g. the vips out.tif[opts] bracket form). Check the result, not only the status. |
| Critical command + a check in one call | Run the mutation in its OWN call (or join with &&). A trailing command's exit masks or misattributes the real one. |
Self-authored text inside a double-quoted arg (git -m, a --hook/--title) | NEVER include backticks or $(...): bash command-substitutes them, RUNNING the word as a command (this once ran a real shutdown) and corrupting the text. Use plain words, single quotes, or pass the text via a file (-F/--body-file). |
| Grep to find EVERY site to change | NEVER pipe the enumeration through head/tail -N: the cap is silent and becomes a false "all N sites updated" claim. Count first with grep -rc, then list uncapped and reconcile against that count. |
Capturing a grep -c count into a variable | grep EXITS 1 when it matches nothing, so the "safe" idiom n=$(grep -c PATTERN file || echo 0) fires the fallback on a zero count and sets n to the TWO-LINE string 0\n0, silently misformatting every comparison and report line built from it. Write n=$(grep -c PATTERN file 2>/dev/null); n=${n:-0} - grep -c already prints 0 itself, so no fallback is needed. |
cmd | tail/head/grep | The pipeline's exit is the LAST stage's, not cmd's. Use set -o pipefail or check ${PIPESTATUS[0]}. |
| Check/kill a process by name | pgrep/pkill -f PATTERN matches your OWN shell. Prefer a pidfile + kill -0, a port/unit/cgroup signal, or bracket the first char ([p]attern) AND keep the keyword out of echo labels in the same command. |
| Backgrounding a long job (run_in_background) | Make the long command ITSELF the background task. NEVER put cmd & INSIDE a run_in_background call: the wrapper reaches its next line and EXITS at once, firing a FALSE completion notification, while the &-detached child is reparented to init and runs ORPHANED + untracked - so its real end-signal never comes and you cannot stop it by task id. Run ONE command per run_in_background; for parallel jobs make SEPARATE calls, never one wrapper that backgrounds several with &. If a job does end up orphaned, poll ground truth (process alive + output-file growth) - no notification will fire. |
| Waiting for an event | Set an EXPECTED-duration ceiling BEFORE you wait (a quick estimate or one-shot instrumentation). This applies to every wait, INCLUDING waiting on a background job's completion signal (a task notification, a log line, a flag, a port) - a signal is not a licence to wait unboundedly. If the event overruns the ceiling by ~2x, STOP and INVESTIGATE (hung? mis-scoped? wrong command/marker? contended?) instead of continuing to wait for the signal. Otherwise wait the measured time plus a small margin (~1.3-1.5x, or a few seconds), or on the concrete signal, never an arbitrary long sleep (over-waiting compounds across cycles). Record measured timings so they are reused, not rediscovered. |
| Judging current state from output/logs | Read the freshest lines and check their timestamps; never conclude from a stale capture. |
| Keep / prune the NEWEST timestamped file(s) | Sort by MTIME, not by name: ls -t (newest first), or find DIR -maxdepth 1 -printf '%T@ %p\n' | sort -zrn. NEVER rely on plain ls/glob order (lexical) - a varying prefix breaks it (bak-dream-... sorts before bak-dreamtest-...), so the alphabetically-last STALE file is kept and a newer one deleted. |
A block like mutate ... ; echo done ; verify returns ONLY the last command's status. So a failed critical command is hidden by a succeeding trailing command (false success), or a trivial trailing failure makes a successful critical command look failed (false failure) which then gets waved off as "a quirk". Both are real defects. Run the critical command alone (clean, unambiguous status), then verify separately. When you must chain, use && (status reflects the first failure), and for pipelines read ${PIPESTATUS[@]}.
A non-zero exit always has a deterministic cause. Reproduce the smallest failing form and isolate it (for example git rev-parse --short A B fails because --short abbreviates one revision, a knowable rule, not a quirk). Dismissing the error guarantees the same confusion next time and can hide a real failure.
block-pgrep-self-match (PreToolUse on Bash) blocks the pgrep/pkill -f echo-label self-match. It does not replace preferring pidfile/port/unit signals over a name grep.
