netresearch/agent-rules-skill / skills/agent-rules
agent-rules
FlaggedUse when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
scripts/check-freshness.sh
View on GitHub#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# Check if AGENTS.md files are up to date with recent git commits
# Compares the "Last updated" date in each AGENTS.md with commits affecting that scope
set -euo pipefail
# shellcheck source-path=SCRIPTDIR
# shellcheck disable=SC1091 # the pre-commit hook runs shellcheck without
# -x, so it cannot follow this source no matter how the path is written.
source "$(dirname "${BASH_SOURCE[0]}")/lib/git.sh"
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
# Options
VERBOSE=false
JSON=false
DAYS_THRESHOLD=7 # Warn if commits are older than this many days after last update (used below)
# Parse flags
while [[ $# -gt 0 ]]; do
case $1 in
--verbose|-v)
VERBOSE=true
shift
;;
--json)
JSON=true
shift
;;
--threshold=*)
# shellcheck disable=SC2034 # Reserved for future threshold-based staleness check
DAYS_THRESHOLD="${1#*=}"
shift
;;
--help|-h)
cat <<EOF
Usage: check-freshness.sh [PROJECT_DIR] [OPTIONS]
Check if AGENTS.md files are up to date with recent git commits.
Options:
--verbose, -v Show detailed output including commit lists
--json Emit machine-readable JSON on stdout (human output suppressed)
--threshold=DAYS Days after last update to consider stale (default: 7)
--help, -h Show this help message
Examples:
check-freshness.sh . # Check all AGENTS.md freshness
check-freshness.sh . --verbose # Show commit details
check-freshness.sh . --threshold=14 # Use 14-day threshold
EOF
exit 0
;;
*)
PROJECT_DIR="$1"
shift
;;
esac
done
# Ensure we're in a git repository
if ! project_git rev-parse --git-dir > /dev/null 2>&1; then
echo "Error: Not a git repository"
exit 1
fi
# 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_FILES=()
if [[ "$JSON" = true ]]; then
exec 3>&1 1>/dev/null
fi
STALE_COUNT=0
FRESH_COUNT=0
UNKNOWN_COUNT=0
log() {
if [ "$VERBOSE" = true ]; then
echo "[INFO] $*" >&2
fi
}
# Extract the "Last updated" date from AGENTS.md header
# Format: <!-- Managed by agent: ... Last updated: YYYY-MM-DD -->
extract_last_updated() {
local file="$1"
local date_str
# Try to extract date from header comment
date_str=$(grep -o 'Last updated: [0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}' "$file" 2>/dev/null | head -1 | sed 's/Last updated: //')
if [ -n "$date_str" ]; then
echo "$date_str"
return 0
fi
# Try alternative formats
# "Created: YYYY-MM-DD" or "Updated: YYYY-MM-DD"
date_str=$(grep -oE '(Created|Updated): [0-9]{4}-[0-9]{2}-[0-9]{2}' "$file" 2>/dev/null | head -1 | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}')
if [ -n "$date_str" ]; then
echo "$date_str"
return 0
fi
return 1
}
# Get the scope directory for an AGENTS.md file
# Root AGENTS.md covers the whole repo, scoped files cover their directory
get_scope_path() {
local agents_file="$1"
local dir
dir=$(dirname "$agents_file")
if [ "$dir" = "." ]; then
echo "." # Root covers everything
else
echo "$dir"
fi
}
# Count commits in a scope since a given date
count_commits_since() {
local scope_path="$1"
local since_date="$2"
local count
if [ "$scope_path" = "." ]; then
# Root: check all commits except AGENTS.md files themselves
count=$(project_git log --oneline --since="$since_date" -- . ':(exclude)**/AGENTS.md' 2>/dev/null | wc -l)
else
# Scoped: check commits in that directory
count=$(project_git log --oneline --since="$since_date" -- "$scope_path" ':(exclude)**/AGENTS.md' 2>/dev/null | wc -l)
fi
echo "$count"
}
# Get commit summary for a scope since a given date
get_commits_since() {
local scope_path="$1"
local since_date="$2"
if [ "$scope_path" = "." ]; then
project_git log --oneline --since="$since_date" -- . ':(exclude)**/AGENTS.md' 2>/dev/null | head -10
else
project_git log --oneline --since="$since_date" -- "$scope_path" ':(exclude)**/AGENTS.md' 2>/dev/null | head -10
fi
}
# Get files changed in a scope since a given date
get_changed_files_since() {
local scope_path="$1"
local since_date="$2"
if [ "$scope_path" = "." ]; then
project_git log --name-only --pretty=format: --since="$since_date" -- . ':(exclude)**/AGENTS.md' 2>/dev/null | sort -u | grep -v '^$' | head -20
else
project_git log --name-only --pretty=format: --since="$since_date" -- "$scope_path" ':(exclude)**/AGENTS.md' 2>/dev/null | sort -u | grep -v '^$' | head -20
fi
}
# Check freshness of a single AGENTS.md file
check_file_freshness() {
local agents_file="$1"
local rel_path="${agents_file#"$PROJECT_DIR"/}"
local last_updated
local scope_path
local commit_count
echo "Checking: $rel_path"
# Extract last updated date
if ! last_updated=$(extract_last_updated "$agents_file"); then
echo " ⚠️ No 'Last updated' date found in header"
((UNKNOWN_COUNT++)) || true
if [[ "$JSON" = true ]]; then
JSON_FILES+=("$(jq -nc --arg path "$rel_path" \
'{path:$path,status:"unknown",last_updated:null,commits_since:null}')")
fi
return 1
fi
log " Last updated: $last_updated"
# Get scope path
scope_path=$(get_scope_path "$agents_file")
log " Scope: $scope_path"
# Count commits since last update
commit_count=$(count_commits_since "$scope_path" "$last_updated")
if [ "$commit_count" -eq 0 ]; then
echo " ✅ Up to date (no commits since $last_updated)"
((FRESH_COUNT++)) || true
if [[ "$JSON" = true ]]; then
JSON_FILES+=("$(jq -nc --arg path "$rel_path" --arg lu "$last_updated" \
'{path:$path,status:"fresh",last_updated:$lu,commits_since:0}')")
fi
return 0
fi
# Check if commits are significant
echo " ⚠️ Potentially stale: $commit_count commit(s) since $last_updated"
((STALE_COUNT++)) || true
if [[ "$JSON" = true ]]; then
JSON_FILES+=("$(jq -nc --arg path "$rel_path" --arg lu "$last_updated" --argjson cs "$commit_count" \
'{path:$path,status:"stale",last_updated:$lu,commits_since:$cs}')")
fi
if [ "$VERBOSE" = true ]; then
echo " Recent commits:"
get_commits_since "$scope_path" "$last_updated" | while read -r line; do
echo " - $line"
done
echo " Changed files:"
get_changed_files_since "$scope_path" "$last_updated" | while read -r line; do
echo " - $line"
done
fi
return 1
}
# Main
echo "Checking AGENTS.md freshness in: $PROJECT_DIR"
echo ""
# Find all AGENTS.md files. Dependency trees are excluded, as in
# validate-structure.sh (#84): a third-party AGENTS.md is not this project's.
AGENTS_FILES=$(find "$PROJECT_DIR" -name "AGENTS.md" -type f \
-not -path "*/.git/*" \
-not -path "*/vendor/*" \
-not -path "*/node_modules/*" \
-not -path "*/.Build/*" \
2>/dev/null | sort)
if [ -z "$AGENTS_FILES" ]; then
echo "No AGENTS.md files found"
exit 0
fi
# Check each file.
# `|| true`: check_file_freshness returns non-zero for stale/unknown files; without
# this guard `set -e` aborts the loop on the first such file, processing only one
# file and defeating the summary below (and forcing the validate-structure caller to
# always warn). Tolerating the non-zero lets every file be counted.
while read -r file; do
check_file_freshness "$file" || true
echo ""
done <<< "$AGENTS_FILES"
# Emit JSON document (machine-readable) and exit before the human summary.
if [[ "$JSON" = true ]]; then
if [[ "${#JSON_FILES[@]}" -eq 0 ]]; then
files_json='[]'
else
files_json=$(printf '%s\n' "${JSON_FILES[@]}" | jq -s '.')
fi
jq -nc \
--argjson files "$files_json" \
--argjson fresh "$FRESH_COUNT" \
--argjson stale "$STALE_COUNT" \
--argjson unknown "$UNKNOWN_COUNT" \
'{script:"check-freshness",schema:1,summary:{fresh:$fresh,stale:$stale,unknown:$unknown},files:$files}' >&3
if [[ "$STALE_COUNT" -gt 0 ]]; then exit 1; fi
exit 0
fi
# Summary
echo "=== Freshness Summary ==="
echo "✅ Up to date: $FRESH_COUNT"
echo "⚠️ Potentially stale: $STALE_COUNT"
[ "$UNKNOWN_COUNT" -gt 0 ] && echo "❓ Unknown (no date): $UNKNOWN_COUNT"
if [ "$STALE_COUNT" -gt 0 ]; then
echo ""
echo "Recommendation: Review the stale AGENTS.md files and update if needed."
echo "Use --verbose to see which commits and files have changed."
exit 1
fi
exit 0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |