Readable ad-hoc commands agent skill

A new open-source project, readable-ad-hoc-commands, formats AI coding agents' shell commands into readable scripts with named values, comments, phase banners, and plain-English summaries, aiming to reduce blind approvals of destructive commands. The project, hosted on GitHub under a-b/readable-ad-hoc-commands, works with any agent and command language, and includes rules in AGENTS.md and a Claude Code skill adapter.

Stop approving shell commands you can't read. When an AI coding agent fires a dense one-liner at your terminal, you either reverse-engineer it or rubber-stamp it blind. This makes the agent format those commands so you can see their intent, steps, and blast radius before they run — and preview anything destructive first. Works with any agent, in any command language shell, python -c , node -e , jq , SQL . Before — what an agent normally emits: find . -name " .log" -mtime +7 -exec gzip {} \; && find . -name " .gz" -mtime +30 -delete && du -sh . After — what this produces: bash /usr/bin/env bash set -euo pipefail Housekeeping for log files in the current tree. root="." compress after days=7 gzip logs older than this delete after days=30 remove archives older than this echo "== Compressing .log files older than ${compress after days}d" find "$root" -name " .log" -mtime "+${compress after days}" -exec gzip {} \; echo "== Deleting .gz archives older than ${delete after days}d" find "$root" -name " .gz" -mtime "+${delete after days}" -delete echo "== Disk usage after cleanup" du -sh "$root" …plus a one-line plain-English summary in chat before it runs. Seven rules do the work — name values, comment the why , banner each phase, fail loud, preview deletions, prose first — and the agent knows to skip all of it for a bare ls . Full rules and per-language mechanics: AGENTS.md /a-b/readable-ad-hoc-commands/blob/main/AGENTS.md . More transforms python -c , SQL : . /a-b/readable-ad-hoc-commands/blob/main/EXAMPLES.md EXAMPLES.md skills.sh recommended — works for every supported agent : npx skills add a-b/readable-ad-hoc-commands this project npx skills add a-b/readable-ad-hoc-commands -g global: all projects Claude Code, by hand bundled skill, auto-discovered on startup : git clone https://github.com/a-b/readable-ad-hoc-commands.git cp -r readable-ad-hoc-commands/readable-ad-hoc-commands ~/.claude/skills/ all projects Any other agent — the rules are plain Markdown in AGENTS.md /a-b/readable-ad-hoc-commands/blob/main/AGENTS.md ; drop them where your tool reads instructions: | Agent | Where | |---|---| | Codex, Amp, Zed, Jules | AGENTS.md at repo root .cursor/rules/readable-commands.mdc .windsurf/rules/ .github/copilot-instructions.md AGENTS.md to the system prompt AGENTS.md harness-neutral rules portable source of truth EXAMPLES.md worked transforms for python -c and SQL readable-ad-hoc-commands/ └── SKILL.md Claude Code skill adapter same rules + frontmatter