Agent Rules

Name: Agent Rules
Author: netresearch

netresearch/agent-rules-skill

543 installs
69 repo stars
Updated August 2, 2026
netresearch/agent-rules-skill

agent-rules is a Claude Code plugin skill that generates AGENTS.md structure, repository file maps, and verification scripts for developers who need consistent agent conventions across every coding session.

About

agent-rules is a Claude Code skill and plugin from netresearch/agent-rules-skill that keeps AGENTS.md sections, file maps, and verification scripts synchronized with repository reality. Bundled bash scripts include generate-file-map.sh, verify-commands.sh, analyze-git-history.sh, and detect-utilities.sh under skills/agent-rules/scripts. Developers reach for agent-rules when onboarding AI agents to large repos and needing managed AGENTS-GENERATED blocks for overview and filemap tables without manual drift. The plugin enforces section order while allowing content edits, helping every agent session share the same structural conventions.

Claude Code plugin packaging with skills/ layout and .claude-plugin/plugin.json manifest.
Bundled bash scripts: verify-commands, generate-file-map, analyze-git-history, detect-utilities, extract-platform-files.
AGENTS.md managed sections with generated overview, filemap, golden samples, setup, and structure blocks.
Composer install path: netresearch/agent-rules-skill for PHP ecosystems adopting the plugin.
Golden sample pointer to skills/agent-rules/SKILL.md as the reference implementation pattern.

Agent Rules by the numbers

543 all-time installs (skills.sh)
+37 installs in the week ending Aug 4, 2026 (Skillselion tracking)
Ranked #95 of 782 Skill Development skills by installs in the Skillselion catalog
Security screen: HIGH risk (skills.sh audit)
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/netresearch/agent-rules-skill --skill agent-rules

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/netresearch/agent-rules-skill/agent-rules.svg)](https://skillselion.com/skills/netresearch/agent-rules-skill/agent-rules)

Installs	543
repo stars	★ 69
Security audit	2 / 3 scanners passed
Last updated	August 2, 2026
Repository	netresearch/agent-rules-skill ↗

How do you generate AGENTS.md for Claude Code?

Install and maintain a Claude Code agent-rules plugin that generates AGENTS.md structure, file maps, and verification scripts so repo conventions stay consistent for every agent session.

Who is it for?

Teams adopting Claude Code agent-rules plugins who need auto-generated AGENTS.md file maps and verification scripts for large repositories.

Skip if: Single-file scripts with no agent onboarding needs, or projects that do not use AGENTS.md or Claude Code plugin conventions.

When should I use this skill?

A developer installs or updates the agent-rules plugin, needs AGENTS.md file maps regenerated, or wants verify-commands checks for repo conventions.

What you get

Structured AGENTS.md with generated overview and filemap tables, plus verify-commands and file-map shell scripts aligned to the repo.

AGENTS.md file map
verification script results

By the numbers

Bundles at least 4 bash scripts: verify-commands, generate-file-map, analyze-git-history, detect-utilities

Files

assets/
- example-workflows/
- scoped/
evals/
references/
- examples/
  - coding-agent-cli/
  - express-api-ts/
    - src/
      - controllers/
      - middleware/
      - routes/
      - utils/
  - fastapi-app/
    - src/
      - models/
      - routes/
      - services/
  - go-api-with-react-admin/
    - admin/
      - src/
    - cmd/
      - api/
  - go-with-internal-web-tsx/
    - internal/
      - web/
        src/
  - ldap-selfservice/
  - php-with-frontend/
    - src/

SKILL.mdMarkdownGitHub ↗

AGENTS.md — agents

Overview

Claude Code skill/plugin providing AI agent capabilities

Key Files

File	Purpose
`skills/agent-rules/scripts/verify-commands.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/generate-file-map.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/analyze-git-history.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/detect-utilities.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/extract-platform-files.sh`	!/usr/bin/env bash

Golden Samples (follow these patterns)

Pattern	Reference
Standard implementation	`skills/agent-rules/SKILL.md`

Setup & environment

Plugin: agents v2.8.0
Skills: 1 skill(s) in skills/
Install: composer require netresearch/agent-rules-skill

Directory structure

.claude-plugin/
  plugin.json          → Plugin manifest (name, version, skills)
skills/
  <skill-name>/
    SKILL.md           → Skill definition and instructions
    assets/            → Templates, reference docs
    scripts/           → Shell scripts for automation
    references/        → Examples, golden samples

Build & tests

Lint scripts: shellcheck skills/*/scripts/*.sh
Validate plugin: jq . .claude-plugin/plugin.json

Code style & conventions

SKILL.md: Clear, actionable instructions for AI agents
Shell scripts: Follow ShellCheck recommendations
Templates: Use `` syntax for variables
Keep skills focused on one domain/task
Include checkpoints for verification
Provide golden samples for pattern demonstration

Skill design principles

Actionable: Tell agents WHAT to do, not just WHAT things are
Verifiable: Include checkpoints agents can run to verify work
Scoped: One skill = one domain (don't mix concerns)
Referenced: Point to golden samples, not generic examples
Minimal: Include only what agents need; avoid documentation bloat

Security & safety

Never include secrets or credentials in skills
Validate all user inputs in scripts
Use placeholder values in examples: your-api-key, example.com
Review generated content for sensitive information

PR/commit checklist

[ ] ShellCheck passes: shellcheck skills/*/scripts/*.sh
[ ] SKILL.md instructions are clear and actionable
[ ] Templates use whole-line placeholders (not inline)
[ ] Golden samples exist for key patterns
[ ] Checkpoints are verifiable
[ ] plugin.json version updated if releasing

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing skills for patterns
Review Claude Code documentation
Test skills with claude --skill <name>
Check root AGENTS.md for project conventions

Example GitHub Actions workflow for validating AGENTS.md file

AGENTS.md — agents

Overview

Claude Code skill/plugin providing AI agent capabilities

Key Files

File	Purpose
`skills/agent-rules/scripts/verify-commands.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/generate-file-map.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/analyze-git-history.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/detect-utilities.sh`	!/usr/bin/env bash
`skills/agent-rules/scripts/extract-platform-files.sh`	!/usr/bin/env bash

Golden Samples (follow these patterns)

Pattern	Reference
Standard implementation	`skills/agent-rules/SKILL.md`

Setup & environment

Plugin: agents v2.8.0
Skills: 1 skill(s) in skills/
Install: composer require netresearch/agent-rules-skill

Directory structure

.claude-plugin/
  plugin.json          → Plugin manifest (name, version, skills)
skills/
  <skill-name>/
    SKILL.md           → Skill definition and instructions
    assets/            → Templates, reference docs
    scripts/           → Shell scripts for automation
    references/        → Examples, golden samples

Build & tests

Lint scripts: shellcheck skills/*/scripts/*.sh
Validate plugin: jq . .claude-plugin/plugin.json

Code style & conventions

SKILL.md: Clear, actionable instructions for AI agents
Shell scripts: Follow ShellCheck recommendations
Templates: Use `` syntax for variables
Keep skills focused on one domain/task
Include checkpoints for verification
Provide golden samples for pattern demonstration

Skill design principles

Actionable: Tell agents WHAT to do, not just WHAT things are
Verifiable: Include checkpoints agents can run to verify work
Scoped: One skill = one domain (don't mix concerns)
Referenced: Point to golden samples, not generic examples
Minimal: Include only what agents need; avoid documentation bloat

Security & safety

Never include secrets or credentials in skills
Validate all user inputs in scripts
Use placeholder values in examples: your-api-key, example.com
Review generated content for sensitive information

PR/commit checklist

[ ] ShellCheck passes: shellcheck skills/*/scripts/*.sh
[ ] SKILL.md instructions are clear and actionable
[ ] Templates use whole-line placeholders (not inline)
[ ] Golden samples exist for key patterns
[ ] Checkpoints are verifiable
[ ] plugin.json version updated if releasing

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing skills for patterns
Review Claude Code documentation
Test skills with claude --skill <name>
Check root AGENTS.md for project conventions

# Example GitHub Actions workflow for validating AGENTS.md files
# Copy this to your repository's .github/workflows/ directory
#
# This workflow runs on:
# - Push/PR to any AGENTS.md file
# - Manual dispatch
#
# Customize the validation steps to match your project's setup.

name: Validate AGENTS.md

on:
  push:
    paths:
      - 'AGENTS.md'
      - '**/AGENTS.md'
  pull_request:
    paths:
      - 'AGENTS.md'
      - '**/AGENTS.md'
  workflow_dispatch:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check AGENTS.md exists
        run: |
          if [ ! -f "AGENTS.md" ]; then
            echo "ERROR: AGENTS.md not found in repository root"
            exit 1
          fi
          echo "AGENTS.md found"

      - name: Validate structure
        run: |
          # Check for required sections (customize this list for your needs)
          required_sections=(
            "## Overview"
            "## Commands"
          )

          for section in "${required_sections[@]}"; do
            if ! grep -qi "^$section" AGENTS.md; then
              echo "WARNING: Missing section: $section"
            fi
          done
          echo "Structure validation complete"

      - name: Check for unresolved placeholders
        run: |
          # Fail if {{PLACEHOLDER}} patterns exist
          if grep -E '\{\{[A-Z][A-Z0-9_]*\}\}' AGENTS.md; then
            echo "ERROR: Found unresolved placeholders"
            exit 1
          fi
          echo "No unresolved placeholders"

      - name: Check for stale content
        run: |
          # Error if unresolved template placeholders exist
          if grep -qE '\{\{[A-Z_]+\}\}' AGENTS.md; then
            echo "ERROR: Found unresolved template placeholders - regenerate AGENTS.md"
            exit 1
          fi

          # Check freshness (optional - customize days threshold)
          if grep -q "Last updated:" AGENTS.md; then
            last_updated=$(grep "Last updated:" AGENTS.md | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1)
            if [ -n "$last_updated" ]; then
              days_old=$(( ($(date +%s) - $(date -d "$last_updated" +%s)) / 86400 ))
              if [ "$days_old" -gt 90 ]; then
                echo "WARNING: AGENTS.md is $days_old days old - consider updating"
              fi
            fi
          fi
          echo "Freshness check complete"

      # Optional: Verify documented commands work
      # Uncomment and customize for your project
      # - name: Verify commands
      #   run: |
      #     # Example: check that npm scripts exist
      #     if [ -f "package.json" ]; then
      #       # Extract commands from AGENTS.md and verify they exist
      #       echo "Verifying npm commands..."
      #     fi

AGENTS.md

Precedence: the closest `AGENTS.md` to the files you're changing wins. Root holds global defaults only.

Commands{{VERIFIED_STATUS}}

Source: {{COMMAND_SOURCE}} — CI-sourced commands are most reliable

Task	Command	~Time
Typecheck	{{TYPECHECK_CMD}}	{{TYPECHECK_TIME}}
Lint	{{LINT_CMD}}	{{LINT_TIME}}
Format	{{FORMAT_CMD}}	{{FORMAT_TIME}}
Test (single)	{{TEST_SINGLE_CMD}}	~2s
Test (all)	{{TEST_CMD}}	{{TEST_TIME}}
Build	{{BUILD_CMD}}	{{BUILD_TIME}}

If commands fail, verify against Makefile/package.json/composer.json or ask user to update.

Response Style

Answer first, elaborate only if needed. No sycophantic openers ("Great question!", "Absolutely!").
For yes/no or status questions, lead with the answer.
Skip preamble. Match response length to task complexity.

Workflow

1. Before coding: Read nearest AGENTS.md + check Golden Samples for the area you're touching 2. After each change: Run the smallest relevant check (lint → typecheck → single test) 3. Before committing: Run full test suite if changes affect >2 files or touch shared code 4. Before claiming done: Run verification and show output as evidence — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output in the same turn

File Map

{{FILE_MAP}}

Golden Samples (follow these patterns)

For	Reference	Key patterns

{{GOLDEN_SAMPLES}}

Utilities (check before creating new)

Need	Use	Location

{{UTILITIES_LIST}}

Heuristics (quick decisions)

When	Do

{{HEURISTICS}} | Adding dependency | Ask first - we minimize deps | | Unsure about pattern | Check Golden Samples above |

Repository Settings

{{REPO_SETTINGS}}

{{CI_RULES_SECTION}}

Key Decisions

{{KEY_DECISIONS}}

Boundaries

Always Do

Run pre-commit checks before committing
Add tests for new code paths
Use conventional commit format: type(scope): subject
Use atomic commits (one logical change per commit); preserve signatures, keep bisection useful
Show test output as evidence before claiming work is complete — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output
Before any edit, verify pwd resolves inside the intended repo worktree — not .bare/, not ~/.claude/skills/…, not ~/.claude/plugins/cache/… (those are read-only caches that get clobbered on update)
For upstream dependency fixes: run full test suite, not just affected tests
Force-push only with --force-with-lease

Ask First

Adding new dependencies
Modifying CI/CD configuration
Changing public API signatures
Running full e2e test suites
Repo-wide refactoring or rewrites
Operations that touch >3 repos (produce a dry-run plan first)

Never Do

Commit secrets, credentials, or sensitive data
Modify vendor/, node_modules/, or generated files
Push directly to main/master branch — open a PR
Merge a PR before all review threads are resolved
Squash commits during merge or rebase unless the user explicitly asked
Edit installed skill/plugin cache paths (~/.claude/skills/, ~/.claude/plugins/cache/, **/.bare/**) — always the source worktree
Reply to review comments with bare "Addressed" or "Fixed" — cite the resolving commit SHA
Delete migration files or schema changes
Use secrets: inherit in reusable GitHub Actions workflows (pass secrets explicitly)

Contributing (for AI agents)

Comprehension: Understand the problem before submitting code. Read the linked issue, understand why the change is needed, not just what to change.
Context: Every PR must explain the trade-offs considered and link to the issue it addresses. Disclose AI assistance if the project requires it.
Continuity: Respond to review feedback. Drive-by PRs without follow-up will be closed.

{{MODULE_BOUNDARIES}}

Codebase State

{{CODEBASE_STATE}}

Terminology

Term	Means

Scoped AGENTS.md (MUST read when working in these directories)

{{SCOPE_INDEX}}

Agents: When you read or edit files in a listed directory, you must load its AGENTS.md first. It contains directory-specific conventions that override this root file.

When instructions conflict

The nearest AGENTS.md wins. Explicit user prompts override files. {{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}

AGENTS.md

Precedence: The closest AGENTS.md to changed files wins. Root holds global defaults only.

Project Overview

{{PROJECT_DESCRIPTION}}

Tech Stack: {{LANGUAGE}} {{VERSION}}, {{BUILD_TOOL}}, {{FRAMEWORK}} Type: {{PROJECT_TYPE}}

Response Style

Answer first, elaborate only if needed. No sycophantic openers ("Great question!", "Absolutely!").
Lead with the answer for yes/no or status questions. Skip preamble.
Match response length to task complexity.

Global Rules

Keep PRs small (~≤300 net LOC)
Conventional Commits: type(scope): subject
Atomic commits (one logical change per commit) — never squash unless explicitly asked

Boundaries

Always Do

Run pre-commit checks before committing
Add tests for new code paths
Use conventional commit format: type(scope): subject
Keep dependencies updated
Validate all user inputs
Show test output as evidence before claiming work is complete — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output in the same turn
Before any edit, verify pwd resolves inside the intended repo worktree — not .bare/, not ~/.claude/skills/…, not ~/.claude/plugins/cache/… (those are read-only caches that get clobbered on update)
For upstream dependency fixes: run full test suite, not just affected tests
Force-push only with --force-with-lease

Ask First

Adding new dependencies
Modifying CI/CD configuration
Changing public API signatures
Running full e2e test suites
Repo-wide refactoring or rewrites
Modifying security-sensitive code
Changing database schemas
Any operation that touches >3 repos — produce a dry-run plan first

Never Do

Commit secrets, credentials, API keys, or PII
Modify vendor/, node_modules/, or generated files
Push directly to main/master branch — open a PR
Merge a PR before all review threads are resolved
Squash commits during merge/rebase unless the user explicitly asked
Edit installed skill/plugin cache paths (~/.claude/skills/, ~/.claude/plugins/cache/, **/.bare/**)
Reply to review comments with bare "Addressed" or "Fixed" — cite the resolving commit SHA
Delete migration files or schema changes
Disable security features or linting rules
Hardcode environment-specific values
Use secrets: inherit in reusable GitHub Actions workflows (pass secrets explicitly)

{{MODULE_BOUNDARIES}}

Development Workflow

1. Create feature branch: git checkout -b feature/description 2. Make changes with tests 3. Run pre-commit checks (see below) 4. Commit with conventional format 5. Push and create PR 6. Address review feedback 7. Merge when approved

Agent Work Loop

Pre-commit Checks

Source: {{COMMAND_SOURCE}} — CI-sourced commands are most reliable

Always run before committing:

Typecheck: {{TYPECHECK_CMD}}
Lint: {{LINT_CMD}}
Format: {{FORMAT_CMD}}
Tests: {{TEST_CMD}}
Build: {{BUILD_CMD}}

Code Quality Standards

{{QUALITY_STANDARDS}}

{{CI_RULES_SECTION}}

Security & Safety

Never commit secrets, credentials, or PII
Validate all user inputs
Use parameterized queries for database access
Keep dependencies updated

Testing Requirements

Write tests for new features
Maintain {{TEST_COVERAGE}}% minimum coverage
Run fast tests locally: {{TEST_FAST_CMD}}
Run full suite in CI: {{TEST_FULL_CMD}}

Key Decisions

{{KEY_DECISIONS}}

Scoped AGENTS.md (MUST read when working in these directories)

{{SCOPE_INDEX}}

Agents: When you read or edit files in a listed directory, you must load its AGENTS.md first. It contains directory-specific conventions that override this root file.

When Instructions Conflict

Nearest AGENTS.md wins. User prompts override files. {{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}

Code Examples

Good Pattern

Avoid

Documentation

Architecture: {{ARCHITECTURE_DOC}}
API docs: {{API_DOC}}
Contributing: {{CONTRIBUTING_DOC}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{GO_VERSION_LINE}} {{GO_TOOLS_LINE}} {{ENV_VARS_LINE}}

Build & tests

{{VET_LINE}} {{FORMAT_LINE}} {{LINT_LINE}} {{GOVULNCHECK_LINE}} {{TEST_LINE}} {{TEST_RACE_LINE}} {{TEST_SINGLE_LINE}} {{FUZZ_LINE}} {{BUILD_LINE}}

Code style & conventions

Follow Go 1.{{GO_MINOR_VERSION}} idioms
Use standard library over external deps when possible
Errors: wrap with fmt.Errorf("context: %w", err), lowercase no punctuation
Naming: camelCase for private, PascalCase for exported; ID/URL/HTTP not Id/Url/Http
Struct tags: use canonical form (json, yaml, etc.)
Comments: complete sentences ending with period
Package docs: first sentence summarizes purpose
Prefer any over interface{}; use generics [T any] where appropriate
Run go fix ./... after Go version upgrades to apply modernizers

Security & safety

Validate all inputs from external sources
Use context.Context for cancellation and timeouts
Avoid goroutine leaks: always ensure termination paths
Sensitive data: never log or include in errors
SQL: use parameterized queries only
File paths: validate and sanitize user-provided paths

Quality gates

Run these checks before completing any review:

golangci-lint run --timeout 5m    # Linting (golangci-lint v2)
go vet ./...                       # Static analysis
govulncheck ./...                  # Vulnerability scan
go test -race ./...                # Race detection

PR/commit checklist

[ ] govulncheck ./... reports no vulnerabilities
[ ] No goroutine leaks (ensure termination paths)
[ ] Error messages are descriptive and wrapped with %w
[ ] Public APIs have godoc comments
[ ] context.Context passed and respected in all I/O paths

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

Key patterns:

Context handling: always pass and respect context.Context
Interfaces: define where used, not where implemented

When stuck

Check Go documentation: https://pkg.go.dev
Review existing patterns in this codebase
Check root AGENTS.md for project-wide conventions
Run go doc <package> for standard library help

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{FRAMEWORK_LINE}} {{PHP_EXTENSIONS_LINE}} {{ENV_VARS_LINE}}

Build & tests

{{TYPECHECK_LINE}} {{FORMAT_LINE}} {{LINT_LINE}} {{TEST_LINE}} {{BUILD_LINE}}

Code style & conventions

Follow PSR-12 coding standard
Use strict types: declare(strict_types=1);
Type hints: always use for parameters and return types
Naming: camelCase for methods, PascalCase for classes
Visibility: always declare (public, protected, private)
PHPDoc: required for public APIs, include @param and @return

{{FRAMEWORK_CONVENTIONS}}

Security & safety

Validate and sanitize all user inputs
Use prepared statements for database queries
Escape output in templates
Never use dynamic code execution functions
Sensitive data: never log or expose in errors
CSRF protection: enable for all forms
XSS protection: escape all user-generated content

PR/commit checklist

[ ] No deprecated functions used
[ ] Public methods have PHPDoc
[ ] Security: inputs validated, outputs escaped

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check PHP documentation: https://www.php.net

Review existing patterns in this codebase
Check root AGENTS.md for project-wide conventions

Skill Reference

For PHP 8.x modernization, type safety, and PHPStan compliance:

Invoke skill: php-modernization

For Symfony projects, use the dedicated symfony.md scoped template instead of this generic PHP template.

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PYTHON_VERSION_LINE}} {{PACKAGE_MANAGER_LINE}} {{VENV_LINE}} {{ENV_VARS_LINE}}

Build & tests

{{TYPECHECK_LINE}} {{FORMAT_LINE}} {{LINT_LINE}} {{TEST_LINE}} {{BUILD_LINE}}

Code style & conventions

Follow PEP 8 style guide
Use type hints for all function signatures
Naming: snake_case for functions/variables, PascalCase for classes
Docstrings: Google style, required for public APIs
Imports: group by stdlib, third-party, local (use isort)
Modern Python: prefer | over Union, list over List

{{FRAMEWORK_CONVENTIONS}}

Security & safety

Validate and sanitize all user inputs
Use parameterized queries for database access
Never use dynamic code execution with untrusted data
Sensitive data: never log or expose in errors
File paths: validate and use pathlib for path operations
Subprocess: use list args, avoid shell=True with user input

PR/commit checklist

[ ] Public functions have docstrings

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check Python documentation: https://docs.python.org
Review existing patterns in this codebase
Check root AGENTS.md for project-wide conventions
Use python -m pydoc <module> for stdlib help

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{NODE_VERSION_LINE}} {{PACKAGE_MANAGER_LINE}} {{RUNTIME_LINE}} {{ENV_VARS_LINE}}

Build & tests

{{TYPECHECK_LINE}} {{FORMAT_LINE}} {{LINT_LINE}} {{TEST_LINE}} {{BUILD_LINE}} {{DEV_LINE}}

Code style & conventions

Use TypeScript strict mode (strict: true in tsconfig)
No any without explicit justification comment
Prefer interface over type for object shapes
Naming: camelCase for functions/vars, PascalCase for classes/types
Async/await over raw Promises
Prefer const over let, never use var
Destructure objects and arrays when appropriate

{{FRAMEWORK_CONVENTIONS}}

Security & safety

Validate all user inputs (use zod or similar)
Parameterized queries only (no string concatenation)
Never use dynamic code execution with user data
Sensitive data: never log or expose in errors
Environment: use dotenv, never hardcode secrets
CORS: configure explicitly, no wildcard in production
Rate limiting: implement for public endpoints

PR/commit checklist

[ ] No any types without justification
[ ] API endpoints have validation
[ ] Error responses don't leak internals

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check Node.js docs: https://nodejs.org/docs
TypeScript handbook: https://www.typescriptlang.org/docs
Review existing patterns in this codebase
Check root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{PLUGIN_JSON_LINE}} {{SKILLS_LINE}} {{INSTALL_LINE}}

Directory structure

.claude-plugin/
  plugin.json          → Plugin manifest (name, version, skills)
skills/
  <skill-name>/
    SKILL.md           → Skill definition and instructions
    assets/            → Templates, reference docs
    scripts/           → Shell scripts for automation
    references/        → Examples, golden samples

Build & tests

{{LINT_LINE}} {{TEST_LINE}} {{VALIDATE_LINE}}

Code style & conventions

SKILL.md: Clear, actionable instructions for AI agents
Shell scripts: Follow ShellCheck recommendations
Templates: Use {{PLACEHOLDER}} syntax for variables
Keep skills focused on one domain/task
Include checkpoints for verification
Provide golden samples for pattern demonstration

Skill design principles

Actionable: Tell agents WHAT to do, not just WHAT things are
Verifiable: Include checkpoints agents can run to verify work
Scoped: One skill = one domain (don't mix concerns)
Referenced: Point to golden samples, not generic examples
Minimal: Include only what agents need; avoid documentation bloat

Security & safety

Never include secrets or credentials in skills
Validate all user inputs in scripts
Use placeholder values in examples: your-api-key, example.com
Review generated content for sensitive information

PR/commit checklist

[ ] SKILL.md instructions are clear and actionable
[ ] Templates use whole-line placeholders (not inline)
[ ] Golden samples exist for key patterns
[ ] Checkpoints are verifiable
[ ] plugin.json version updated if releasing

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing skills for patterns
Review Claude Code documentation
Test skills with claude --skill <name>
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{SETUP_INSTRUCTIONS}} {{CLI_FRAMEWORK_LINE}} {{BUILD_OUTPUT_LINE}}

Build & tests

{{BUILD_LINE}} {{RUN_LINE}} {{TEST_LINE}} {{LINT_LINE}}

Code style & conventions

Provide --help for all commands and subcommands
Use --version to display version information
Exit codes: 0 = success, 1 = general error, 2 = usage error
Output: structured (JSON) for scripts, human-readable for interactive
Errors: write to stderr, not stdout
Progress: show for long-running operations
Interactive prompts: support non-interactive mode with flags

Security & safety

Validate all file paths and prevent directory traversal
Never execute user-provided code without explicit confirmation
Sensitive data: never log or display in plain text
Config files: validate schema and permissions
Network operations: timeout and retry with backoff

PR/commit checklist

[ ] --help text is clear and accurate
[ ] --version displays correct version
[ ] Exit codes are correct
[ ] Errors go to stderr
[ ] Long operations show progress
[ ] Works in non-interactive mode
[ ] Tests cover main workflows

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing commands for patterns
Test with --help to ensure clarity
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Pipeline configuration

{{PIPELINE_COUNT_LINE}} {{TASKS_LINE}}

Directory structure

ci/
  pipeline.yml          → Main pipeline definition
  pipeline-*.yml        → Additional pipelines (optional)
  tasks/
    build.yml           → Task definitions
    test.yml
    deploy.yml
  scripts/
    build.sh            → Task scripts
    test.sh

Pipeline conventions

Resources first: Define all resources at top of pipeline
Jobs reference resources: Use get: and put: for resource I/O
Tasks are reusable: Define tasks in separate files under ci/tasks/
Params over hardcoding: Use ((params)) for configuration
YAML anchors: Use anchors for repeated configuration

Naming conventions

Type	Convention	Example
Resource	kebab-case	`source-code`, `docker-image`
Job	kebab-case with verb	`build-app`, `deploy-staging`
Task	kebab-case	`run-tests`, `push-image`
Param	snake_case	`docker_repo`, `deploy_env`

Common patterns

Basic pipeline structure

resources:
  - name: source-code
    type: git
    source:
      uri: ((git_uri))
      branch: main

  - name: app-image
    type: registry-image
    source:
      repository: ((docker_repo))

jobs:
  - name: build-and-test
    plan:
      - get: source-code
        trigger: true
      - task: run-tests
        file: source-code/ci/tasks/test.yml
      - task: build-image
        privileged: true
        config:
          platform: linux
          image_resource:
            type: registry-image
            source: {repository: concourse/oci-build-task}
          inputs:
            - name: source-code
          outputs:
            - name: image
          run:
            path: build
      - put: app-image
        params:
          image: image/image.tar

Task definition (ci/tasks/test.yml)

platform: linux

image_resource:
  type: registry-image
  source:
    repository: node
    tag: "20"

inputs:
  - name: source-code

run:
  path: /bin/sh
  args:
    - -c
    - |
      cd source-code
      npm ci
      npm test

Multi-environment deployment

jobs:
  - name: deploy-staging
    plan:
      - get: source-code
        passed: [build-and-test]
        trigger: true
      - task: deploy
        file: source-code/ci/tasks/deploy.yml
        params:
          ENVIRONMENT: staging

  - name: deploy-production
    plan:
      - get: source-code
        passed: [deploy-staging]
      - task: deploy
        file: source-code/ci/tasks/deploy.yml
        params:
          ENVIRONMENT: production

Using across step for parallel deploys

- across:
    - var: region
      values: [us-east-1, eu-west-1, ap-southeast-1]
  task: deploy-region
  file: ci/tasks/deploy.yml
  params:
    REGION: ((.:region))

Security & safety

Store secrets in Vault or CredHub, never in pipeline YAML
Use ((params)) syntax for all sensitive values
Privileged containers only for image building (oci-build-task)
Pin resource versions for reproducibility
Use webhook tokens with secrets for triggers
Review fly set-pipeline changes before applying

PR/commit checklist

[ ] Pipeline validates: fly validate-pipeline -c pipeline.yml
[ ] Resources have appropriate check_every intervals
[ ] Tasks are defined in separate files (not inline)
[ ] Secrets use ((param)) syntax, not hardcoded
[ ] Jobs have appropriate passed: constraints
[ ] Triggers are on correct resources only

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Concourse docs: https://concourse-ci.org/docs.html
Resource types: https://resource-types.concourse-ci.org/
Pipeline examples: https://concourse-ci.org/examples.html
Validate locally: fly validate-pipeline -c pipeline.yml
Check existing pipelines in this repo for patterns

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

DDEV local development environment configuration. Use the `typo3-ddev` skill for setup and multi-version testing.

Key Files

File	Purpose
`config.yaml`	Main DDEV configuration
`docker-compose.*.yaml`	Custom service overrides
`commands/host/`	Host-side custom commands
`commands/web/`	Container-side custom commands
`.env`	Environment variables

Common Commands

Task	Command
Start	`ddev start`
Stop	`ddev stop`
SSH into container	`ddev ssh`
Run composer	`ddev composer ...`
Database export	`ddev export-db > dump.sql.gz`
Database import	`ddev import-db < dump.sql.gz`
View logs	`ddev logs`
Restart	`ddev restart`

Key Patterns

Use ddev composer instead of local composer
Custom commands in .ddev/commands/ for project-specific tasks
Override services with docker-compose.*.yaml files
Use ddev describe to see URLs and credentials
Multi-version testing: change php_version in config.yaml

Configuration Style

Keep config.yaml minimal, use overrides for complexity
Document custom commands with ## Description: header
Use #ddev-generated comment for files DDEV manages
Pin addon versions for reproducibility

PR Checklist

[ ] ddev start works after changes
[ ] Custom commands have descriptions
[ ] No hardcoded paths or credentials
[ ] Works on macOS, Linux, and Windows (WSL2)

Skill Reference

For DDEV setup, TYPO3 multi-version testing, and custom commands:

Invoke skill: typo3-ddev

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{DOCKER_VERSION_LINE}} {{COMPOSE_VERSION_LINE}} {{REGISTRY_LINE}}

Directory structure

docker/                      # or deploy/, .docker/, infrastructure/
  Dockerfile                 → Main application image
  Dockerfile.dev             → Development image (optional)
  docker-compose.yml         → Local development stack
  docker-compose.prod.yml    → Production overrides
  .dockerignore              → Build context exclusions
  entrypoint.sh              → Container entrypoint script
  healthcheck.sh             → Health check script

Build & run

Task	Command
Build image	`docker build -t app .`
Run container	`docker run -p 8080:80 app`
Start stack	`docker compose up -d`
View logs	`docker compose logs -f`
Stop stack	`docker compose down`
Rebuild	`docker compose up -d --build`

Dockerfile conventions

Multi-stage builds: Separate build and runtime stages
Non-root user: Run as non-root user in production
Layer caching: Order instructions from least to most frequently changing
Specific versions: Pin base image versions (e.g., node:20-alpine, not node:latest)
COPY over ADD: Prefer COPY unless extracting archives
.dockerignore: Exclude unnecessary files from build context

Naming conventions

Type	Convention	Example
Dockerfile	`Dockerfile` or `Dockerfile.<variant>`	`Dockerfile.dev`
Compose file	`docker-compose.yml` or `compose.yml`	`docker-compose.prod.yml`
Image tag	`<registry>/<name>:<version>`	`ghcr.io/org/app:1.2.3`
Service name	lowercase with hyphens	`web-app`, `postgres-db`

Common patterns

Multi-stage build

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runtime stage
FROM node:20-alpine AS runtime
WORKDIR /app
RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

Health check

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

Compose with profiles

services:
  app:
    build: .
    profiles: ["dev", "prod"]
  debug:
    build:
      context: .
      dockerfile: Dockerfile.dev
    profiles: ["dev"]

Security & safety

No secrets in images: Use runtime environment variables or secret mounts
Non-root execution: Always use USER directive in production
Minimal base images: Prefer Alpine or distroless images
Scan images: Use docker scout, trivy, or similar tools
Pin versions: Avoid latest tags for reproducibility
Read-only filesystem: Use --read-only when possible

PR/commit checklist

[ ] Dockerfile builds successfully
[ ] Image runs without errors
[ ] Non-root user configured for production
[ ] .dockerignore excludes sensitive/unnecessary files
[ ] Health check configured
[ ] No secrets or credentials in image layers
[ ] Base image version pinned
[ ] Multi-stage build used where appropriate

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Docker docs: https://docs.docker.com
Dockerfile best practices: https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
Compose specification: https://docs.docker.com/compose/compose-file/
Check existing Dockerfiles in this repo for patterns
Review root AGENTS.md for project-wide conventions

Skill Reference

For Dockerfile best practices, multi-stage builds, and compose patterns:

Invoke skill: docker-development

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

Documentation may use a static site generator (check for config files)
Preview locally before committing major changes
Check for broken links and formatting issues

Building docs

Preview: check for npm run docs, make docs, or similar
Build: check for documentation build commands in root
Serve locally to verify rendering

Documentation structure

README.md - Entry point, project overview
getting-started/ - Installation and quick start guides
guides/ - How-to guides and tutorials
reference/ - API documentation, configuration reference
architecture/ - Design documents, ADRs
contributing/ - Contribution guidelines

Code style & conventions

Use clear, concise language
Include code examples for technical concepts
Keep line length reasonable (~80-120 chars for readability)
Use consistent heading hierarchy (H1 for page title, H2 for sections)
Add alt text to images for accessibility
Use relative links for internal references
Keep code examples up-to-date with actual codebase

Markdown best practices

Use fenced code blocks with language hints: ```python
Use tables for structured data comparison
Use admonitions for warnings/notes (if supported)
Keep paragraphs focused on one idea
Use bullet points for lists, numbered lists for sequences

Security & safety

Never include secrets, API keys, or credentials in examples
Use placeholder values: your-api-key, example.com
Review screenshots for sensitive information
Avoid documenting security vulnerabilities in detail

PR/commit checklist

[ ] Documentation matches current code behavior
[ ] Code examples are tested and work
[ ] Links are valid (no 404s)
[ ] Images have alt text
[ ] Spelling and grammar checked
[ ] Formatting renders correctly

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing documentation for patterns
Review the style guide (if one exists)
Preview changes locally before committing
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

Examples should be self-contained and runnable
Each example may have its own dependencies (check local README)
Examples should work with the current version of the main package

Running examples

Check each example's README for specific instructions
Most examples: cd example-name && follow README
Some examples may require environment setup

Example organization

One directory per example/use case
Each example has its own README explaining what it demonstrates
Keep examples focused on one concept or pattern
Name examples descriptively: basic-usage/, advanced-config/, integration-with-x/

Code style & conventions

Examples should be educational and well-commented
Use realistic but simplified scenarios
Show best practices, not shortcuts
Include error handling to demonstrate proper patterns
Keep examples minimal - only what's needed to demonstrate the concept
Avoid complex setups that distract from the main point

Documentation requirements

Each example needs a README with:
What this example demonstrates
Prerequisites and setup steps
How to run the example
Expected output or behavior
Links to relevant documentation

Security & safety

Never include real API keys or credentials
Use environment variables for sensitive config: export API_KEY=your-key
Use sandbox/test environments when interacting with external services
Include warnings for examples that make real API calls

PR/commit checklist

[ ] Example runs successfully
[ ] README is complete and accurate
[ ] No hardcoded credentials
[ ] Code demonstrates best practices
[ ] Comments explain non-obvious parts
[ ] Example works with current package version

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check similar examples for patterns
Ensure the example is self-contained
Test the example from scratch (fresh environment)
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{NODE_VERSION_LINE}} {{FRAMEWORK_LINE}} {{PACKAGE_MANAGER_LINE}} {{ENV_VARS_LINE}}

Build & tests

{{INSTALL_LINE}} {{TYPECHECK_LINE}} {{LINT_LINE}} {{FORMAT_LINE}} {{TEST_LINE}} {{BUILD_LINE}} {{DEV_LINE}}

Code style & conventions

Naming: camelCase for variables/functions, PascalCase for components
File naming: ComponentName.tsx, utilityName.ts
Imports: group and sort (external, internal, types)

{{CSS_APPROACH_LINE}} {{FRAMEWORK_CONVENTIONS}}

Security & safety

Sanitize user inputs before rendering
Raw HTML rendering only with sanitized content (use DOMPurify)
Validate environment variables at build time
Never expose secrets in client-side code
Use HTTPS for all API calls
Implement CSP headers
WCAG 2.2 AA accessibility compliance

PR/commit checklist

[ ] Accessibility: keyboard navigation works, ARIA labels present
[ ] Responsive: tested on mobile, tablet, desktop
[ ] Performance: no unnecessary re-renders

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Review TypeScript handbook: https://www.typescriptlang.org/docs/
Check root AGENTS.md for project-wide conventions
Review existing components for patterns

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Workflow files

{{WORKFLOW_COUNT_LINE}} {{REUSABLE_WORKFLOWS_LINE}}

Directory structure

.github/
  workflows/
    ci.yml              → Main CI workflow (lint, test, build)
    release.yml         → Release/deploy workflow
    dependabot.yml      → Dependency updates
  actions/
    <action-name>/      → Composite actions (reusable)
      action.yml
  CODEOWNERS            → Code ownership rules
  pull_request_template.md

Workflow conventions

Pin action versions with full SHA, not tags (uses: actions/checkout@abc123...)
Minimal permissions: Use permissions: block, never use permissions: write-all
Reusable workflows: Extract common patterns to .github/workflows/reusable-*.yml
Job dependencies: Use needs: to express dependencies
Caching: Use actions/cache for dependencies (npm, composer, go)

Naming conventions

Type	Convention	Example
Workflow file	`<purpose>.yml`	`ci.yml`, `release.yml`
Workflow name	Title Case	`CI Pipeline`, `Release`
Job ID	kebab-case	`build-and-test`, `deploy-staging`
Step name	Sentence case	`Install dependencies`
Secret	SCREAMING_SNAKE	`DEPLOY_TOKEN`, `NPM_TOKEN`

Common patterns

Basic CI workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Matrix builds

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: ['18', '20', '22']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: ${{ matrix.node }}

Reusable workflow

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}

Conditional deployment

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: [test, build]
    environment: production
    steps:
      - name: Deploy
        run: ./deploy.sh

Security & safety

NEVER expose secrets in logs: use ::add-mask:: for dynamic secrets
Pin actions to full commit SHA, not mutable tags
Minimal permissions: Start with contents: read, add only what's needed
Environment protection: Use environments with required reviewers for deploys
Secret scanning: Enable in repository settings
Dependency review: Use actions/dependency-review-action for PRs
OIDC: Prefer OIDC over long-lived secrets for cloud providers

PR/commit checklist

[ ] Actions pinned to full SHA (not tags)
[ ] Permissions block uses minimal required permissions
[ ] Secrets are not exposed in logs
[ ] Workflow syntax valid: actionlint or GitHub UI validation
[ ] Matrix strategy covers required versions/platforms
[ ] Caching configured for dependencies

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

GitHub Actions docs: https://docs.github.com/en/actions
Workflow syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
Action marketplace: https://github.com/marketplace?type=actions
Use act for local testing: https://github.com/nektos/act
Check existing workflows in this repo for patterns

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Pipeline configuration

{{JOB_COUNT_LINE}} {{INCLUDES_LINE}}

File structure

.gitlab-ci.yml          → Main pipeline configuration
.gitlab/
  ci/
    templates/          → Reusable job templates
    jobs/               → Job definitions (included)
  CODEOWNERS            → Code ownership

Pipeline conventions

Use stages to organize job execution order
Extend templates with extends: for DRY jobs
Use rules: instead of only:/except: (deprecated)
Cache dependencies between jobs
Use artifacts to pass files between stages

Naming conventions

Type	Convention	Example
Stage	lowercase	`build`, `test`, `deploy`
Job	kebab-case with stage prefix	`build-app`, `test-unit`
Variable	SCREAMING_SNAKE	`DEPLOY_ENV`, `CI_TOKEN`
Template	`.template-name` (dot prefix)	`.build-template`

Common patterns

Basic pipeline structure

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "20"

build-app:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test-unit:
  stage: test
  needs: [build-app]
  script:
    - npm test

Reusable job template

.deploy-template:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - ./deploy.sh $ENVIRONMENT

deploy-staging:
  extends: .deploy-template
  variables:
    ENVIRONMENT: staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy-production:
  extends: .deploy-template
  variables:
    ENVIRONMENT: production
  rules:
    - if: $CI_COMMIT_TAG
  when: manual

Matrix builds (parallel)

test:
  stage: test
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        OS: ["alpine", "debian"]
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

Include external files

include:
  - local: '.gitlab/ci/templates.yml'
  - project: 'company/ci-templates'
    ref: main
    file: '/templates/docker.yml'
  - template: Security/SAST.gitlab-ci.yml

Security & safety

Use protected variables for secrets (Settings > CI/CD > Variables)
Mask variables to prevent log exposure
Use protected branches for deployment jobs
Enable SAST/DAST scanning templates
Pin Docker images to specific versions/digests
Use rules: with $CI_COMMIT_TAG for release workflows
Review merge request pipelines before merging

PR/commit checklist

[ ] Pipeline syntax valid: use CI/CD > Editor > Validate
[ ] Jobs use appropriate stages
[ ] Sensitive variables are masked and protected
[ ] Artifacts have reasonable expire_in values
[ ] Cache keys are appropriate for the content
[ ] Rules conditions are correct (not using deprecated only/except)

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

GitLab CI docs: https://docs.gitlab.com/ee/ci/
CI/CD YAML syntax: https://docs.gitlab.com/ee/ci/yaml/
Predefined variables: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
Use the pipeline editor for validation: CI/CD > Editor
Check existing .gitlab-ci.yml patterns in this repo

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{ORO_VERSION_LINE}} {{DATABASE_LINE}} {{SETUP_COMMANDS}}

Directory structure

src/
  Acme/
    Bundle/
      MyBundle/
        AcmeMyBundle.php        → Bundle class
        Controller/             → Web and API controllers
        Entity/                 → Doctrine entities
        Form/                   → Form types
        Resources/
          config/
            oro/                → Oro-specific configs
              workflows.yml     → Workflow definitions
              datagrids.yml     → Datagrid definitions
              navigation.yml    → Menu/navigation
              acl.yml           → ACL definitions
            services.yml        → Service definitions
          views/                → Twig templates
          translations/         → Translation files
        Migrations/
          Schema/               → Doctrine schema migrations
          Data/                 → Data migrations (fixtures)
        Api/                    → API processors
        Async/                  → Message queue processors
        EventListener/          → Event subscribers/listeners
        ImportExport/           → Import/export processors

Build & tests

{{COMMANDS_TABLE}}

Code style & conventions

PSR-12 coding standard
Strict types: declare(strict_types=1);
Symfony best practices + Oro conventions
Use Oro's config-based approach (YAML over annotations when possible)
Dependency injection via services.yml
Entities extend Oro base classes when applicable

Naming conventions

Type	Convention	Example
Bundle	`VendorNameBundle`	`AcmeCrmBundle`
Entity	`PascalCase`	`CustomerOrder`
Datagrid	`vendor-entity-grid`	`acme-orders-grid`
Workflow	`vendor_entity_flow`	`acme_order_flow`
API resource	`vendor_entity`	`acme_orders`

Oro-specific patterns

Datagrids (datagrids.yml)

datagrids:
    acme-orders-grid:
        source:
            type: orm
            query:
                select:
                    - o.id
                    - o.orderNumber
                from:
                    - { table: Acme\Bundle\OrderBundle\Entity\Order, alias: o }
        columns:
            orderNumber:
                label: acme.order.order_number.label
        sorters:
            columns:
                orderNumber:
                    data_name: o.orderNumber
        filters:
            columns:
                orderNumber:
                    type: string
                    data_name: o.orderNumber

Workflows (workflows.yml)

workflows:
    acme_order_flow:
        entity: Acme\Bundle\OrderBundle\Entity\Order
        entity_attribute: order
        start_step: draft
        steps:
            draft:
                allowed_transitions:
                    - submit
            submitted:
                allowed_transitions:
                    - approve
                    - reject
        transitions:
            submit:
                step_to: submitted

ACL (acl.yml)

acl:
    acme_order_view:
        type: entity
        class: Acme\Bundle\OrderBundle\Entity\Order
        permission: VIEW
    acme_order_edit:
        type: entity
        class: Acme\Bundle\OrderBundle\Entity\Order
        permission: EDIT

Security & safety

ACL: Define permissions in acl.yml, check with isGranted()
CSRF: Oro handles automatically for forms
API auth: OAuth2 or WSSE authentication
Input validation: Use Symfony validators + Oro constraints
Sensitive data: Use Oro's ConfigManager for encrypted values
SQL: Always use Doctrine ORM/DBAL, never raw queries

PR/commit checklist

[ ] Schema migrations are reversible
[ ] Data migrations use DependentFixtureInterface for ordering
[ ] Datagrids tested in browser
[ ] Workflows tested end-to-end
[ ] ACL permissions defined for new entities
[ ] Translation keys added to messages.en.yml
[ ] API resources documented with NelmioApiDocBundle annotations

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

Message Queue patterns

// Async processor
class ProcessOrderProcessor implements MessageProcessorInterface
{
    public function process(MessageInterface $message, SessionInterface $session): string
    {
        $data = JSON::decode($message->getBody());
        // Process order...
        return self::ACK;
    }
}

// Producer usage
$this->messageProducer->send(ProcessOrderTopic::NAME, ['orderId' => $order->getId()]);

When stuck

Oro Documentation: https://doc.oroinc.com
Backend Architecture: https://doc.oroinc.com/backend/architecture/
Datagrids: https://doc.oroinc.com/backend/entities/data-grids/
Workflows: https://doc.oroinc.com/backend/entities/workflows/
API: https://doc.oroinc.com/api/
Check existing bundles in vendor/oro/ for patterns
Review root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{ORO_VERSION_LINE}} {{DATABASE_LINE}} {{MESSAGE_QUEUE_LINE}}

Directory structure

bin/
  console              → Symfony console entry point
config/
  bundles.php          → Registered bundles
  config.yml           → Main configuration
  config_dev.yml       → Development overrides
  config_prod.yml      → Production settings
  parameters.yml       → Environment parameters
  security.yml         → Security configuration
  oro/
    bundles.yml        → Oro bundle registration
public/
  index.php            → Web entry point
  bundles/             → Bundle assets
src/
  Acme/                → Custom bundles
    Bundle/
      MyBundle/
var/
  cache/               → Cache files
  logs/                → Log files
  attachment/          → File attachments
migrations/
  Schema/              → Doctrine schema migrations
  Data/                → Data migrations/fixtures

Build & tests

{{COMMANDS_TABLE}}

Code style & conventions

PSR-12 coding standard
Strict types: declare(strict_types=1);
Symfony best practices + Oro conventions
Bundle-based architecture for all custom code
Use Oro's config-based approach (YAML over annotations)
Dependency injection via services.yml

Project structure rules

Type	Location	Purpose
Custom bundles	`src/Vendor/Bundle/`	All custom functionality
Overrides	`config/`	Configuration overrides
Migrations	`migrations/`	Application-level migrations
Assets	`public/bundles/`	Compiled/copied assets

Oro CLI commands

# Installation & setup
bin/console oro:install                    # Full installation
bin/console oro:platform:update           # Update after code changes

# Cache management
bin/console cache:clear                   # Clear cache
bin/console oro:assets:install            # Install bundle assets
bin/console oro:localization:dump         # Dump translations

# Database & migrations
bin/console doctrine:migrations:migrate   # Run migrations
bin/console oro:migration:data:load       # Load data migrations

# Message queue (required for Oro)
bin/console oro:message-queue:consume     # Process queue
bin/console oro:cron                      # Run cron jobs

# Development
bin/console debug:router                  # List routes
bin/console debug:container               # Debug DI container

Message Queue

Oro requires a running message queue consumer for:

Email sending
Search indexing
Workflow processing
Data import/export

Development: Run bin/console oro:message-queue:consume in terminal Production: Use supervisor or systemd to keep consumer running

Security & safety

Parameters: Use parameters.yml for sensitive values (not in git)
OAuth2: Configure for API authentication
ACL: Define permissions in bundle acl.yml
HTTPS: Enforce in production
Secrets: Use Symfony secrets for production credentials
Session: Configure secure session handling

Deployment

# Production deployment steps
composer install --no-dev --optimize-autoloader
bin/console cache:clear --env=prod
bin/console oro:platform:update --env=prod --force
bin/console oro:assets:install --env=prod
bin/console assetic:dump --env=prod

Always run oro:platform:update after code changes
Restart message queue consumer after deployment
Warm up cache before switching to new release

PR/commit checklist

[ ] Bundle registered in config/oro/bundles.yml
[ ] Migrations reversible and tested
[ ] Assets installed: bin/console oro:assets:install
[ ] Message queue tested with consumer running
[ ] ACL permissions defined for new entities

When stuck

Oro Documentation: https://doc.oroinc.com
Installation: https://doc.oroinc.com/backend/setup/
Backend Architecture: https://doc.oroinc.com/backend/architecture/
CLI Commands: bin/console list oro
Check vendor/oro/ bundles for reference implementations
Review root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{PYTHON_VERSION_LINE}} {{PACKAGE_MANAGER_LINE}} {{VENV_LINE}} {{ENV_VARS_LINE}}

Project configuration

All tool config lives in pyproject.toml -- no setup.cfg, setup.py, tox.ini, or scattered config files.

[project]                    # PEP 621 metadata
[build-system]               # Build backend (hatchling, setuptools, flit, pdm)
[tool.ruff]                  # Linting + formatting (replaces black, isort, flake8, pylint)
[tool.ruff.lint]             # Lint rule selection
[tool.mypy]                  # Static type checking
[tool.pytest.ini_options]    # Test configuration
[tool.coverage]              # Coverage settings

Build & tests

Command	Purpose	~Time

{{RUFF_CHECK_LINE}} {{RUFF_FORMAT_LINE}} {{MYPY_LINE}} {{PYTEST_LINE}} {{PYTEST_COV_LINE}} {{BUILD_LINE}}

Code style & conventions

Ruff (linting + formatting)

Ruff replaces black, isort, flake8, pylint, pyflakes, pycodestyle in one tool
Format: ruff format . -- black-compatible, deterministic
Lint: ruff check . --fix -- auto-fix safe rules
Config in pyproject.toml under [tool.ruff]
Common rule sets: E (pycodestyle), F (pyflakes), I (isort), UP (pyupgrade), B (bugbear)

Type hints (mypy)

All functions must have type annotations (parameters + return)
Use mypy --strict or configure strictness in pyproject.toml
Modern syntax: str | None not Optional[str], list[int] not List[int]
Use typing.TypeAlias for complex types
Use Protocol for structural subtyping (duck typing with types)

Naming conventions

Type	Convention	Example
Module	`snake_case`	`user_service.py`
Class	`PascalCase`	`UserService`
Function	`snake_case`	`get_user_by_id()`
Constant	`UPPER_SNAKE_CASE`	`MAX_RETRIES`
Type variable	`PascalCase`	`T = TypeVar("T")`
Private	`_leading_underscore`	`_internal_helper()`

Docstrings

Google style preferred (compatible with Sphinx napoleon)
Required for all public modules, classes, functions
Include Args:, Returns:, Raises: sections

Imports

Ruff handles import sorting (I rules) -- no separate isort needed
Group: stdlib, third-party, local (Ruff enforces this)
Prefer absolute imports; relative only within package internals

Testing (pytest)

Test files: tests/ directory, files named test_*.py
Test functions: test_<description>() -- no class needed for simple tests
Fixtures: prefer conftest.py for shared fixtures
Parametrize: use @pytest.mark.parametrize for data-driven tests
Markers: @pytest.mark.slow, @pytest.mark.integration for selective runs
Coverage: pytest --cov=src --cov-report=term-missing
Assert style: plain assert (pytest rewrites for detailed output)

Dependency management

uv (recommended)

uv sync                     # Install deps from uv.lock
uv add <package>            # Add dependency
uv add --dev <package>      # Add dev dependency
uv run pytest               # Run in managed venv

poetry

poetry install              # Install deps from poetry.lock
poetry add <package>        # Add dependency
poetry add --group dev <p>  # Add dev dependency
poetry run pytest           # Run in managed venv

pip (fallback)

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"     # Install with dev extras

Security & safety

Validate and sanitize all user inputs
Use parameterized queries for database access (SQLAlchemy, asyncpg)
Never use dynamic code evaluation functions with untrusted data
Sensitive data: never log or expose in errors
File paths: validate and use pathlib.Path for all path operations
Subprocess: use list args, never shell=True with user input
Dependencies: pin versions in lockfile, audit with pip-audit or safety

PR/commit checklist

[ ] ruff check . passes (no lint errors)
[ ] ruff format --check . passes (formatting clean)
[ ] mypy . passes (no type errors)
[ ] pytest passes (all tests green)
[ ] New public functions have type hints and docstrings
[ ] No # type: ignore without explanation comment

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Python docs: https://docs.python.org
Ruff rules reference: https://docs.astral.sh/ruff/rules/
mypy cheat sheet: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
pytest docs: https://docs.pytest.org
Review existing patterns in this codebase
Check root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

Resources are typically consumed by other parts of the application
Some resources may need preprocessing or compilation
Check build scripts for resource handling

Resource types

Templates: HTML, email, or text templates
Static assets: Images, fonts, icons, stylesheets
Configuration: Default configs, schema files, fixtures
Localization: Translation files, locale data
Data files: JSON, YAML, CSV for static data

Organization conventions

Group resources by type: templates/, images/, locales/
Use consistent naming: lowercase, hyphens for spaces
Keep related resources together
Version large binary assets carefully (consider Git LFS)

Code style & conventions

Use descriptive file names: user-profile-template.html not template1.html
Keep templates simple - logic belongs in code, not templates
Use consistent indentation in structured files (JSON, YAML, XML)
Document template variables and their expected values
Optimize images before committing (compress, resize)

Template best practices

Use clear placeholder syntax: {{variable}} or ${variable}
Document all required variables in comments or README
Keep templates focused - one purpose per template
Use partials/includes for reusable components

Security & safety

Never store secrets in resource files
Validate all resource files that accept user input
Sanitize template variables to prevent injection
Review images/assets for embedded metadata (EXIF, etc.)
Use CSP-safe inline styles when applicable

PR/commit checklist

[ ] File names are descriptive and consistent
[ ] Images are optimized (compressed, correct size)
[ ] Templates have documented variables
[ ] No sensitive data in resources
[ ] Structured files are valid (JSON, YAML syntax)
[ ] Changes tested with consuming code

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check how resources are consumed in the codebase
Look for build/preprocessing scripts
Review existing resources for patterns
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

Plugin manifest: .claude-plugin/plugin.json (name, version, skills array, author URL)
Skills: skills/<name>/SKILL.md — one per domain
Licensing: Split MIT (code) + CC-BY-SA-4.0 (content) — entity: Netresearch DTT GmbH
CI: Reusable workflows from netresearch/skill-repo-skill (validate.yml, auto-merge-deps.yml)

Directory structure

.claude-plugin/
  plugin.json            → Plugin manifest (name, version, skills, author)
skills/
  <skill-name>/
    SKILL.md             → Skill definition (max 500 words)
    assets/              → Templates, scoped AGENTS.md templates
    scripts/             → Shell scripts (bash 4.3+, ShellCheck clean)
    references/          → Extended docs, golden samples, examples
    checkpoints/         → Checkpoint definitions (YAML)
LICENSE-MIT              → MIT license for code
LICENSE-CC-BY-SA-4.0     → CC-BY-SA-4.0 for content
.github/
  workflows/
    lint.yml             → Calls skill-repo-skill validate.yml@main
    auto-merge-deps.yml  → Calls skill-repo-skill auto-merge-deps.yml@main

Build & tests

{{LINT_LINE}} {{VALIDATE_LINE}} {{SHELLCHECK_LINE}}

Code style & conventions

SKILL.md rules

Max 500 words — keep it focused and actionable
Use references/ for extended documentation (no word limit)
Front matter: name, description, license, compatibility, metadata, allowed-tools
Instructions are FOR AGENTS, not humans — be prescriptive, not descriptive

plugin.json rules

version: semver, bump on release
author.url: must be a valid URL
skills[].name must match directory name under skills/

Shell scripts

Shebang: #!/usr/bin/env bash
set -euo pipefail at top
ShellCheck clean (no suppressions without justification)
Use "$var" quoting everywhere

Templates

Use {{PLACEHOLDER}} syntax — whole-line placeholders only
Wrap auto-generated sections in  /

Licensing

Entity name: Netresearch DTT GmbH (never "Netresearch GmbH & Co. KG")
Code files (.sh, .py, .json): MIT
Content files (.md, .yaml): CC-BY-SA-4.0

Checkpoints (verification)

checkpoints.yaml defines verifiable steps agents can run
Each checkpoint: name, command, expected (exit code or output pattern)
Agents run checkpoints after completing tasks to verify correctness
Keep checkpoints fast (<10s each)

Security & safety

Never include secrets or credentials in skills
Validate all user inputs in scripts
Use placeholder values in examples: your-api-key, example.com
Review generated content for sensitive information
Shell scripts: quote all variables, avoid eval with user input

CI/CD

Validate workflow: Runs on PR — markdown lint, YAML lint, ShellCheck, plugin.json schema
Auto-merge deps: Merges Renovate/Dependabot PRs after CI passes
Config files (.markdownlint-cli2.jsonc, .yamllint.yml) are per-repo; validate.yml provides defaults if missing
Releasing: bump plugin.json version, create signed tag, push — release workflow handles the rest

PR/commit checklist

[ ] SKILL.md is under 500 words
[ ] plugin.json version bumped if releasing
[ ] Shell scripts pass ShellCheck
[ ] Templates use whole-line {{PLACEHOLDER}} syntax
[ ] Golden samples exist for key patterns
[ ] Checkpoints are verifiable (fast, deterministic)
[ ] Entity name is "Netresearch DTT GmbH" in all license files
[ ] No trailing blank lines in YAML files

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing skill repos for patterns (e.g., agent-rules-skill, go-development-skill)
Review skill-repo-skill for CI workflow definitions
Test skills locally with claude --skill <name>
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{SYMFONY_VERSION_LINE}} {{DATABASE_LINE}}

Directory structure

src/
  Controller/           → HTTP controllers
  Entity/               → Doctrine entities
  Repository/           → Doctrine repositories
  Service/              → Business logic services
  Form/                 → Form types
  EventSubscriber/      → Event subscribers
  Command/              → Console commands
  Security/             → Voters, authenticators
config/
  packages/             → Bundle configuration
  routes/               → Routing configuration
  services.yaml         → Service definitions
templates/              → Twig templates
migrations/             → Doctrine migrations
tests/                  → PHPUnit tests

Build & tests

{{COMMANDS_TABLE}}

Code style & conventions

PSR-12 coding standard with strict types
Use constructor injection for dependencies
Controllers are thin: delegate to services
Use attributes for routing, validation, ORM mapping
Services are autowired by default

Naming conventions

Type	Convention	Example
Controller	`<Entity>Controller`	`UserController`
Service	`<Domain>Service` or `<Domain>Manager`	`UserService`
Repository	`<Entity>Repository`	`UserRepository`
Form	`<Entity>Type`	`UserType`
Event	`<Entity><Action>Event`	`UserCreatedEvent`
Command	`app:<domain>:<action>`	`app:user:import`

Symfony-specific patterns

Controller with form handling

#[Route('/user/new', name: 'user_new')]
public function new(Request $request, EntityManagerInterface $em): Response
{
    $user = new User();
    $form = $this->createForm(UserType::class, $user);
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $em->persist($user);
        $em->flush();
        return $this->redirectToRoute('user_show', ['id' => $user->getId()]);
    }

    return $this->render('user/new.html.twig', ['form' => $form]);
}

Service with dependency injection

final class UserService
{
    public function __construct(
        private readonly UserRepository $userRepository,
        private readonly EventDispatcherInterface $dispatcher,
    ) {}

    public function createUser(string $email): User
    {
        $user = new User($email);
        $this->userRepository->save($user, flush: true);
        $this->dispatcher->dispatch(new UserCreatedEvent($user));
        return $user;
    }
}

Custom console command

#[AsCommand(name: 'app:user:import', description: 'Import users from CSV')]
final class ImportUsersCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Implementation
        return Command::SUCCESS;
    }
}

Security & safety

Use Voters for authorization logic, not inline checks
Store secrets in .env.local (never commit)
Use CSRF tokens for all forms
Enable security headers via NelmioSecurityBundle
Validate all input with Symfony Validator constraints
Use parameterized queries (Doctrine handles this)

PR/commit checklist

[ ] Migrations are reversible (down() method works)
[ ] New routes have proper security annotations
[ ] Services are properly autowired (no manual config needed)
[ ] Cache cleared: bin/console cache:clear

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Symfony docs: https://symfony.com/doc/current/
Best practices: https://symfony.com/doc/current/best_practices.html
Check existing controllers/services for patterns
Run bin/console debug:router to inspect routes
Run bin/console debug:container to inspect services
Review root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

Install dev dependencies before running tests
Some tests may require additional setup (see individual test files)
Use the project's test framework consistently

Running tests

{{TEST_LINE}} {{TEST_SINGLE_LINE}} {{TEST_COVERAGE_LINE}} {{TEST_WATCH_LINE}}

Test organization

Group tests by feature or module
Name test files to match source files (e.g., foo_test.go, foo.test.ts)
Use descriptive test names that explain the expected behavior
Keep fixtures and mocks in dedicated directories

Code style & conventions

One assertion per test when possible
Use descriptive test names: test_should_return_error_when_input_is_empty
Avoid testing implementation details; focus on behavior
Keep tests independent - no shared mutable state
Mock external dependencies (network, filesystem, time)
Use table-driven tests for multiple similar cases

Security & safety

Never commit real credentials in test fixtures
Use environment variables or mock services for sensitive data
Sanitize any test data that might contain PII
Ensure test databases are isolated from production

PR/commit checklist

[ ] All tests pass locally
[ ] New functionality has corresponding tests
[ ] Test names describe expected behavior
[ ] No hardcoded credentials or sensitive data
[ ] Mocks are appropriate and maintainable
[ ] Coverage hasn't decreased significantly

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

When stuck

Check existing tests for patterns
Review test framework documentation
Ensure test isolation (no shared state)
Check root AGENTS.md for project conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

TYPO3 extension documentation (RST format for docs.typo3.org). Use the `typo3-docs` skill for comprehensive guidance.

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Structure (docs.typo3.org standard)

Documentation/
├── Index.rst              # Main entry point (required)
├── Settings.cfg           # Sphinx configuration (required)
├── Includes.rst.txt       # Shared includes
├── Introduction/
│   └── Index.rst
├── Installation/
│   └── Index.rst
├── Configuration/
│   └── Index.rst
├── Editor/
│   └── Index.rst
├── Developer/
│   └── Index.rst
└── Images/
    └── *.png, *.svg

Rendering Docs

Task	Command
Render locally	`docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest`
Preview	Open `Documentation-GENERATED-temp/Index.html`
Clean	`rm -rf Documentation-GENERATED-temp/`

Key Patterns (TYPO3-specific)

Use RST format, not Markdown
Use TYPO3 directives: confval, versionadded, deprecated, t3-field-list-table
Include code with .. code-block:: php or .. literalinclude::
Cross-reference with :ref: and proper labels
Screenshots MANDATORY for backend modules, config screens, UI workflows
Store in Documentation/Images/, use .. figure:: with :zoom: lightbox

Screenshots (MANDATORY for UI)

.. figure:: /Images/Configuration/ExtensionSettings.png
   :alt: Extension configuration showing API settings
   :zoom: lightbox
   :class: with-border with-shadow

   Configure the extension in Admin Tools > Settings

Format: PNG only
Zoom modes: lightbox (default), gallery (tutorials), inline (diagrams)
Always include :alt: text

RST Style

Headings: = for H1, - for H2, ~ for H3, ^ for H4
Line length: ~80 characters for readability
One sentence per line (for better diffs)
Use .. note::, .. warning::, .. tip:: for admonitions
Tables: use .. t3-field-list-table:: or grid tables

PR Checklist

[ ] RST syntax valid (renders without errors)
[ ] All internal links resolve
[ ] Images have :alt: text and :zoom: lightbox
[ ] Screenshots exist for all backend/config/UI sections
[ ] Code examples are tested
[ ] Follows docs.typo3.org structure

Skill Reference

For RST syntax, TYPO3 directives, screenshots, and docs.typo3.org deployment:

Invoke skill: typo3-docs

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{TYPO3_VERSION_LINE}} {{DEV_SETUP_LINE}} {{REQUIRED_EXTENSIONS_LINE}}

Directory structure

Classes/           → PHP classes (PSR-4: Vendor\ExtKey\)
  Controller/      → Backend/Frontend controllers
  Domain/          → Model, Repository, Validator
  Service/         → Business logic services
  ViewHelpers/     → Fluid ViewHelpers
Configuration/     → TYPO3 configuration
  TCA/             → Table Configuration Array
  TypoScript/      → TypoScript setup/constants
  FlexForms/       → FlexForm XML definitions
  Backend/         → Backend module config
Resources/
  Private/         → Templates, Partials, Layouts (Fluid)
  Public/          → CSS, JS, Icons
Tests/
  Unit/            → PHPUnit unit tests
  Functional/      → Functional tests with DB
Documentation/     → RST documentation for docs.typo3.org

Build & tests

{{COMMANDS_TABLE}} {{DDEV_ALTERNATIVE}}

Code style & conventions

PSR-12 + TYPO3 CGL (Coding Guidelines)
Strict types: declare(strict_types=1); in all PHP files
Namespace: {{VENDOR}}\{{EXT_KEY}}\ (PSR-4 from Classes/)
Use dependency injection via Services.yaml, not GeneralUtility::makeInstance()
Extbase conventions for domain models and repositories
Fluid templates: use <f: and custom ViewHelpers
TCA: use TYPO3 API, not raw SQL for schema
Never use $GLOBALS['TYPO3_DB'] (deprecated since v8)

Naming conventions

Type	Convention	Example
Extension key	`lowercase_underscore`	`my_extension`
Composer name	`vendor/ext-key`	`vendor/my-extension`
Namespace	`Vendor\ExtKey\`	`Vendor\MyExtension\`
Controller	`*Controller`	`BlogController`
Repository	`*Repository`	`PostRepository`
ViewHelper	`*ViewHelper`	`FormatDateViewHelper`

Security & safety

Always use QueryBuilder or Extbase repositories - never raw SQL
Escape output in Fluid: {variable} auto-escapes, use <f:format.raw> only when safe
CSRF protection: use \TYPO3\CMS\Core\FormProtection\FormProtectionFactory for forms
Access checks: use $GLOBALS['BE_USER']->check() for backend
File handling: use FAL (File Abstraction Layer), never direct file paths
Never trust user input: validate via Extbase validators or custom validation

PR/commit checklist

[ ] ext_emconf.php version updated if releasing
[ ] TCA changes have matching SQL in ext_tables.sql
[ ] Documentation updated in Documentation/
[ ] No deprecated TYPO3 APIs (run Extension Scanner)

{{TYPO3_VERSION_CHECKLIST_LINE}}

Patterns to Follow

Prefer looking at real code in this repo over generic examples.

See Golden Samples section above for files that demonstrate correct patterns.

TYPO3 upgrade considerations

Run Extension Scanner before upgrading: Backend → Upgrade → Scan Extension Files
Use Rector for automated migrations: vendor/bin/rector process
Check deprecation log in TYPO3 backend
Review TYPO3 Changelog for breaking changes

When stuck

TYPO3 Documentation: https://docs.typo3.org
TCA Reference: https://docs.typo3.org/m/typo3/reference-tca/main/en-us/
Core API: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
Extbase Guide: https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/
Check existing patterns in EXT:core or EXT:backend
Review root AGENTS.md for project-wide conventions

Skill Reference

For TYPO3 extension standards, TER compliance, and conformance checks:

Invoke skill: typo3-conformance

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

{{SCOPE_DESCRIPTION}}

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Setup & environment

{{INSTALL_LINE}} {{PHP_VERSION_LINE}} {{TYPO3_VERSION_LINE}} {{DEV_SETUP_LINE}} {{COMPOSER_MODE_LINE}}

Directory structure

public/                 → Web root (DocumentRoot)
  typo3/               → TYPO3 backend assets
  typo3conf/           → Configuration (legacy, avoid)
  fileadmin/           → User uploads (FAL)
  index.php            → Entry point
config/                → Project configuration
  sites/               → Site configurations (YAML)
    <site>/
      config.yaml      → Site routing, languages
  system/              → System-wide settings
    settings.php       → LocalConfiguration equivalent
    additional.php     → AdditionalConfiguration
var/                   → Runtime data (cache, logs)
  cache/               → Cache files
  log/                 → Log files
  session/             → Session data
vendor/                → Composer dependencies
packages/              → Local extensions (recommended)
  my_extension/        → Custom extension

Build & tests

{{COMMANDS_TABLE}}

Code style & conventions

PSR-12 + TYPO3 CGL (Coding Guidelines)
Strict types: declare(strict_types=1); in all PHP files
Use Composer Mode for all extensions
Site configuration in config/sites/ (not database)
Use environment variables for sensitive config
Avoid typo3conf/ - use config/ and packages/ instead

Project vs Extension code

Type	Location	Purpose
Local extensions	`packages/`	Custom functionality
Site config	`config/sites/`	Routing, languages
System config	`config/system/`	TYPO3 settings
Templates	Extension `Resources/`	Fluid templates

Extension management

Composer-only: All extensions via composer require
Local packages: Use packages/ with path repository
Never use Extension Manager for production
Lock extension versions in composer.lock

Adding local extension

{
    "repositories": [
        {"type": "path", "url": "packages/*"}
    ],
    "require": {
        "vendor/my-extension": "@dev"
    }
}

Security & safety

Environment variables: Use for DB credentials, encryption key
Restrict backend access: Use .htaccess or server config
Disable install tool: Remove ENABLE_INSTALL_TOOL after setup
File permissions: Strict permissions on var/, config/
HTTPS only: Enforce in site configuration
Update regularly: Security updates for core and extensions

Deployment

Use composer install --no-dev --optimize-autoloader
Clear caches: vendor/bin/typo3 cache:flush
Warmup caches: vendor/bin/typo3 cache:warmup
Run database migrations: vendor/bin/typo3 database:updateschema
Never deploy var/cache/ or var/session/

PR/commit checklist

[ ] Site configuration is valid YAML
[ ] No hardcoded credentials or paths
[ ] Extensions installed via Composer only
[ ] Database schema changes documented

{{TYPO3_VERSION_CHECKLIST_LINE}}

When stuck

TYPO3 Documentation: https://docs.typo3.org
Installation Guide: https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/
Site Configuration: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/
Console Commands: vendor/bin/typo3 list
Review root AGENTS.md for project-wide conventions

House Rules (project-specific)

{{HOUSE_RULES}}

AGENTS.md — {{SCOPE_NAME}}

Overview

TYPO3 extension test suite. Use the `typo3-testing` skill for comprehensive guidance.

Key Files

{{SCOPE_FILE_MAP}}

Golden Samples (follow these patterns)

{{SCOPE_GOLDEN_SAMPLES}}

Test Structure (TYPO3 standard)

Tests/
├── Unit/                    # Fast, isolated unit tests
│   └── Domain/
│       └── Model/
├── Functional/              # Tests with database/TYPO3 context
│   ├── Fixtures/            # Test data, SQL, XML
│   └── Domain/
│       └── Repository/
└── Build/                   # CI configuration

Running Tests

Type	Command
Unit tests	`composer ci:test:php:unit` or `Build/Scripts/runTests.sh -s unit`
Functional tests	`composer ci:test:php:functional` or `Build/Scripts/runTests.sh -s functional`
Single file	`Build/Scripts/runTests.sh -s unit -p Tests/Unit/Path/To/Test.php`
Coverage	`composer ci:test:php:unit -- --coverage-html .Build/coverage`

Key Patterns (TYPO3-specific)

Unit tests extend \TYPO3\TestingFramework\Core\Unit\UnitTestCase
Functional tests extend \TYPO3\TestingFramework\Core\Functional\FunctionalTestCase
Use $this->importCSVDataSet() for functional test fixtures
Define $testExtensionsToLoad for extension dependencies
Use GeneralUtility::makeInstance() for DI-aware instantiation in functional tests

Code Style

Test class name matches source: MyClass → MyClassTest
Test methods: test prefix or @test annotation
One assertion concept per test
Use data providers for multiple similar cases
Mock external services, never real HTTP calls

PR Checklist

[ ] All tests pass: composer ci:test:php:unit && composer ci:test:php:functional
[ ] New functionality has tests
[ ] Fixtures are minimal and focused
[ ] No hardcoded credentials or paths
[ ] Coverage hasn't decreased

Skill Reference

For comprehensive TYPO3 testing guidance including fixtures, mocking, CI setup, and runTests.sh:

Invoke skill: typo3-testing

House Rules (project-specific)

{{HOUSE_RULES}}

AI Agent Contribution Guidelines

Guidelines for AI agents contributing to projects with AGENTS.md files. Based on the "3 Cs" framework from GitHub's open source mentorship research (March 2026).

The 3 Cs

Comprehension

Before submitting any code change, the agent must demonstrate understanding of the problem:

Read the linked issue fully — understand the why, not just the symptoms
Check if the issue is already assigned to someone
Understand the trade-offs involved (performance vs readability, backwards compatibility, etc.)
If the issue is unclear, ask for clarification rather than guessing

Red flag: Submitting code that "looks right" without understanding why the current behavior exists.

Context

Every PR must provide enough context for efficient review:

Link to the issue being addressed (Fixes #NNN)
Explain the approach taken and alternatives considered
If AI tools assisted the contribution, disclose this if the project requires it
Include test evidence (test output, before/after screenshots)
Note any side effects or breaking changes

Red flag: A PR with only "Fixes the bug" as description.

Continuity

Contributions are not fire-and-forget:

Respond to review comments within a reasonable timeframe
Be willing to iterate on feedback
Don't submit to many projects simultaneously without capacity to follow up
If you can't continue, say so — maintainers prefer honesty over silence

Red flag: Opening a PR and never responding to review feedback.

Detection Patterns

The agent-rules skill detects contribution requirements from:

Source	What's extracted
`CONTRIBUTING.md`	Issue-first requirements, AI disclosure policy
PR templates (`.github/pull_request_template.md`)	Required fields (issue links, test plans)
Branch protection rules	Linked issue requirements
`AGENTS.md`	Agent-specific boundaries and conventions

What AGENTS.md Signals

Having an AGENTS.md file signals:

The project is AI-contribution-ready
Agents should follow the conventions documented in the file
The closest AGENTS.md to the files being changed takes precedence
Explicit user instructions override AGENTS.md

References

Rethinking open source mentorship in the AI era (GitHub Blog, March 2026)
agents.md convention — the standard our skill implements

# Server Configuration
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/api

# Logging
LOG_LEVEL=info

# Security
JWT_SECRET=change-me-in-production
CORS_ORIGIN=http://localhost:3000

{
  "name": "express-api-ts",
  "version": "1.0.0",
  "description": "Express.js REST API with TypeScript",
  "main": "dist/index.js",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint src/",
    "format": "prettier --write src/",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "express": "^4.21.0",
    "zod": "^3.23.0",
    "winston": "^3.14.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/node": "^22.0.0",
    "eslint": "^9.12.0",
    "prettier": "^3.3.0",
    "tsx": "^4.19.0",
    "typescript": "^5.6.0",
    "vitest": "^3.2.6"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

import type { Request, Response, NextFunction } from 'express';
import { logger } from '../utils/logger.js';

export function requestLogger(req: Request, res: Response, next: NextFunction): void {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    logger.info('Request completed', {
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration: `${duration}ms`,
    });
  });

  next();
}

Related skills

Find SkillsSo their agent can intelligently recommend and install the right modular skills from the open ecosystem when they ask how to do something.3M27.9k

Lark Skill MakerRapidly create custom skills for Lark (Feishu) that can be invoked by their AI agents and automation workflows.513k

Skill CreatorGenerate, test, and iterate on new reusable agent skills directly inside their Claude or Cursor workflow.337k166k

BrainstormingTurn vague product ideas into clear, approved designs and specifications through guided collaborative dialogue before writing any code.307k265k

Writing Great SkillsCreate high-quality, reusable agent skills that other developers can discover and install from the Skillselion catalog.290k200k

Find SkillsInstantly surface the best relevant agent skills, MCP servers, and workflows across multiple registries before starting any new project.226k12

How it compares

Choose agent-rules when standardizing AGENTS.md and verification scripts for Claude Code; use generic documentation skills when agents do not need repo-specific file maps.

FAQ

Which scripts does agent-rules include?

agent-rules bundles bash scripts including verify-commands.sh, generate-file-map.sh, analyze-git-history.sh, and detect-utilities.sh under skills/agent-rules/scripts. They regenerate AGENTS.md maps and validate repo conventions.

What does agent-rules write into AGENTS.md?

agent-rules maintains managed AGENTS-GENERATED overview and filemap sections in AGENTS.md with a fixed section order. Developers edit content while scripts keep file maps and verification aligned to the repository.

Is Agent Rules safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Skill Developmentintegrationsdocs