netresearch/agent-rules-skill / skills/agent-rules
agent-rules
FlaggedUse when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
references/output-structure.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Output Structure
## Root File
Root AGENTS.md (~50-80 lines) contains agent-optimized sections:
| Section | Purpose | Format |
|---------|---------|--------|
| **Commands (verified)** | Executable commands with time estimates | Table with ~Time column |
| **File Map** | Directory purposes for navigation | `dir/ -> purpose` format |
| **Golden Samples** | Canonical patterns to follow | Table: For / Reference / Key patterns |
| **Utilities List** | Existing helpers to reuse | Table: Need / Use / Location |
| **Heuristics** | Quick decision rules | Table: When / Do |
| **Boundaries** | Always/Ask/Never rules | Three-tier list |
| **Changelog** (required, AG-32) | Where changes are recorded, in which format, and which PR writes the entry (each PR or the release PR, as the last merged PRs show) | `**Changelog:**` bullet under Always Do, or a `## Changelog` section |
| **Codebase State** | Migrations, tech debt, known issues | Bullet list |
| **Terminology** | Domain-specific terms | Table: Term / Means |
| **Scope Index** | Links to scoped files | List with descriptions |
## Scoped Files
Scoped AGENTS.md files cover six core areas (per [GitHub best practices](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)):
1. **Commands** - Executable build, test, lint commands
2. **Testing** - Test conventions and execution
3. **Project Structure** - Architecture and key files
4. **Code Style** - Formatting and conventions
5. **Git Workflow** - Commit/PR guidelines
6. **Boundaries** - Always do / Ask first / Never do
Additional recommended sections:
- Overview
- Setup/Prerequisites
- Security
- Good vs Bad examples
- When stuck
- House Rules (for scoped overrides)
- **Approved learnings** — titled rules appended by `/retro` (see [feedback-memory-schema.md](feedback-memory-schema.md))
### AGENTS.md is an index, not a rule dump
When session learnings are approved (via `/retro` or similar), the rule is appended under `## Approved learnings` as a short titled block — AGENTS.md is the single project rule store, so there is no second file to keep in sync. Keep each rule to a title plus one or two sentences naming the trigger and the action; anything that needs more belongs in `docs/` with a pointer, the same as every other topic in this index. Repos that still carry a `docs/feedback/` tree from the earlier index-plus-file model keep working — see [feedback-memory-schema.md](feedback-memory-schema.md).
Place `## Approved learnings` **after `## Key Decisions` and before `## Boundaries`** in the section order, and put it **outside** any `<!-- AGENTS-GENERATED:START ... -->` markers — this section is managed by retro-skill, not by `generate-agents.sh`, so it must survive `--update` runs.
If the approved-learnings section would push AGENTS.md over the harness 150-line cap (`AH-02`), prune rules that no longer apply or move them to a scoped `AGENTS.md` next to the code they govern, rather than letting the section grow unbounded.
## When to Customize vs Auto-Generate
### Auto-Generate These Sections
These sections are factual and extractable - let scripts handle them:
| Section | Why Auto-Generate |
|---------|-------------------|
| **Commands** | Extract from Makefile/package.json - always accurate |
| **File Map** | Directory listing is objective |
| **Scope Index** | Detectable from filesystem structure |
| **Language/Framework** | Detectable from config files |
| **Test Commands** | Extract from CI config |
### Manually Curate These Sections
These sections require human judgment - preserve them during updates:
| Section | Why Manual |
|---------|------------|
| **Golden Samples** | Requires taste - which file exemplifies good patterns? |
| **Heuristics** | Decision rules come from team experience |
| **Boundaries** | Always/Ask/Never rules reflect team policy |
| **Codebase State** | Tech debt awareness requires context |
| **Terminology** | Domain knowledge is human insight |
| **Architecture Decisions** | Why choices were made isn't extractable |
### Override Best Practices
When updating existing AGENTS.md files, preserve custom content:
**1. Use `--update` flag:**
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/generate-agents.sh /path/to/project --update
```
This preserves content outside `<!-- GENERATED:START -->` / `<!-- GENERATED:END -->` markers.
**2. Place custom content outside markers:**
```markdown
<!-- GENERATED:START -->
## Commands (auto-generated)
| Command | Purpose |
|---------|---------|
| `make test` | Run tests |
<!-- GENERATED:END -->
## Custom Heuristics (preserved)
| When | Do |
|------|-----|
| Adding endpoint | Create OpenAPI spec first |
```
**3. Use scoped overrides for exceptions:**
```
project/
├── AGENTS.md # Global rules
└── legacy/
└── AGENTS.md # "Ignore linting in this directory"
```
**4. Review diffs before committing:**
```bash
# After regenerating
git diff AGENTS.md
# Ensure custom sections weren't overwritten
```
## Directory Coverage
When creating AGENTS.md files, create them in ALL key directories:
| Directory | Purpose |
|-----------|---------|
| Root | Precedence, architecture overview |
| `Classes/` or `src/` | Source code patterns |
| `Configuration/` or `config/` | Framework config |
| `Documentation/` or `docs/` | Doc standards |
| `Resources/` or `assets/` | Templates, assets |
| `Tests/` | Testing patterns |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |