Skip to content

dirien/yet-another-agent-harness / .claude/skills/agent-rules

agent-rules

Flagged

Use 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.

FileKindSize
AGENTS.mdmarkdown3.9 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md4.5 KB
assets/example-workflows/validate-agents.ymlconfig2.7 KB
assets/root-thin.mdmarkdown5.7 KB
assets/root-verbose.mdmarkdown5.5 KB
assets/scoped/backend-go.mdmarkdown3.6 KB
assets/scoped/backend-php.mdmarkdown3.0 KB
assets/scoped/backend-python.mdmarkdown2.6 KB
assets/scoped/backend-typescript.mdmarkdown2.8 KB
assets/scoped/claude-code-skill.mdmarkdown3.4 KB
assets/scoped/cli.mdmarkdown2.7 KB
assets/scoped/concourse.mdmarkdown5.2 KB
assets/scoped/ddev.mdmarkdown2.4 KB
assets/scoped/docker.mdmarkdown5.3 KB
assets/scoped/documentation.mdmarkdown3.5 KB
assets/scoped/examples.mdmarkdown3.4 KB
assets/scoped/frontend-typescript.mdmarkdown2.7 KB
assets/scoped/github-actions.mdmarkdown5.2 KB
assets/scoped/gitlab-ci.mdmarkdown4.6 KB
assets/scoped/oro-bundle.mdmarkdown6.5 KB
assets/scoped/oro-project.mdmarkdown5.5 KB
assets/scoped/python-modern.mdmarkdown6.1 KB
assets/scoped/resources.mdmarkdown3.5 KB
assets/scoped/skill-repo.mdmarkdown5.4 KB
assets/scoped/symfony.mdmarkdown5.3 KB
assets/scoped/testing.mdmarkdown3.0 KB
assets/scoped/typo3-docs.mdmarkdown3.6 KB
assets/scoped/typo3-extension.mdmarkdown5.1 KB
assets/scoped/typo3-project.mdmarkdown4.7 KB
assets/scoped/typo3-testing.mdmarkdown3.0 KB
checkpoints.yamlconfig9.0 KB
evals/evals.jsonconfig20.7 KB
references/ai-contribution-guidelines.mdmarkdown2.5 KB
references/ai-tool-compatibility.mdmarkdown7.9 KB
references/analysis.mdmarkdown10.8 KB
references/directory-coverage.mdmarkdown2.4 KB
references/examples/coding-agent-cli/AGENTS.mdmarkdown2.5 KB
references/examples/coding-agent-cli/go.modmanifest45 B
references/examples/coding-agent-cli/scripts-AGENTS.mdmarkdown10.1 KB
references/examples/express-api-ts/.env.exampleother232 B
references/examples/express-api-ts/AGENTS.mdmarkdown3.1 KB
references/examples/express-api-ts/package.jsonmanifest757 B
references/examples/express-api-ts/pnpm-lock.yamlmanifest101 B
references/examples/express-api-ts/src/AGENTS.mdmarkdown3.1 KB
references/examples/express-api-ts/src/config.tsscript917 B
references/examples/express-api-ts/src/controllers/userController.tsscript2.1 KB
references/examples/express-api-ts/src/index.tsscript671 B
references/examples/express-api-ts/src/middleware/errorHandler.tsscript1.0 KB
references/examples/express-api-ts/src/middleware/requestLogger.tsscript471 B
references/examples/express-api-ts/src/routes/health.tsscript428 B
references/examples/express-api-ts/src/routes/users.tsscript397 B
references/examples/express-api-ts/src/utils/errors.tsscript1.2 KB
references/examples/express-api-ts/src/utils/logger.tsscript441 B
references/examples/express-api-ts/tsconfig.jsonconfig630 B
references/examples/fastapi-app/.env.exampleother348 B
references/examples/fastapi-app/AGENTS.mdmarkdown3.2 KB
references/examples/fastapi-app/pyproject.tomlmanifest1.8 KB
references/examples/fastapi-app/src/AGENTS.mdmarkdown2.9 KB
references/examples/fastapi-app/src/__init__.pyscript58 B
references/examples/fastapi-app/src/config.pyscript1.1 KB
references/examples/fastapi-app/src/main.pyscript1.7 KB
references/examples/fastapi-app/src/models/__init__.pyscript278 B
references/examples/fastapi-app/src/models/item.pyscript1.0 KB
references/examples/fastapi-app/src/models/user.pyscript922 B
references/examples/fastapi-app/src/routes/__init__.pyscript110 B
references/examples/fastapi-app/src/routes/health.pyscript470 B
references/examples/fastapi-app/src/routes/items.pyscript1.9 KB
references/examples/fastapi-app/src/routes/users.pyscript1.7 KB
references/examples/fastapi-app/src/services/__init__.pyscript174 B
references/examples/fastapi-app/src/services/item_service.pyscript2.5 KB
references/examples/fastapi-app/src/services/user_service.pyscript2.1 KB
references/examples/fastapi-app/uv.lockmanifest136 B
references/examples/go-api-with-react-admin/.scopesother93 B
references/examples/go-api-with-react-admin/AGENTS.mdmarkdown3.0 KB
references/examples/go-api-with-react-admin/admin/package.jsonmanifest422 B
references/examples/go-api-with-react-admin/admin/src/App.tsxother101 B
references/examples/go-api-with-react-admin/cmd/api/main.goscript75 B
references/examples/go-api-with-react-admin/go.modmanifest31 B
references/examples/go-api-with-react-admin/main.goscript71 B
references/examples/go-with-internal-web-tsx/.scopesother102 B
references/examples/go-with-internal-web-tsx/AGENTS.mdmarkdown3.1 KB
references/examples/go-with-internal-web-tsx/go.modmanifest34 B
references/examples/go-with-internal-web-tsx/internal/web/AGENTS.mdmarkdown3.1 KB
references/examples/go-with-internal-web-tsx/internal/web/package.jsonmanifest328 B
references/examples/go-with-internal-web-tsx/internal/web/src/App.tsxother57 B
references/examples/go-with-internal-web-tsx/internal/web/src/Button.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Footer.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Header.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Sidebar.tsxother65 B
references/examples/go-with-internal-web-tsx/main.goscript85 B
references/examples/go-with-internal-web-tsx/package-lock.jsonmanifest0 B
references/examples/go-with-internal-web-tsx/package.jsonmanifest220 B
references/examples/ldap-selfservice/AGENTS.mdmarkdown2.5 KB
references/examples/ldap-selfservice/go.modmanifest45 B
references/examples/ldap-selfservice/internal-AGENTS.mdmarkdown10.0 KB
references/examples/ldap-selfservice/internal-web-AGENTS.mdmarkdown12.1 KB
references/examples/php-with-frontend/.scopesother89 B
references/examples/php-with-frontend/AGENTS.mdmarkdown3.1 KB
references/examples/php-with-frontend/composer.jsonconfig185 B
references/examples/php-with-frontend/package.jsonmanifest306 B
references/examples/php-with-frontend/pnpm-lock.yamlmanifest0 B
references/examples/php-with-frontend/src/Controller.phpscript41 B
references/examples/php-with-frontend/web/AGENTS.mdmarkdown3.1 KB
references/examples/php-with-frontend/web/package.jsonmanifest514 B
references/examples/php-with-frontend/web/src/App.tsxother63 B
references/examples/php-with-frontend/web/src/Button.tsxother215 B
references/examples/php-with-frontend/web/src/Footer.tsxother125 B
references/examples/php-with-frontend/web/src/Header.tsxother122 B
references/examples/php-with-frontend/web/src/main.tsxother68 B
references/examples/php-with-frontend/web/tsconfig.jsonconfig280 B
references/examples/pnpm-workspace/AGENTS.mdmarkdown2.6 KB
references/examples/pnpm-workspace/package.jsonmanifest105 B
references/examples/pnpm-workspace/packages/web/package.jsonmanifest187 B
references/examples/pnpm-workspace/packages/web/src/index.tsscript258 B
references/examples/pnpm-workspace/pnpm-lock.yamlmanifest920 B
references/examples/pnpm-workspace/pnpm-workspace.yamlconfig27 B
references/examples/simple-ldap-go/AGENTS.mdmarkdown2.5 KB
references/examples/simple-ldap-go/examples-AGENTS.mdmarkdown1.8 KB
references/examples/simple-ldap-go/go.modmanifest43 B
references/examples/t3x-rte-ckeditor-image/AGENTS.mdmarkdown2.5 KB
references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.mdmarkdown12.0 KB
references/examples/t3x-rte-ckeditor-image/composer.jsonconfig174 B
references/feedback-memory-schema.mdmarkdown7.2 KB
references/git-hooks-setup.mdmarkdown2.4 KB
references/output-structure.mdmarkdown4.9 KB
references/scripts-guide.mdmarkdown4.9 KB
references/verification-guide.mdmarkdown5.5 KB
scripts/analyze-git-history.shexecutablescript9.8 KB
scripts/check-freshness.shexecutablescript6.3 KB
scripts/detect-golden-samples.shexecutablescript5.3 KB
scripts/detect-heuristics.shexecutablescript3.2 KB
scripts/detect-project.shexecutablescript19.3 KB
scripts/detect-scopes.shexecutablescript12.1 KB
scripts/detect-utilities.shexecutablescript4.3 KB
scripts/extract-adrs.shexecutablescript6.6 KB
scripts/extract-agent-configs.shexecutablescript9.2 KB
scripts/extract-architecture-rules.shexecutablescript19.9 KB
scripts/extract-ci-commands.shexecutablescript12.5 KB
scripts/extract-ci-rules.shexecutablescript15.4 KB
scripts/extract-commands.shexecutablescript11.0 KB
scripts/extract-documentation.shexecutablescript7.7 KB
scripts/extract-github-rulesets.shexecutablescript3.5 KB
scripts/extract-github-settings.shexecutablescript3.3 KB
scripts/extract-ide-settings.shexecutablescript7.0 KB
scripts/extract-platform-files.shexecutablescript7.9 KB
scripts/extract-quality-configs.shexecutablescript14.8 KB
scripts/generate-agents.shexecutablescript113.6 KB
scripts/generate-file-map.shexecutablescript4.4 KB
scripts/lib/config-root.shexecutablescript5.8 KB
scripts/lib/summary.shscript10.7 KB
scripts/lib/template.shexecutablescript13.1 KB
scripts/validate-structure.shexecutablescript8.6 KB
scripts/verify-commands.shexecutablescript22.0 KB
scripts/verify-content.shexecutablescript9.5 KB

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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall