Agent Rules

---
name: agent-rules
description: "Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents."
license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0"
compatibility: "Requires bash 4.3+, jq 1.5+, git 2.0+."
metadata:
  author: Netresearch DTT GmbH
  version: "3.11.0"
  repository: https://github.com/netresearch/agent-rules-skill
allowed-tools: Bash(git:*) Bash(jq:*) Bash(grep:*) Bash(find:*) Bash(bash:*) Read Glob Grep
---

# AGENTS.md Generator Skill

Generate and maintain AGENTS.md files following the [agents.md convention](https://agents.md/). AGENTS.md is FOR AGENTS, not humans.

## When to Use

- Creating or updating AGENTS.md for new/existing projects
- Standardizing agent documentation across repositories
- Checking if AGENTS.md files are current with recent code changes
- Onboarding AI agents to an unfamiliar codebase

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/generate-agents.sh PATH` | Generate AGENTS.md files |
| `scripts/validate-structure.sh PATH` | Validate structure compliance |
| `scripts/check-freshness.sh PATH` | Check if files are outdated |
| `scripts/verify-content.sh PATH` | Verify documented files/commands match codebase |
| `scripts/verify-commands.sh PATH` | Verify documented commands execute |
| `scripts/detect-project.sh PATH` | Detect language, version, build tools |
| `scripts/detect-scopes.sh PATH` | Identify directories needing scoped files |
| `scripts/extract-commands.sh PATH` | Extract commands from build configs |
| `scripts/extract-ci-rules.sh PATH` | Extract CI quality gates and version matrix |
| `scripts/extract-architecture-rules.sh PATH` | Extract module boundaries |
| `scripts/extract-adrs.sh PATH` | Extract architectural decision records |
| `scripts/extract-github-rulesets.sh PATH` | Extract GitHub rulesets and merge rules |

See `references/scripts-guide.md` for full options.

## Workflow

1. **Detect**: `detect-project.sh` + `detect-scopes.sh` to identify stacks and subsystems
2. **Extract**: `extract-commands.sh`, `extract-ci-rules.sh`, etc. to gather facts
3. **Generate**: `generate-agents.sh` with `--style=thin` (default) or `--verbose`
4. **Verify**: `verify-content.sh` + `verify-commands.sh` -- MANDATORY before done

Use `--update` to preserve human-curated content outside `<!-- GENERATED -->` markers.

## Core Principles

- **Structured over Prose** -- tables parse faster than paragraphs
- **Never Fabricate** -- only document what exists; verify every command and path
- **Pointer Principle** -- point to files, don't duplicate content
- **Auto Symlinks** -- CLAUDE.md/GEMINI.md symlinks by default (see [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md))

## References

| File | Contents |
|------|----------|
| [`verification-guide.md`](references/verification-guide.md) | Verification steps, design principles |
| [`scripts-guide.md`](references/scripts-guide.md) | Script options, validation checklist |
| [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md) | 16-agent compatibility matrix |
| [`output-structure.md`](references/output-structure.md) | Root/scoped sections |
| [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework detection and setup |
| [`examples/`](references/examples/) | Complete examples |
| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehension, Context, Continuity) |
| [`directory-coverage.md`](references/directory-coverage.md) | Full coverage rationale for scoped AGENTS.md files |

## Templates

Root: `assets/root-thin.md` (default), `root-verbose.md`. Scoped: `assets/scoped/` -- `backend-go.md`, `backend-php.md`, `python-modern.md`, `typo3.md`, `symfony.md`, `skill-repo.md`, `cli.md`, `frontend-typescript.md`, `oro.md`.

## Supported Projects

Go, PHP (Composer/Laravel/Symfony/TYPO3/Oro), TypeScript (React/Next/Vue/Node), Python (pip/poetry/ruff/mypy), Skill repos, Hybrid (multi-stack with auto-scoping).

## See Also

- [`agent-harness-skill`](https://github.com/netresearch/agent-harness-skill) — broader agent-readiness harness (CI verification, enforcement). Invokes this skill when AGENTS.md is missing.
- [`skill-repo-skill`](https://github.com/netresearch/skill-repo-skill) — skill-repo structure (plugin.json, split licensing, release workflows).