dirien/yet-another-agent-harness / .claude/skills/agent-rules
agent-rules
FlaggedUse when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
scripts/verify-commands.sh
View on GitHub#!/usr/bin/env bash
# Verify that commands documented in AGENTS.md actually work
# This prevents "command rot" - documented commands that no longer exist
# Requires: Bash 4.0+ (for associative arrays)
set -euo pipefail
# Check Bash version - we need 4.0+ for associative arrays (declare -A)
if ((BASH_VERSINFO[0] < 4)); then
echo "Error: Bash 4.0+ required (found ${BASH_VERSION})." >&2
echo "On macOS: brew install bash" >&2
exit 1
fi
PROJECT_DIR="${1:-.}"
AGENTS_FILE="$PROJECT_DIR/AGENTS.md"
VERBOSE="${VERBOSE:-false}"
DRY_RUN="${DRY_RUN:-false}"
SMOKE_TEST="${SMOKE_TEST:-false}"
TIMEOUT="${TIMEOUT:-60}"
OUTPUT_JSON="${OUTPUT_JSON:-$PROJECT_DIR/.agents/command-verification.json}"
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
log() {
if [ "$VERBOSE" = true ]; then
echo -e "[INFO] $*" >&2
fi
}
error() {
echo -e "${RED}[ERROR]${NC} $*" >&2
}
success() {
echo -e "${GREEN}[OK]${NC} $*"
}
warn() {
echo -e "${YELLOW}[WARN]${NC} $*"
}
# Check if AGENTS.md exists
if [ ! -f "$AGENTS_FILE" ]; then
error "AGENTS.md not found at $AGENTS_FILE"
exit 1
fi
cd "$PROJECT_DIR"
echo "Verifying commands in $AGENTS_FILE..."
echo ""
FAILED=0
PASSED=0
SKIPPED=0
# JSON results storage
declare -A COMMAND_RESULTS
# Initialize JSON output directory (always needed for results)
mkdir -p "$(dirname "$OUTPUT_JSON")"
# Check if a command is safe to execute using a whitelist approach.
# Only commands whose base binary is in the ALLOWED_COMMANDS list are permitted.
# Returns 0 if safe, 1 if not whitelisted.
is_safe_command() {
local cmd="$1"
# Whitelist of known safe base commands.
# These are common build/dev tools that are safe to invoke for verification.
local -a ALLOWED_COMMANDS=(
# Version control
git
# File inspection
ls cat head tail less wc file stat find grep egrep fgrep rg ag sed awk sort uniq diff
# Build tools / package managers
make go npm yarn pnpm bun composer cargo deno gradle gradlew python python3 pip pip3
poetry uv pytest php phpunit node ruby bundle gem mvn ant
# Project-specific binaries (resolved via PATH or relative path)
vendor/bin
# Container tools (read-only / informational subcommands only)
docker podman
# Linters and formatters
eslint prettier phpcs phpcbf phpstan psalm rector black flake8 mypy ruff shellcheck
# Documentation / misc
jq yq curl wget
# Testing
jest vitest mocha
)
# Extract the base command (first word), stripping any leading ./
local base_cmd
base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|^\./||')
# Allow vendor/bin/* paths
if [[ "$base_cmd" == vendor/bin/* ]]; then
return 0
fi
# Check against whitelist
for allowed in "${ALLOWED_COMMANDS[@]}"; do
if [[ "$base_cmd" == "$allowed" ]]; then
return 0
fi
done
# Not in whitelist - reject
return 1
}
# Portable milliseconds timestamp (works on both GNU and BSD date)
get_time_ms() {
# Try GNU date with nanoseconds first, fall back to seconds * 1000
if date +%s%3N 2>/dev/null | grep -qE '^[0-9]+$'; then
date +%s%3N
else
echo $(( $(date +%s) * 1000 ))
fi
}
# Run a command with timeout and measure duration
smoke_test_command() {
local cmd="$1"
local start_time end_time duration_ms exit_code
# Safety check - skip dangerous commands
if ! is_safe_command "$cmd"; then
warn "Skipping potentially dangerous command: $cmd"
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "skipped": true, "reason": "safety"}'
return 1
fi
start_time=$(get_time_ms)
# Run with timeout, capture exit code
if timeout "${TIMEOUT}s" bash -c "$cmd" > /dev/null 2>&1; then
exit_code=0
else
exit_code=$?
fi
end_time=$(get_time_ms)
duration_ms=$((end_time - start_time))
# Store result
if [ $exit_code -eq 0 ]; then
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": true, "duration_ms": '"$duration_ms"'}'
return 0
elif [ $exit_code -eq 124 ]; then
# Timeout
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "timeout": true, "duration_ms": '"$((TIMEOUT * 1000))"'}'
return 1
else
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "exit_code": '"$exit_code"', "duration_ms": '"$duration_ms"'}'
return 1
fi
}
# Write results to JSON file
write_json_results() {
local timestamp
# Portable ISO 8601 timestamp (works on both GNU and BSD date)
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
{
echo "{"
echo ' "verified_at": "'"$timestamp"'",'
echo ' "smoke_tested": '"$SMOKE_TEST"','
echo ' "commands": {'
local first=true
for cmd in "${!COMMAND_RESULTS[@]}"; do
if [ "$first" = true ]; then
first=false
else
echo ","
fi
# Escape the command string for JSON
local escaped_cmd
escaped_cmd=$(echo "$cmd" | sed 's/\\/\\\\/g; s/"/\\"/g')
printf ' "%s": %s' "$escaped_cmd" "${COMMAND_RESULTS[$cmd]}"
done
echo ""
echo " }"
echo "}"
} > "$OUTPUT_JSON"
log "Results written to $OUTPUT_JSON"
}
# Extract commands from markdown code blocks and table cells
# Look for patterns like: `command arg` or | command | or | `command` |
extract_commands() {
# Extract from tables with backticks (| `command` | format)
grep -oE '\| `[^`]+`' "$AGENTS_FILE" 2>/dev/null | sed 's/| `//;s/`$//' | grep -v '^\s*$' || true
# Extract from tables without backticks in Commands section
# Look for lines like "| Lint | vendor/bin/php-cs-fixer fix --dry-run |"
# Skip header row and separator row, get 3rd column (command), filter empty and time estimates
sed -n '/^## Commands/,/^##/p' "$AGENTS_FILE" 2>/dev/null | \
grep -E '^\|' | \
tail -n +3 | \
cut -d'|' -f3 | \
sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | \
grep -v '^$' | \
grep -v '^~' || true
# Extract from inline code that looks like commands
# Includes: npm, yarn, pnpm, bun, make, go, composer, cargo, python, pip, poetry, uv, deno, gradle, php, vendor/bin
grep -oE '`(npm |yarn |pnpm |bun |make |go |composer |cargo |pytest |python |pip |poetry |uv |deno |gradle |php |vendor/bin/)[^`]+`' "$AGENTS_FILE" 2>/dev/null | sed 's/`//g' || true
}
# Verify a single command exists (not that it succeeds, just that it's callable)
verify_command() {
local cmd="$1"
local base_cmd
# Extract the base command (first word)
base_cmd=$(echo "$cmd" | awk '{print $1}')
# Skip placeholders
if [[ "$cmd" == *"<"* ]] || [[ "$cmd" == *"{{{"* ]]; then
log "Skipping placeholder: $cmd"
((SKIPPED+=1))
return 0
fi
# Skip if it's just a flag or option
if [[ "$base_cmd" == -* ]]; then
return 0
fi
log "Checking: $cmd"
# Check different command types
case "$base_cmd" in
npm|yarn|pnpm|bun)
# Check if package.json script exists
local script="${cmd#* }"
script="${script#run }"
script="${script%% *}"
if [ -f "package.json" ]; then
local script_exists=false
if jq -e ".scripts[\"$script\"]" package.json > /dev/null 2>&1; then
script_exists=true
elif [[ "$script" =~ ^(install|test|build|start|run)$ ]]; then
script_exists=true
fi
if [ "$script_exists" = true ]; then
if [ "$SMOKE_TEST" = true ]; then
# For test commands, only verify they start (dry-run if available)
local test_cmd="$cmd"
if [[ "$script" == "test" ]]; then
# Try to use --help or --dry-run to avoid full test run
test_cmd="$base_cmd run $script -- --help 2>/dev/null || $base_cmd run $script --dry-run 2>/dev/null || true"
fi
if smoke_test_command "$test_cmd"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "$base_cmd script works: $script (~${duration}ms)"
((PASSED+=1))
else
warn "$base_cmd script exists but smoke test failed: $script"
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
((SKIPPED+=1))
fi
else
success "$base_cmd script exists: $script"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
warn "$base_cmd script not found: $script (in $cmd)"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
else
warn "No package.json found for: $cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
make)
# Check if Makefile target exists
local target="${cmd#make }"
target="${target%% *}"
if [ -f "Makefile" ] || [ -f "makefile" ] || [ -f "GNUmakefile" ]; then
if make -n "$target" > /dev/null 2>&1; then
if [ "$SMOKE_TEST" = true ]; then
# Use make -n (dry run) for smoke test to avoid side effects
if smoke_test_command "make -n $target"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "make target works: $target (~${duration}ms)"
((PASSED+=1))
else
warn "make target exists but dry-run failed: $target"
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
((SKIPPED+=1))
fi
else
success "make target exists: $target"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
error "make target not found: $target"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((FAILED+=1))
fi
else
warn "No Makefile found for: $cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
composer)
# Check if composer script exists
local script="${cmd#composer }"
script="${script%% *}"
if [ -f "composer.json" ]; then
local script_exists=false
if [[ "$script" =~ ^(install|update|require|remove|dump-autoload)$ ]]; then
script_exists=true
elif jq -e ".scripts[\"$script\"]" composer.json > /dev/null 2>&1; then
script_exists=true
fi
if [ "$script_exists" = true ]; then
if [ "$SMOKE_TEST" = true ]; then
# For composer scripts, try --dry-run or --help
local test_cmd="$cmd"
if [[ "$script" =~ ^(install|update)$ ]]; then
test_cmd="composer $script --dry-run 2>/dev/null || true"
fi
if smoke_test_command "$test_cmd"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "composer script works: $script (~${duration}ms)"
((PASSED+=1))
else
warn "composer script exists but smoke test failed: $script"
COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
((SKIPPED+=1))
fi
else
success "composer script exists: $script"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
warn "composer script not found: $script"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
else
warn "No composer.json found for: $cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
python|python3|pip|pip3)
# Python commands
if command -v "$base_cmd" > /dev/null 2>&1; then
success "Python command available: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "Python command not found: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
poetry)
# Poetry package manager
if command -v poetry > /dev/null 2>&1; then
local subcmd="${cmd#poetry }"
subcmd="${subcmd%% *}"
if [[ "$subcmd" =~ ^(install|add|remove|update|build|publish|run|shell)$ ]]; then
success "poetry command: $subcmd"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
# Check if it's a custom script
if [ -f "pyproject.toml" ] && grep -q "\[tool.poetry.scripts\]" pyproject.toml 2>/dev/null; then
success "poetry command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "poetry script not found: $subcmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
fi
else
warn "poetry not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
uv)
# uv package manager
if command -v uv > /dev/null 2>&1; then
success "uv command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "uv not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
pytest)
# pytest test runner
if command -v pytest > /dev/null 2>&1; then
success "pytest available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "pytest not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
cargo)
# Rust cargo
if command -v cargo > /dev/null 2>&1; then
success "cargo command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "cargo not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
deno)
# Deno runtime
if command -v deno > /dev/null 2>&1; then
success "deno command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "deno not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
gradle|gradlew|./gradlew)
# Gradle build tool
if [ -f "gradlew" ] || [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
success "gradle project detected"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
elif command -v gradle > /dev/null 2>&1; then
success "gradle command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
else
warn "gradle not found"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
go)
# Go commands are generally available if go is installed
if command -v go > /dev/null 2>&1; then
if [ "$SMOKE_TEST" = true ]; then
if smoke_test_command "$cmd"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "go command ran successfully (~${duration}ms)"
((PASSED+=1))
else
error "go command failed: $cmd"
((FAILED+=1))
fi
else
success "go command available"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
error "go not installed"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((FAILED+=1))
fi
;;
vendor/bin/*)
# PHP vendor binary
if [ -f "$base_cmd" ]; then
if [ "$SMOKE_TEST" = true ]; then
# For test commands, run with --help to avoid actually running tests
local test_cmd="$cmd"
if [[ "$cmd" == *"phpunit"* ]] && [[ "$cmd" != *"--help"* ]]; then
test_cmd="$base_cmd --help"
fi
if smoke_test_command "$test_cmd"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "vendor binary works (~${duration}ms)"
((PASSED+=1))
else
warn "vendor binary exists but failed: $cmd"
((SKIPPED+=1))
fi
else
success "vendor binary exists: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
error "vendor binary not found: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((FAILED+=1))
fi
;;
*)
# Check if command exists in PATH
if command -v "$base_cmd" > /dev/null 2>&1; then
if [ "$SMOKE_TEST" = true ]; then
if smoke_test_command "$cmd"; then
local duration="${COMMAND_RESULTS[$cmd]}"
duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
success "command works (~${duration}ms)"
((PASSED+=1))
else
warn "command exists but failed: $cmd"
((SKIPPED+=1))
fi
else
success "command exists: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": true}'
((PASSED+=1))
fi
else
warn "command not in PATH: $base_cmd"
COMMAND_RESULTS["$cmd"]='{"exists": false}'
((SKIPPED+=1))
fi
;;
esac
}
# Get unique commands
mapfile -t commands < <(extract_commands | sort -u)
if [ ${#commands[@]} -eq 0 ]; then
warn "No commands found in AGENTS.md"
exit 0
fi
echo "Found ${#commands[@]} unique commands to verify"
echo ""
for cmd in "${commands[@]}"; do
[ -n "$cmd" ] && verify_command "$cmd"
done
echo ""
echo "======================================"
echo "Verification Summary"
echo "======================================"
echo -e "${GREEN}Passed:${NC} $PASSED"
echo -e "${YELLOW}Skipped:${NC} $SKIPPED"
echo -e "${RED}Failed:${NC} $FAILED"
echo ""
if [ "$FAILED" -gt 0 ]; then
echo -e "${RED}Some commands in AGENTS.md are invalid!${NC}"
echo "Update AGENTS.md to fix broken command references."
# Still write JSON results
if [ "$DRY_RUN" = false ] && [ ${#COMMAND_RESULTS[@]} -gt 0 ]; then
write_json_results
fi
exit 1
else
echo -e "${GREEN}All verifiable commands are valid.${NC}"
# Write JSON results
if [ "$DRY_RUN" = false ] && [ ${#COMMAND_RESULTS[@]} -gt 0 ]; then
write_json_results
echo "Verification results saved to $OUTPUT_JSON"
fi
# Update verified timestamp if not dry-run
if [ "$DRY_RUN" = false ] && [ -w "$AGENTS_FILE" ]; then
TODAY=$(date +%Y-%m-%d)
if grep -q "Last verified:" "$AGENTS_FILE"; then
# Portable sed -i: use backup extension then remove backup
sed -i.bak "s/Last verified: .*/Last verified: $TODAY -->/" "$AGENTS_FILE" && rm -f "$AGENTS_FILE.bak"
echo "Updated 'Last verified' timestamp to $TODAY"
fi
fi
fi
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |