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

/" data-turbo-transient="true" />

Skip to content

Search or jump to...

Search code, repositories, users, issues, pull requests...

-->

Search

Clear

Search syntax tips

Provide feedback

--><br>We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

-->

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

a-b

readable-ad-hoc-commands

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>8 Commits<br>8 Commits

readable-ad-hoc-commands

readable-ad-hoc-commands

AGENTS.md

AGENTS.md

EXAMPLES.md

EXAMPLES.md

LICENSE

LICENSE

README.md

README.md

View all files

Repository files navigation

readable-ad-hoc-commands

Stop approving shell commands you can't read. When an AI coding agent fires<br>a dense one-liner at your terminal, you either reverse-engineer it or rubber-stamp<br>it blind. This makes the agent format those commands so you can see their intent,<br>steps, and blast radius before they run — and preview anything destructive<br>first.

Works with any agent, in any command language (shell, python -c, node -e,<br>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:

Compressing .log files older than ${compress_after_days}d"<br>find "$root" -name "*.log" -mtime "+${compress_after_days}" -exec gzip {} \;

echo "==> Deleting .gz archives older than ${delete_after_days}d"<br>find "$root" -name "*.gz" -mtime "+${delete_after_days}" -delete

echo "==> Disk usage after cleanup"<br>du -sh "$root"">#!/usr/bin/env bash<br>set -euo pipefail

# Housekeeping for log files in the current tree.<br>root="."<br>compress_after_days=7 # gzip logs older than this<br>delete_after_days=30 # remove archives older than this

echo "==> Compressing .log files older than ${compress_after_days}d"<br>find "$root" -name "*.log" -mtime "+${compress_after_days}" -exec gzip {} \;

echo "==> Deleting .gz archives older than ${delete_after_days}d"<br>find "$root" -name "*.gz" -mtime "+${delete_after_days}" -delete

echo "==> Disk usage after cleanup"<br>du -sh "$root"

…plus a one-line plain-English summary in chat before it runs. Seven rules do<br>the work — name values, comment the why, banner each phase, fail loud, preview<br>deletions, prose first — and the agent knows to skip all of it for a bare ls.<br>Full rules and per-language mechanics: AGENTS.md. More transforms<br>(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<br>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<br>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;<br>drop them where your tool reads instructions:

Agent<br>Where

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

Cursor<br>.cursor/rules/readable-commands.mdc

Windsurf<br>.windsurf/rules/

GitHub Copilot<br>.github/copilot-instructions.md

Generic / API<br>Prepend AGENTS.md to the system prompt

Layout

AGENTS.md # harness-neutral rules (portable source of truth)<br>EXAMPLES.md # worked transforms for python -c and SQL<br>readable-ad-hoc-commands/<br>└── SKILL.md # Claude Code skill adapter (same rules + frontmatter)

License

MIT

About<br>Claude Code skill: format ad-hoc, multi-step shell so you can read it before it runs<br>Resources<br>Readme<br>MIT license<br>Activity<br>Stars<br>1 star<br>Watchers<br>0 watching<br>Forks<br>0 forks<br>Report repository

Releases

Packages

Contributors

You can’t perform that action at this time.