# Readable ad-hoc commands agent skill

> Source: <https://github.com/a-b/readable-ad-hoc-commands>
> Published: 2026-08-01 00:25:22+00:00

**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)
```