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/lib/template.sh
View on GitHub#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# Template rendering helper functions
# Remove sections that are entirely empty (only header + whitespace/empty tables)
# A section is: ## Header followed by content until next ## or EOF
# Empty means: only whitespace, empty table headers (2 rows only), or empty code blocks
remove_empty_sections() {
local content="$1"
# Use awk to process sections
echo "$content" | awk '
BEGIN {
section_header = ""
section_body = ""
preamble = ""
in_section = 0
}
# Match section headers (## Something)
/^## / {
# Flush previous section if it had real content
if (in_section) {
if (has_content(section_body)) {
print section_header
printf "%s", section_body
}
} else {
# Print any preamble before first section
printf "%s", preamble
}
section_header = $0
section_body = ""
in_section = 1
next
}
# Accumulate content
{
if (in_section) {
section_body = section_body $0 "\n"
} else {
preamble = preamble $0 "\n"
}
}
END {
# Flush last section
if (in_section && has_content(section_body)) {
print section_header
printf "%s", section_body
}
}
# Check if body has real content (not just empty structural elements)
function has_content(body, stripped, table_rows, n, i, data_rows) {
stripped = body
# Remove HTML comments
gsub(/<!--[^>]*-->/, "", stripped)
# Count table rows - if exactly 2 (header + divider), table is empty
# Split by newlines and count lines starting with |
n = split(stripped, lines, "\n")
table_rows = 0
data_rows = 0
for (i = 1; i <= n; i++) {
if (lines[i] ~ /^\|/) {
table_rows++
# Data row = table row that is NOT a header divider (|---|)
if (lines[i] !~ /^\|[-:| ]+\|$/) {
# Also not just the header row if we are still in first 2
if (table_rows > 2) {
data_rows++
}
}
}
}
# If we have a table with more than 2 rows, it has data
if (table_rows > 2) {
return 1
}
# Remove tables that are just header+divider (2 rows)
# Pattern: | ... |\n|---...|\n
gsub(/\|[^|\n]+(\|[^|\n]+)*\|\n\|[-:| ]+\|\n?/, "", stripped)
# Remove empty code blocks (``` followed by optional whitespace and ```)
gsub(/```[^\n]*\n[ \t]*\n?```/, "", stripped)
# Remove standalone code block markers
gsub(/```[a-z]*\n?/, "", stripped)
# Remove bullet points that are just placeholder markers or empty
gsub(/^[ \t]*[-*][ \t]*\n/, "", stripped)
# Remove lines that say "No scoped AGENTS.md files yet" or similar placeholder text
gsub(/- \(No scoped [^)]+\)/, "", stripped)
gsub(/- No known [^\n]+/, "", stripped)
# Check if anything substantive remains
gsub(/[ \t\n]/, "", stripped)
return length(stripped) > 0
}
'
}
# Render template with placeholder replacement
# Supports multi-line values using bash string replacement
render_template() {
local template_file="$1"
local output_file="$2"
local -n template_vars=$3
local content
content=$(cat "$template_file")
# Replace all placeholders using bash parameter expansion
# This handles multi-line values correctly
for key in "${!template_vars[@]}"; do
local value="${template_vars[$key]}"
content="${content//"{{$key}}"/$value}"
done
# Handle remaining unfilled placeholders
# Delete table rows containing unresolved placeholders
content=$(echo "$content" | sed '/^|.*{{[A-Z_]*}}.*|$/d')
# Delete bullet points with only unresolved placeholders
content=$(echo "$content" | sed '/^[[:space:]]*[-*][[:space:]]*{{[A-Z_][A-Z0-9_]*}}[[:space:]]*$/d')
# Delete lines that are ONLY a placeholder (prevents blank lines in tables)
content=$(echo "$content" | sed '/^{{[A-Z_][A-Z0-9_]*}}$/d')
# Also handle placeholders with leading/trailing whitespace
content=$(echo "$content" | sed '/^[[:space:]]*{{[A-Z_][A-Z0-9_]*}}[[:space:]]*$/d')
# Remove any remaining inline placeholders (better than "(not configured)" noise)
# shellcheck disable=SC2001 # regex quantifier over a character class;
# bash glob replacement cannot express "one class char then zero or more".
content=$(echo "$content" | sed 's/{{[A-Z_][A-Z0-9_]*}}//g')
# Remove empty lines that appear after table rows but before non-table content
# This fixes broken tables when placeholders were replaced with empty content
content=$(echo "$content" | awk '
/^\|.*\|$/ {
# Print any pending empty lines first if we are continuing a table
if (prev_was_table && pending_empty) {
# Skip the pending empty - it was between table rows with no data
}
print
prev_was_table=1
pending_empty=0
next
}
/^[[:space:]]*$/ {
if (prev_was_table) {
pending_empty=1 # Hold empty line, might be inside table
} else {
print # Normal empty line outside table
}
next
}
{
# Non-table line - do not print pending empty from table section
pending_empty=0
prev_was_table=0
print
}
')
# Clean up multiple consecutive empty lines
content=$(echo "$content" | cat -s)
# Remove empty sections (only header + whitespace/empty tables)
content=$(remove_empty_sections "$content")
# Final cleanup of multiple consecutive empty lines after section removal
content=$(echo "$content" | cat -s)
# Write output
printf '%s\n' "$content" | replace_file "$output_file"
}
# Write stdin to <file> by replacement: a temporary file in the same directory
# is renamed over the target, so a symlink there is replaced, never followed.
# An existing regular file keeps its mode; a new file gets the mode the umask
# gives a newly created file, not the 0600 of a temporary file. A directory at
# the path is refused (mv would move the file into it).
replace_file() {
local file="$1" dir tmp mode
if [ -d "$file" ] && [ ! -L "$file" ]; then
echo "Error: $file is a directory; not writing it" >&2
return 1
fi
dir="$(dirname "$file")"
if [ -f "$file" ] && [ ! -L "$file" ]; then
mode="$(stat -c %a "$file" 2>/dev/null || stat -f %Lp "$file")"
else
mode="$(printf '%o' $(( 0666 & ~0$(umask) )))"
fi
tmp="$(mktemp "$dir/.agents-write.XXXXXX")"
cat > "$tmp"
chmod "$mode" "$tmp"
[ -L "$file" ] && rm -f "$file"
mv -f "$tmp" "$file"
}
# Validate rendered content has no remaining placeholders
# Returns 0 if valid, 1 if placeholders found
validate_no_placeholders() {
local file="$1"
local strict="${2:-false}"
if grep -qE '\{\{[A-Z][A-Z0-9_]*\}\}' "$file"; then
local placeholders
placeholders=$(grep -oE '\{\{[A-Z][A-Z0-9_]*\}\}' "$file" | sort -u | tr '\n' ' ')
if [ "$strict" = "true" ]; then
echo "[ERROR] Unresolved placeholders in $file: $placeholders" >&2
return 1
else
echo "[WARN] Unresolved placeholders in $file: $placeholders" >&2
return 0
fi
fi
return 0
}
# Generate timestamp
get_timestamp() {
date +%Y-%m-%d
}
# Build scope index for root template
build_scope_index() {
local scopes_json="$1"
local index=""
local count
count=$(echo "$scopes_json" | jq '.scopes | length')
if [ "$count" -eq 0 ]; then
echo "- (No scoped AGENTS.md files yet)"
return
fi
while read -r scope; do
local path type description
path=$(echo "$scope" | jq -r '.path')
type=$(echo "$scope" | jq -r '.type')
description=$(get_scope_description "$type")
# A scope discovered only because it already carries an AGENTS.md has no
# type to describe. Let the file speak for itself — its own Overview
# line says what the directory is for, which beats any label this
# script could invent. Falls back to a neutral phrase, never to the
# bare type name, which reads as a bug in the generated output.
if [ "$type" = "existing" ]; then
description=$(sed -n '/^## Overview/,/^## /p' "$path/AGENTS.md" 2>/dev/null \
| grep -v '^##' | grep -v '^$' | head -1 | cut -c1-100)
[ -n "$description" ] || description="Scoped rules for \`$path/\`"
fi
index="$index- \`./$path/AGENTS.md\` — $description\n"
done < <(echo "$scopes_json" | jq -c '.scopes[]')
echo -e "$index"
}
# Get description for scope type
get_scope_description() {
local type="$1"
case "$type" in
"backend-go") echo "Backend services (Go)" ;;
"backend-php") echo "Backend services (PHP)" ;;
"backend-typescript") echo "Backend services (TypeScript/Node.js)" ;;
"backend-python") echo "Backend services (Python)" ;;
"frontend-typescript") echo "Frontend application (TypeScript/React/Vue)" ;;
"cli") echo "Command-line interface tools and entry points" ;;
"testing") echo "Test suites, fixtures, and testing utilities" ;;
"documentation") echo "Project documentation, guides, and reference materials" ;;
"examples") echo "Example applications, usage patterns, and sample code" ;;
"resources") echo "Static resources, assets, templates, and configuration files" ;;
"docker") echo "Container/Docker configuration for building and deploying images" ;;
"claude-code-skill") echo "Claude Code skill/plugin providing AI agent capabilities" ;;
"typo3-extension") echo "TYPO3 extension following TYPO3 CGL and PSR-12" ;;
"typo3-project") echo "TYPO3 project installation with site configuration" ;;
"oro-bundle") echo "Oro bundle following Oro Architecture and Symfony best practices" ;;
"oro-project") echo "Oro application with platform configuration and bundles" ;;
"symfony") echo "Symfony application following Symfony best practices" ;;
"github-actions") echo "GitHub Actions workflows and CI/CD automation" ;;
"gitlab-ci") echo "GitLab CI/CD pipeline configuration" ;;
"concourse") echo "Concourse CI pipeline and task definitions" ;;
"typo3-testing") echo "TYPO3 test suites, fixtures and the Docker test runner" ;;
"typo3-docs") echo "TYPO3 documentation (reStructuredText, rendered by the docs toolchain)" ;;
"ddev") echo "DDEV local development environment and its commands" ;;
"python-modern") echo "Python package using the modern toolchain (uv, ruff, pyproject)" ;;
# Falling through prints the raw type name into user-facing output,
# which reads as a bug rather than a description. Anything reaching
# here is a type someone added to detect-scopes.sh without a matching
# case above — say so plainly instead of leaking the identifier.
*) echo "Scoped rules for this directory" ;;
esac
}
# Get language-specific conventions text
get_language_conventions() {
local language="$1"
local version="$2"
case "$language" in
"go")
echo "- Follow Go $version conventions and idioms"
;;
"php")
echo "- Follow PSR-12 coding standards and PHP $version features"
;;
"typescript")
echo "- Use TypeScript strict mode with proper type annotations"
;;
"python")
echo "- Follow PEP 8 style guide and Python $version features"
;;
*)
echo ""
;;
esac
}
# Format command with fallback text
format_command() {
local cmd="$1"
local fallback="$2"
if [ -n "$cmd" ] && [ "$cmd" != "null" ]; then
echo "$cmd"
else
echo "$fallback"
fi
}
# Check if file has generated section markers
has_generated_markers() {
local file="$1"
grep -q 'AGENTS-GENERATED:START' "$file" 2>/dev/null
}
# Extract section names from file
get_section_names() {
local file="$1"
grep -oE 'AGENTS-GENERATED:START [a-z0-9-]+' "$file" 2>/dev/null | sed 's/AGENTS-GENERATED:START //' | sort -u
}
# Extract content between markers for a section
get_section_content() {
local file="$1"
local section="$2"
sed -n "/AGENTS-GENERATED:START $section/,/AGENTS-GENERATED:END $section/p" "$file" 2>/dev/null | \
sed '1d;$d' # Remove the marker lines themselves
}
# Update only generated sections in an existing file
# Preserves all content outside markers
update_generated_sections() {
local template_file="$1"
local existing_file="$2"
local output_file="$3"
# shellcheck disable=SC2034 # nameref, read through the indirect name below
local -n update_vars=$4
# First render the template to get new content
local temp_rendered
temp_rendered=$(mktemp)
render_template "$template_file" "$temp_rendered" update_vars
# If existing file doesn't have markers, just overwrite
if ! has_generated_markers "$existing_file"; then
replace_file "$output_file" < "$temp_rendered"
rm -f "$temp_rendered"
return 0
fi
# Get all section names from the rendered template
local sections
sections=$(get_section_names "$temp_rendered")
# Start with the existing file content
local result
result=$(cat "$existing_file")
# Replace each generated section
for section in $sections; do
local new_content
new_content=$(get_section_content "$temp_rendered" "$section")
if [ -n "$new_content" ]; then
# Create a sed-safe version of the new content
# Use awk for multi-line replacement
result=$(echo "$result" | awk -v section="$section" -v newcontent="$new_content" '
BEGIN { in_section = 0 }
/AGENTS-GENERATED:START / && $0 ~ section {
print
in_section = 1
next
}
/AGENTS-GENERATED:END / && $0 ~ section {
print newcontent
print
in_section = 0
next
}
!in_section { print }
')
fi
done
# Update timestamp
local today
today=$(date +%Y-%m-%d)
# shellcheck disable=SC2001 # see above: quantified class, not a glob.
result=$(echo "$result" | sed "s/Last updated: [0-9-]*/Last updated: $today/")
# Write result
printf '%s\n' "$result" | replace_file "$output_file"
# Clean up
rm -f "$temp_rendered"
}
# Render template - respects update mode
# If update_mode=true and file exists with markers, only updates generated sections
render_template_smart() {
local template_file="$1"
local output_file="$2"
# shellcheck disable=SC2034 # nameref, read through the indirect name below
local -n smart_vars=$3
local update_mode="${4:-false}"
if [ "$update_mode" = "true" ] && [ -f "$output_file" ] && has_generated_markers "$output_file"; then
# Update mode - preserve human edits
update_generated_sections "$template_file" "$output_file" "$output_file" smart_vars
else
# Normal mode - full render
render_template "$template_file" "$output_file" smart_vars
fi
}
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: 469k | 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 |