dirien/yet-another-agent-harness / .claude/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/analysis.md
View on GitHub# AGENTS.md Analysis Across 6 Netresearch Projects
> **Reference:** This analysis aligns with the [official agents.md specification](https://agents.md/) and [GitHub best practices from 2,500+ repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/).
## Executive Summary
**Total AGENTS.md Files Found**: 21 files across 6 projects
**Patterns Observed**:
1. **Root files are thin** (26-348 lines) with precedence rules and global defaults
2. **Scoped files are focused** on specific subsystems (backend, frontend, CLI, etc.)
3. **Managed header** present in newer files: `<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->`
4. **Consistent structure** following the 9-section schema from your prompt
## File Distribution
| Project | Root | Scoped Files | Total Lines (root) |
|---------|------|--------------|-------------------|
| t3x-rte_ckeditor_image | ✅ | Classes/, Documentation/, Resources/, Tests/ | 348 |
| coding_agent_cli_toolset | ✅ | scripts/ | 308 |
| ldap-selfservice-password-changer | ✅ | internal/, internal/web/ | 282 |
| ldap-manager | ✅ | cmd/, internal/, internal/web/, scripts/ | 228 |
| raybeam | ✅ | cmd/, internal/ | 209 |
| simple-ldap-go | ✅ | docs/, examples/, testutil/ | 26 ⭐ **Perfect thin root** |
## Key Findings
### 1. **simple-ldap-go** is the Best Example ⭐
**Root file** (26 lines):
- Minimal global rules
- Clear precedence statement
- Index of scoped files
- No duplication with scoped content
```markdown
## Global rules
- Keep diffs small; add tests for new code paths
- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites
## Minimal pre-commit checks
- Typecheck (all packages): `go build -v ./...`
- Lint/format (file scope): `gofmt -w <file.go>`
- Unit tests (fast): `go test -v -race -short -timeout=10s ./...`
## Index of scoped AGENTS.md
- `./examples/AGENTS.md` — Example applications
- `./testutil/AGENTS.md` — Testing utilities
- `./docs/AGENTS.md` — Documentation
```
### 2. Scoped Files Follow 9-Section Schema
**Example: simple-ldap-go/examples/AGENTS.md**:
1. ✅ Overview
2. ✅ Setup & environment
3. ✅ Build & tests (file-scoped)
4. ✅ Code style & conventions
5. ✅ Security & safety
6. ✅ PR/commit checklist
7. ✅ Good vs. bad examples
8. ✅ When stuck
9. ⚠️ House Rules (rarely used, only when overriding)
### 3. Managed Header Usage
**Present in** (newer projects):
- simple-ldap-go (all files)
- ldap-selfservice-password-changer (all files)
- raybeam (some files)
**Missing in** (older projects):
- t3x-rte_ckeditor_image
- coding_agent_cli_toolset
**Format**:
```html
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
```
### 4. Precedence Rules - Consistent Pattern
All root files establish precedence clearly:
**Pattern 1** (verbose):
> "This file explains repo-wide conventions and where to find scoped rules. **Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only."
**Pattern 2** (concise):
> "**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults."
**Pattern 3** (index-focused):
> "## Precedence & Scoped Files
> Nearest AGENTS.md wins. Use this root for defaults only."
### 5. Docker-First vs Native-First
**Docker-first projects** (ldap-selfservice-password-changer, ldap-manager):
```markdown
### Setup
**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev)
# Docker (recommended)
docker compose --profile dev up
# Native development
pnpm install
```
**Native-first projects** (simple-ldap-go, t3x-rte_ckeditor_image):
```markdown
### Setup
**Prerequisites**: Go 1.24, golangci-lint
# Install
go mod download
```
### 6. Language-Specific Patterns
**Go Projects** (simple-ldap-go, ldap-manager, raybeam):
- Minimal pre-commit: `go build -v ./...`, `gofmt -w`, `go test -short`
- Go version in global rules (1.24, 1.25)
- golangci-lint for comprehensive checks
**PHP Project** (t3x-rte_ckeditor_image):
- Composer scripts for CI pipeline
- PHPStan + PHP-CS-Fixer + Rector
- Make targets preferred over composer commands
**Hybrid Projects** (ldap-selfservice-password-changer):
- Separate sections for Go backend vs TypeScript frontend
- Scoped AGENTS.md for `internal/` (Go) and `internal/web/` (TS)
- pnpm for package management (strict version)
### 7. Quick Start Patterns
**Best practice** (ldap-selfservice-password-changer):
```markdown
## Quick Navigation
- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services
- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend
```
**Alternative** (simple-ldap-go):
```markdown
## Index of scoped AGENTS.md
- `./examples/AGENTS.md` — Example applications and usage patterns
- `./testutil/AGENTS.md` — Testing utilities and container management
```
### 8. House Rules Implementation
**Global defaults** typically include:
- Commits: Conventional Commits, small PRs (~≤300 LOC)
- Type-safety: Strict types when supported
- SOLID, KISS, DRY, YAGNI principles
- SemVer for versioning
- No secrets in VCS
- Structured logging
- WCAG AA for UI projects
**Scoped overrides** (rare):
- Different test coverage targets per module
- Module-specific commit conventions
- Technology-specific style guides
### 9. Common Gaps Across Projects
❌ **Missing .envrc** in most projects (your prompt requires it)
❌ **Missing .editorconfig** in some projects
❌ **Husky + commitlint** not universally adopted
❌ **lint-staged** not implemented in older projects
❌ **CI parity section** often missing (should reference GitHub Actions)
## Recommendations for Your Skill
### Essential Features
1. **Template Selection**:
- Thin root (simple-ldap-go style) ⭐
- Verbose root (ldap-selfservice-password-changer style)
- Auto-detect based on project size
2. **Project Type Detection**:
- Go: Look for `go.mod`, detect version from `go.mod` directive
- PHP: Look for `composer.json`, detect TYPO3 from dependencies
- TypeScript: Look for `tsconfig.json`, detect strict mode
- Hybrid: Detect multiple languages, recommend scoped files
3. **Scoped File Generation**:
- **Required scopes**: backend/, frontend/, internal/
- **Optional scopes**: cmd/, scripts/, examples/, docs/, testutil/
- **Auto-create** if directory exists and has ≥5 files
4. **Content Extraction**:
- **Makefile**: Extract targets with `##` comments → Build & Test Commands
- **package.json scripts**: Extract npm/pnpm commands
- **go.mod**: Extract Go version → Prerequisites
- **composer.json scripts**: Extract PHP quality commands
- **GitHub Actions**: Extract CI checks → PR/commit checklist
5. **Managed Header**:
- Always add to new files
- Preserve in existing files
- Update timestamp on regeneration
6. **Precedence Rules**:
- Auto-add "Nearest AGENTS.md wins" statement
- Generate index of scoped files in root
- Link from root to scoped files
### Skill Structure Recommendation
```
agents-skill/
├── SKILL.md
├── README.md
├── templates/
│ ├── root-thin.md # simple-ldap-go style (recommended)
│ ├── root-verbose.md # ldap-selfservice style
│ ├── scoped-backend.md # Go/PHP backend
│ ├── scoped-frontend.md # TypeScript/JS frontend
│ ├── scoped-cli.md # CLI tools
│ ├── scoped-docs.md # Documentation
│ ├── scoped-tests.md # Testing utilities
│ └── sections/ # Modular sections
│ ├── header.md # Managed header template
│ ├── precedence.md # Precedence statement
│ ├── setup.md # Setup section
│ ├── build-commands.md # Build & test commands
│ ├── code-style.md # Code style guidelines
│ ├── security.md # Security practices
│ ├── pr-checklist.md # PR/commit checklist
│ ├── examples.md # Good vs bad examples
│ └── when-stuck.md # When stuck guidance
├── scripts/
│ ├── generate-agents.sh # Main generator
│ ├── detect-project.sh # Auto-detect project type
│ ├── extract-commands.sh # Extract from Makefile/package.json
│ └── validate-structure.sh # Validate generated files
└── references/
├── examples/ # Real-world examples
│ ├── go-library.md # simple-ldap-go
│ ├── go-web-app.md # ldap-manager
│ ├── php-typo3.md # t3x-rte_ckeditor_image
│ └── hybrid-app.md # ldap-selfservice-password-changer
└── best-practices.md # AGENTS.md writing guide
```
### Key Differentiators
✅ **Thin root by default** (not verbose like some projects)
✅ **Auto-scope detection** (create scoped files when needed)
✅ **Command extraction** (don't make user write commands manually)
✅ **Managed header** (mark files as agent-maintained)
✅ **Language-agnostic** (works with Go, PHP, TypeScript, Python, etc.)
✅ **Idempotent** (can be re-run without breaking existing structure)
## Sample Output Comparison
### Your Prompt's Expected Output
**Root AGENTS.md** (following simple-ldap-go pattern):
```markdown
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
# AGENTS.md (root)
**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
## Global rules
- Keep PRs small (~≤300 net LOC)
- Conventional Commits: type(scope): subject
- Ask before: heavy deps, full e2e, repo rewrites
- Never commit secrets or PII
## Minimal pre-commit checks
- Typecheck: [auto-detected command]
- Lint: [auto-detected command]
- Format: [auto-detected command]
- Tests: [auto-detected command]
## Index of scoped AGENTS.md
- `./internal/AGENTS.md` — Go backend services
- `./internal/web/AGENTS.md` — TypeScript frontend
## When instructions conflict
Nearest AGENTS.md wins. User prompts override files.
```
**Scoped AGENTS.md** (e.g., internal/AGENTS.md):
```markdown
<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
# AGENTS.md — Backend Services
## Overview
[Auto-generated description of internal/ directory purpose]
## Setup & environment
[Auto-detected from go.mod, .env.example]
## Build & tests (prefer file-scoped)
[Auto-extracted from Makefile, go commands]
## Code style & conventions
[Auto-detected from golangci-lint config, gofmt]
## Security & safety
[Standard Go security practices + project-specific]
## PR/commit checklist
[Auto-extracted from GitHub Actions, Makefile]
## Good vs. bad examples
[Template with placeholders to fill]
## When stuck
- Check root AGENTS.md for global rules
- Review sibling modules for 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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |