shell-hygiene

Enforces safe shell command patterns for agents using Monitor loops and zsh-safe iteration.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/diazMelgarejo/orama-system --skill shell-hygiene-diazmelgarejo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: shell-hygiene
Source: https://github.com/diazMelgarejo/orama-system/tree/main/bin/orama-system/skills/shell-hygiene
Command: npx skills add https://github.com/diazMelgarejo/orama-system --skill shell-hygiene-diazmelgarejo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Agents waste tool-call budget and corrupt shared state by using sleep chains to poll background tasks, mishandling zsh word-splitting, racing concurrent git commits, and downloading installers into predictable shared paths. ## Core Features & Use Cases - Sleep-chain prevention: Replaces sleep N && cmd polling with run_in_background notifications and Monitor until-loops for files, PIDs, ports, and services. - Background dispatch ceilings: Applies a 15-minute hard wall-clock deadline to hung external CLI or subagent dispatches like codex exec or kimi -p. - Concurrent git safety: Handles .git/index.lock contention and empty-commit races with bounded retry loops instead of deleting lock files. - Use Case: While waiting for an npm install running in the background, the agent waits for the completion notification instead of burning turns on sleep 30 && cat output, then iterates the results with while IFS= read -r to avoid zsh splitting bugs. ## Quick Start Ask the agent to wait for a background task or poll a file, and it will use a Monitor until-loop instead of a sleep chain.

Frequently Asked Questions about shell-hygiene

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I wait for a background task without sleep in shell scripts?

Use run_in_background: true and wait for the automatic completion notification instead of polling with sleep. If you must poll a condition, use an until-loop like `until grep -q "done" file; do sleep 3; done`, which is allowed because sleep is not the first token.

Why is `sleep 30 && cat output` blocked in agent shells?

A leading sleep followed by any command is detected and rejected before execution because sleep chains waste tool-call budget on polling. Splitting into shorter sleeps is also blocked; use background notifications or Monitor until-loops instead.

Why does `for x in $var` not split words in zsh?

zsh does not word-split unquoted parameter expansions by default, so the whole multiline variable becomes one iteration. Iterate with `printf '%s\n' "$var" | while IFS= read -r x` or pass lists as explicit arrays like "${files[@]}".

How do I handle .git/index.lock errors with concurrent agents?

Never delete .git/index.lock yourself, since a live git process may hold it and removal corrupts its commit. Retry the commit in a bounded loop (up to 15 attempts with short sleeps); the lock clears once the other process finishes.

What timeout should backgrounded CLI agent dispatches have?

Apply a 15-minute hard wall-clock ceiling to external dispatches like codex exec or kimi -p, since a hung process looks identical to a slow one. Monitor the PID in a loop and force-kill it when the deadline passes.

How should agents safely download and run installer scripts?

Create a private mode-700 directory with mktemp -d, download inside it, chain curl success before bash with `curl ... && bash`, and remove the directory on exit via a trap unless artifacts are explicitly kept for review.