Skip to content

netresearch/agent-rules-skill / skills/agent-rules

agent-rules

Flagged

Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.

FileKindSize
AGENTS.mdmarkdown4.0 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md5.2 KB
assets/.markdownlint-cli2.jsoncother624 B
assets/example-workflows/validate-agents.ymlconfig2.8 KB
assets/root-thin.mdmarkdown5.7 KB
assets/root-verbose.mdmarkdown5.5 KB
assets/scoped/backend-go.mdmarkdown3.6 KB
assets/scoped/backend-php.mdmarkdown3.0 KB
assets/scoped/backend-python.mdmarkdown2.6 KB
assets/scoped/backend-typescript.mdmarkdown2.8 KB
assets/scoped/claude-code-skill.mdmarkdown3.4 KB
assets/scoped/cli.mdmarkdown2.7 KB
assets/scoped/concourse.mdmarkdown5.2 KB
assets/scoped/ddev.mdmarkdown2.4 KB
assets/scoped/docker.mdmarkdown5.3 KB
assets/scoped/documentation.mdmarkdown3.5 KB
assets/scoped/examples.mdmarkdown3.4 KB
assets/scoped/frontend-typescript.mdmarkdown2.7 KB
assets/scoped/github-actions.mdmarkdown5.2 KB
assets/scoped/gitlab-ci.mdmarkdown4.6 KB
assets/scoped/oro-bundle.mdmarkdown6.5 KB
assets/scoped/oro-project.mdmarkdown5.5 KB
assets/scoped/python-modern.mdmarkdown6.1 KB
assets/scoped/resources.mdmarkdown3.5 KB
assets/scoped/skill-repo.mdmarkdown5.4 KB
assets/scoped/symfony.mdmarkdown5.3 KB
assets/scoped/testing.mdmarkdown3.0 KB
assets/scoped/typo3-docs.mdmarkdown3.6 KB
assets/scoped/typo3-extension.mdmarkdown5.1 KB
assets/scoped/typo3-project.mdmarkdown4.7 KB
assets/scoped/typo3-testing.mdmarkdown3.0 KB
checkpoints.yamlconfig14.4 KB
evals/evals.jsonconfig22.9 KB
references/ai-contribution-guidelines.mdmarkdown2.6 KB
references/ai-tool-compatibility.mdmarkdown8.0 KB
references/directory-coverage.mdmarkdown2.5 KB
references/examples/coding-agent-cli/AGENTS.mdmarkdown2.5 KB
references/examples/coding-agent-cli/go.modmanifest45 B
references/examples/coding-agent-cli/scripts-AGENTS.mdmarkdown10.1 KB
references/examples/express-api-ts/.env.exampleother232 B
references/examples/express-api-ts/AGENTS.mdmarkdown3.1 KB
references/examples/express-api-ts/package.jsonmanifest757 B
references/examples/express-api-ts/pnpm-lock.yamlmanifest101 B
references/examples/express-api-ts/src/AGENTS.mdmarkdown3.1 KB
references/examples/express-api-ts/src/config.tsscript917 B
references/examples/express-api-ts/src/controllers/userController.tsscript2.1 KB
references/examples/express-api-ts/src/index.tsscript671 B
references/examples/express-api-ts/src/middleware/errorHandler.tsscript1.0 KB
references/examples/express-api-ts/src/middleware/requestLogger.tsscript471 B
references/examples/express-api-ts/src/routes/health.tsscript428 B
references/examples/express-api-ts/src/routes/users.tsscript397 B
references/examples/express-api-ts/src/utils/errors.tsscript1.2 KB
references/examples/express-api-ts/src/utils/logger.tsscript441 B
references/examples/express-api-ts/tsconfig.jsonconfig630 B
references/examples/fastapi-app/.env.exampleother348 B
references/examples/fastapi-app/AGENTS.mdmarkdown3.2 KB
references/examples/fastapi-app/pyproject.tomlmanifest1.8 KB
references/examples/fastapi-app/src/AGENTS.mdmarkdown2.9 KB
references/examples/fastapi-app/src/__init__.pyscript58 B
references/examples/fastapi-app/src/config.pyscript1.1 KB
references/examples/fastapi-app/src/main.pyscript1.7 KB
references/examples/fastapi-app/src/models/__init__.pyscript278 B
references/examples/fastapi-app/src/models/item.pyscript1.0 KB
references/examples/fastapi-app/src/models/user.pyscript922 B
references/examples/fastapi-app/src/routes/__init__.pyscript110 B
references/examples/fastapi-app/src/routes/health.pyscript470 B
references/examples/fastapi-app/src/routes/items.pyscript1.9 KB
references/examples/fastapi-app/src/routes/users.pyscript1.7 KB
references/examples/fastapi-app/src/services/__init__.pyscript174 B
references/examples/fastapi-app/src/services/item_service.pyscript2.5 KB
references/examples/fastapi-app/src/services/user_service.pyscript2.1 KB
references/examples/fastapi-app/uv.lockmanifest136 B
references/examples/go-api-with-react-admin/.scopesother93 B
references/examples/go-api-with-react-admin/AGENTS.mdmarkdown3.0 KB
references/examples/go-api-with-react-admin/admin/package.jsonmanifest423 B
references/examples/go-api-with-react-admin/admin/src/App.tsxother101 B
references/examples/go-api-with-react-admin/cmd/api/main.goscript75 B
references/examples/go-api-with-react-admin/go.modmanifest31 B
references/examples/go-api-with-react-admin/main.goscript71 B
references/examples/go-with-internal-web-tsx/.scopesother102 B
references/examples/go-with-internal-web-tsx/AGENTS.mdmarkdown3.1 KB
references/examples/go-with-internal-web-tsx/go.modmanifest34 B
references/examples/go-with-internal-web-tsx/internal/web/AGENTS.mdmarkdown3.1 KB
references/examples/go-with-internal-web-tsx/internal/web/package.jsonmanifest329 B
references/examples/go-with-internal-web-tsx/internal/web/src/App.tsxother57 B
references/examples/go-with-internal-web-tsx/internal/web/src/Button.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Footer.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Header.tsxother63 B
references/examples/go-with-internal-web-tsx/internal/web/src/Sidebar.tsxother65 B
references/examples/go-with-internal-web-tsx/main.goscript85 B
references/examples/go-with-internal-web-tsx/package-lock.jsonmanifest87 B
references/examples/go-with-internal-web-tsx/package.jsonmanifest221 B
references/examples/ldap-selfservice/AGENTS.mdmarkdown2.5 KB
references/examples/ldap-selfservice/go.modmanifest45 B
references/examples/ldap-selfservice/internal-AGENTS.mdmarkdown10.0 KB
references/examples/ldap-selfservice/internal-web-AGENTS.mdmarkdown12.1 KB
references/examples/php-with-frontend/.scopesother89 B
references/examples/php-with-frontend/AGENTS.mdmarkdown3.1 KB
references/examples/php-with-frontend/composer.jsonconfig185 B
references/examples/php-with-frontend/package.jsonmanifest307 B
references/examples/php-with-frontend/pnpm-lock.yamlmanifest101 B
references/examples/php-with-frontend/src/Controller.phpscript41 B
references/examples/php-with-frontend/web/AGENTS.mdmarkdown3.1 KB
references/examples/php-with-frontend/web/package.jsonmanifest515 B
references/examples/php-with-frontend/web/src/App.tsxother63 B
references/examples/php-with-frontend/web/src/Button.tsxother215 B
references/examples/php-with-frontend/web/src/Footer.tsxother125 B
references/examples/php-with-frontend/web/src/Header.tsxother122 B
references/examples/php-with-frontend/web/src/main.tsxother41 B
references/examples/php-with-frontend/web/tsconfig.jsonconfig280 B
references/examples/pnpm-workspace/AGENTS.mdmarkdown2.6 KB
references/examples/pnpm-workspace/package.jsonmanifest105 B
references/examples/pnpm-workspace/packages/web/package.jsonmanifest187 B
references/examples/pnpm-workspace/packages/web/src/index.tsxother258 B
references/examples/pnpm-workspace/pnpm-lock.yamlmanifest920 B
references/examples/pnpm-workspace/pnpm-workspace.yamlconfig27 B
references/examples/simple-ldap-go/AGENTS.mdmarkdown2.5 KB
references/examples/simple-ldap-go/examples-AGENTS.mdmarkdown1.8 KB
references/examples/simple-ldap-go/go.modmanifest43 B
references/examples/t3x-rte-ckeditor-image/AGENTS.mdmarkdown2.5 KB
references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.mdmarkdown12.0 KB
references/examples/t3x-rte-ckeditor-image/composer.jsonconfig174 B
references/feedback-memory-schema.mdmarkdown6.2 KB
references/fleet-sync-sweep.mdmarkdown4.8 KB
references/git-hooks-setup.mdmarkdown2.5 KB
references/output-structure.mdmarkdown5.4 KB
references/quality-rubric.mdmarkdown6.2 KB
references/scripts-guide.mdmarkdown7.7 KB
references/verification-guide.mdmarkdown9.4 KB
scripts/analyze-git-history.shexecutablescript10.2 KB
scripts/check-freshness.shexecutablescript8.9 KB
scripts/detect-golden-samples.shexecutablescript5.7 KB
scripts/detect-heuristics.shexecutablescript3.2 KB
scripts/detect-project.shexecutablescript19.6 KB
scripts/detect-scopes.shexecutablescript13.4 KB
scripts/detect-utilities.shexecutablescript4.6 KB
scripts/extract-adrs.shexecutablescript6.8 KB
scripts/extract-agent-configs.shexecutablescript9.3 KB
scripts/extract-architecture-rules.shexecutablescript19.9 KB
scripts/extract-ci-commands.shexecutablescript12.5 KB
scripts/extract-ci-rules.shexecutablescript16.1 KB
scripts/extract-commands.shexecutablescript11.9 KB
scripts/extract-documentation.shexecutablescript7.8 KB
scripts/extract-github-rulesets.shexecutablescript3.8 KB
scripts/extract-github-settings.shexecutablescript3.6 KB
scripts/extract-ide-settings.shexecutablescript7.0 KB
scripts/extract-platform-files.shexecutablescript8.0 KB
scripts/extract-quality-configs.shexecutablescript14.9 KB
scripts/generate-agents.shexecutablescript118.2 KB
scripts/generate-file-map.shexecutablescript4.6 KB
scripts/lib/config-root.shexecutablescript5.8 KB
scripts/lib/git.shscript1.2 KB
scripts/lib/summary.shscript11.7 KB
scripts/lib/template.shexecutablescript15.9 KB
scripts/score-agents.shexecutablescript9.8 KB
scripts/tests/test-agents-file-write-boundary.shscript5.8 KB
scripts/tests/test-agents-scan-dependency-trees.shexecutablescript4.5 KB
scripts/tests/test-changelog-rule.shexecutablescript3.4 KB
scripts/tests/test-claude-import-file.shscript3.3 KB
scripts/tests/test-command-allowlist.shexecutablescript4.7 KB
scripts/tests/test-dependency-tree-exclusion.shscript2.5 KB
scripts/tests/test-extract-commands-real-scripts.shexecutablescript4.0 KB
scripts/tests/test-git-history-counts.shexecutablescript3.6 KB
scripts/tests/test-golden-sample-file-names.shexecutablescript2.2 KB
scripts/tests/test-json-manifest.shexecutablescript5.5 KB
scripts/tests/test-last-verified-opt-in.shscript1.6 KB
scripts/tests/test-make-target-lookup.shscript2.5 KB
scripts/tests/test-merge-heuristic.shscript1.8 KB
scripts/tests/test-scope-index-heading.shexecutablescript4.4 KB
scripts/tests/test-scope-index-keeps-existing.shexecutablescript2.5 KB
scripts/tests/test-symlink-write-boundary.shexecutablescript6.3 KB
scripts/tests/test-untrusted-git-config.shscript5.0 KB
scripts/tests/test-verification-sidecar.shscript2.7 KB
scripts/validate-structure.shexecutablescript13.3 KB
scripts/verify-commands.shexecutablescript32.5 KB
scripts/verify-content.shexecutablescript13.2 KB

scripts/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
}
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall