a-b/readable-ad-hoc-commands

Claude Code skill: format ad-hoc, multi-step shell so you can read it before it runs - a-b/readable-ad-hoc-commands

1 stars · 0 forks · 0 watchers

README

readable-ad-hoc-commands

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). The payoff 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: #!/usr/bin/env bash set -euo pipefail

Housekeeping for log files in the current tree.

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. More transforms (python -c, SQL): EXAMPLES.md. Install 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; drop them where your tool reads instructions:

Agent Where

Codex, Amp, Zed, Jules (AGENTS.md convention) AGENTS.md at repo root

Cursor .cursor/rules/readable-commands.mdc

Windsurf .windsurf/rules/

GitHub Copilot .github/copilot-instructions.md

Generic / API Prepend AGENTS.md to the system prompt

Layout 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)

License MIT

source