agent-rules
Generate and maintain AGENTS.md, copilot-instructions.md, and other agent rule files
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 13 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/netresearch/agent-rules-skill with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/netresearch/agent-rules-skill'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/netresearch--agent-rules-skill)HTML
<a href="/listings/netresearch--agent-rules-skill"><img src="/api/listings/netresearch--agent-rules-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Marketplace (Recommended)
Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:
# Claude Code /plugin marketplace add netresearch/claude-code-marketplace /plugin install agent-rules@netresearch-claude-code-marketplace
Without a marketplace
Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:
mkdir -p ~/.claude/skills git clone https://github.com/netresearch/agent-rules-skill.git \ ~/.claude/skills/agent-rules
It loads as `agent-rules@skills-dir` on the next session. Update with `git -C ~/.claude/skills/agent-rules pull` and start a new session; remove it by deleting the directory. This route has no `claude plugin update`.
npx ([skills.sh](https://skills.sh))
Install with any [Agent Skills](https://agentskills.io)-compatible agent:
npx skills add https://github.com/netresearch/agent-rules-skill --skill agent-rules
Download Release
Download the [latest release](https://github.com/netresearch/agent-rules-skill/releases/latest) and extract to your agent's skills directory.
Git Clone
git clone https://github.com/netresearch/agent-rules-skill.git
Composer (PHP Projects)
composer require netresearch/agent-rules-skill
Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
npm (Node Projects)
npm install --save-dev \ @netresearch/agent-skill-coordinator \ github:netresearch/agent-rules-skill
Requires [@netresearch/agent-skill-coordinator](https://github.com/netresearch/node-agent-skill-coordinator), which discovers the skill in `node_modules` and registers it in `AGENTS.md` via a `postinstall` hook. For pnpm, also allowlist the coordinator's postinstall:
{
"pnpm": {
"onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 14 lines
- {
- "name": "agent-rules",
- "version": "3.17.0",
- "description": "Generate and maintain AGENTS.md, copilot-instructions.md, and other agent rule files",
- "author": {
- "name": "Netresearch DTT GmbH",
- "url": "https://www.netresearch.de"
- },
- "repository": "https://github.com/netresearch/agent-rules-skill",
- "license": "(MIT AND CC-BY-SA-4.0)",
- "skills": [
- "./skills/agent-rules"
- ]
- }
README.md · README · 190 lines
- <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
- <!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
- # AGENTS.md Generator Skill
- Netresearch AI skill for generating and maintaining AGENTS.md files following the [agents.md specification](https://agents.md/).
- > **What is AGENTS.md?** A context file written **for AI coding agents**, not humans. Human readability is a side effect, not a goal. Adopted by 60,000+ open-source projects. See the [official specification](https://agents.md/) and [best practices from 2,500+ repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/).
- ## Standards Compliance
- This skill implements two complementary standards:
- 1. **[agents.md](https://agents.md/)** - The file format this skill generates. A simple Markdown convention for guiding AI coding agents, supported by Claude Code, GitHub Copilot, Cursor, and 60,000+ open-source projects.
- 2. **[Agent Skills](https://agentskills.io)** - How this skill is packaged and distributed. A portable format for procedural knowledge that works across AI agents.
- **Supported Platforms:**
- - ✅ Claude Code (Anthropic)
- - ✅ Cursor
- - ✅ GitHub Copilot
- - ✅ Other skills-compatible AI agents
- ## Features
- - **Thin Root Files** - ~30 lines with precedence rules and global defaults
- - **Scoped Files** - Automatic subsystem detection (backend/, frontend/, internal/, cmd/)
- - **Auto-Extraction** - Commands from Makefile, package.json, composer.json, go.mod
- - **Multi-Language** - Templates for Go, PHP, TypeScript, Python, and hybrid projects
- - **Idempotent Updates** - Preserve existing structure while refreshing content
- - **Managed Headers** - Mark files as agent-maintained with timestamps
- ## Installation
- ### Marketplace (Recommended)
- Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:
- ```bash
- # Claude Code
- /plugin marketplace add netresearch/claude-code-marketplace
- /plugin install agent-rules@netresearch-claude-code-marketplace
- ```
- ### Without a marketplace
- Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:
- ```bash
- mkdir -p ~/.claude/skills
- git clone https://github.com/netresearch/agent-rules-skill.git \
- ~/.claude/skills/agent-rules
- ```
- It loads as `agent-rules@skills-dir` on the next session. Update with `git -C ~/.claude/skills/agent-rules pull` and start a new session; remove it by deleting the directory. This route has no `claude plugin update`.
- ### npx ([skills.sh](https://skills.sh))
- Install with any [Agent Skills](https://agentskills.io)-compatible agent:
- ```bash
- npx skills add https://github.com/netresearch/agent-rules-skill --skill agent-rules
- ```
- ### Download Release
- Download the [latest release](https://github.com/netresearch/agent-rules-skill/releases/latest) and extract to your agent's skills directory.
- ### Git Clone
- ```bash
- git clone https://github.com/netresearch/agent-rules-skill.git
- ```
- ### Composer (PHP Projects)
- ```bash
- composer require netresearch/agent-rules-skill
- ```
- Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
- ### npm (Node Projects)
- ```bash
- npm install --save-dev \
- @netresearch/agent-skill-coordinator \
- github:netresearch/agent-rules-skill
- ```
- Requires [@netresearch/agent-skill-coordinator](https://github.com/netresearch/node-agent-skill-coordinator), which discovers the skill in `node_modules` and registers it in `AGENTS.md` via a `postinstall` hook. For pnpm, also allowlist the coordinator's postinstall:
- ```json
- {
- "pnpm": {
- "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
- }
- }
- ```
- ## Usage
- The skill triggers on keywords like:
- - "AGENTS.md", "agents file"
- - "agent documentation", "AI onboarding"
- - "project context for AI"
- ### Example Prompts
- ```
- "Generate AGENTS.md for this project"
- "Update the agents documentation"
- "Create scoped AGENTS.md files for each subsystem"
- "Validate AGENTS.md structure"
- ```
- ## Supported Projects
- | Type | Detection | Features |
- |------|-----------|----------|
- | Go | `go.mod` | Version extraction, CLI tool detection |
- | PHP | `composer.json` | TYPO3/Laravel/Symfony detection |
- | TypeScript | `package.json` | React/Next.js/Vue/Express detection |
- | Python | `pyproject.toml` | Poetry/Ruff/Django/Flask detection |
- | Hybrid | Multiple markers | Auto-creates scoped files per stack |
- ## Structure
- ```
- agents/
- ├── SKILL.md # AI instructions
- ├── README.md # This file
- ├── LICENSE-MIT # Code license (MIT)
- ├── LICENSE-CC-BY-SA-4.0 # Content license (CC-BY-SA-4.0)
- ├── composer.json # PHP distribution
- ├── references/ # Convention documentation
- ├── scripts/ # Generator scripts
- │ ├── generate-agents.sh
- │ ├── validate-structure.sh
- │ └── detect-scopes.sh
- └── templates/ # Language-specific templates
- ├── go/
- ├── php/
- ├── typescript/
- └── python/
- ```
- ## Contributing
- Contributions welcome! Please submit PRs for:
- - Additional language templates
- - Detection signal improvements
- - Script enhancements
- - Documentation updates
- ## Governance and policies
- This repository follows the organisation-wide policies of `netresearch`:
- - [Governance](https://github.com/netresearch/.github/blob/main/GOVERNANCE.md): roles, how changes are decided and disputes resolved, and who controls access to sensitive resources.
- - [Roadmap](https://github.com/netresearch/.github/blob/main/ROADMAP.md): the maintenance work planned and excluded for the coming year.
- - [Handling of dependency and code analysis findings](https://github.com/netresearch/.github/blob/main/SECURITY.md#handling-of-dependency-and-code-analysis-findings): which vulnerability, licence and static-analysis findings block a change, the deadlines for the others, and how exceptions are recorded.
- - [Secret management](https://github.com/netresearch/.github/blob/main/SECURITY.md#secret-management): where CI secrets are stored, who can access them, and when they are rotated.
- - [Access roster](https://github.com/netresearch/.github/blob/main/docs/access-roster.md): the accounts with admin, maintain and write access to this repository.
- Checks that run on every pull request to `main` (`.github/workflows/security.yml`):
- - Dependency review: fails on a known vulnerability of severity high or critical in a dependency the pull request adds or changes.
- - Composer Audit: fails on a known vulnerability in a Composer dependency.
- - Opengrep: static security analysis of the repository's code; which findings fail the check is set by the [organisation's static analysis rule](https://github.com/netresearch/.github/blob/main/SECURITY.md#static-analysis-sast).
- - Betterleaks: fails on a committed secret.
- - zizmor: static analysis of the GitHub Actions workflows; findings go to code scanning and do not fail the check.
- What you can and cannot expect from this repository in terms of security, with its threat model: [docs/SECURITY-ASSURANCE.md](docs/SECURITY-ASSURANCE.md).
- ## License
- This project uses split licensing:
- - **Code** (scripts, workflows, configs): [MIT](LICENSE-MIT)
- - **Content** (skill definitions, documentation, references): [CC-BY-SA-4.0](LICENSE-CC-BY-SA-4.0)
- See the individual license files for full terms.
- ## Credits
- Developed and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/).
- ---
- **Made with ❤️ for Open Source by [Netresearch](https://www.netresearch.de/)**
skills/agent-rules/scripts/verify-commands.sh · Bundled script · 857 lines · 1 finding marked
- #!/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
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 140 on GitHub
- # 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
Version history
v3.17.011/13/2026
v3.16.510/24/2026
v3.16.410/18/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.