B+

agentic harnessagents md

AGENTS.md Management

Create and maintain AGENTS.md documentation for simple projects, complex monorepos, deterministic discovery, scoped instruction files, low-token navigation; use when generating AGENTS.md, updating agent docs, standardizing AI-facing project guidance.

npx skills add github:pantheon-org/tekhne --skill agentic-harness--agents-md

When to Use

“Create AGENTS.md for this repo.”
“Update agent documentation for this monorepo.”
“Set up hierarchical AGENTS.md files by package.”
Repository shape or tooling changed and the existing agent guidance needs a refresh.

When Not to Use

Pure code implementation work with no documentation update.
One-off prompts where repository guidance files are unnecessary.
Questions about a single function or file that need no standing project guidance.

Principles

Keep instructions concise, concrete, and path-specific.
Prefer references and indices over duplicated prose.
Optimize for nearest-file relevance in hierarchical layouts.

Workflow

Discover repository shape and technologies. Output: simple vs hierarchical documentation strategy.
Select structure (single root file or root + sub-files). Output: file layout plan.
Generate AGENTS.md content with concrete commands and paths. Output: actionable docs with JIT indexing.
Validate command correctness and duplication boundaries. Output: clean, copy-paste-safe instruction files.
Re-check after major repo changes. Output: synchronized documentation.

Structure Decision

Simple project: one AGENTS.md when stack and patterns are uniform.
Complex monorepo: root AGENTS.md + scoped subdirectory AGENTS.md files.
Consider adding subdirectory files iteratively — start minimal, expand as complexity grows.

Minimal Template

# Project Agent Guide

## Commands
- Build: `bun run build`
- Test: `bun run test`
- Lint: `bun run lint`

## Conventions
- [describe key patterns here]

## Key Paths
- Source: `src/`
- Tests: colocated `*.test.ts`

Quick Commands

# Discovery baseline
rg --files

# Detect core config/tooling
rg -n "workspaces|nx|turbo|pnpm|yarn|packageManager|tsconfig|pytest|playwright" .

# Locate existing AGENTS files
find . -name AGENTS.md -o -name AI-DOCS.md

Anti-Patterns

NEVER assume a technology stack without discovery

WHY: incorrect assumptions produce unusable instructions.

BAD: generate React/Jest guidance without evidence.

GOOD: run discovery commands and map docs to the detected stack.

NEVER dump encyclopedic content into root AGENTS.md

WHY: oversized docs increase token cost and reduce usability.

BAD: embed full framework manuals.

GOOD: keep root concise and link to scoped files or references.

NEVER duplicate the same instructions across root and sub-files

WHY: duplication creates drift and maintenance overhead.

BAD: copy/paste identical conventions in every file.

GOOD: keep universal rules at root and package-specific rules locally.

NEVER provide unverified commands

WHY: broken commands erode trust and block contributors.

BAD: include hypothetical commands.

GOOD: include only validated copy-paste commands.

NEVER create a hierarchy for a simple, uniform project

WHY: extra files add navigation cost and drift risk when one file would do.

BAD: add a subdirectory AGENTS.md to every folder of a single-package repo.

GOOD: use one root AGENTS.md when stack and patterns are uniform.

NEVER put package-specific rules in the root file

WHY: agents read the nearest file, so misplaced rules waste tokens and mislead other packages.

BAD: list UI build flags in the root file of a monorepo.

GOOD: keep package commands in that package’s own AGENTS.md.

NEVER use generic placeholder commands or paths

WHY: placeholders cannot be copy-pasted and give the reader nothing concrete.

BAD: write <your-project>/src or “run the tests”.

GOOD: write the real path and the real command found during discovery.

NEVER front-load every sub-file at once

WHY: speculative files describe complexity that does not exist yet and go stale.

BAD: generate an AGENTS.md for every package on the first pass.

GOOD: start minimal and add scoped files iteratively as complexity grows.

NEVER leave documentation stale after major repository changes

WHY: instructions for removed tooling mislead agents and break their commands.

BAD: keep Jest commands after the project moved to another runner.

GOOD: re-run discovery, remove obsolete content, and document new scripts.

Verification

rumdl check --include "**/AGENTS.md" .

bun run lint

References

Topic	Reference
Repository discovery commands	references/discovery-commands.md
What to avoid	references/anti-patterns.md
API package template	references/api-template.md
Design-system template	references/design-system-template.md
Database package template	references/database-template.md
Testing package template	references/testing-template.md
Troubleshooting	references/troubleshooting.md

120/ 140

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Runtime validation via eval scenarios proving the skill actually changes agent behaviour. Requires evals/ directory, instructions.json, ≥3 scenarios, and ≥80% instruction coverage in summary.json.

Appropriate rigidity for the skill type: strict rules for critical/security skills, balanced steps for process skills, flexible options for tool skills. Mismatched calibration (too rigid or too loose) reduces score.

Expert-only knowledge the AI couldn't derive on its own — domain-specific patterns, production gotchas, decision frameworks, and non-obvious tool behaviour. High scores mean <5% redundancy with what the model already knows.

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Rich activation keywords and trigger scenarios in the description so the skill fires when needed. Best descriptions read like an exhaustive list of the tasks and concepts that should invoke this skill.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

176 lines · 7 references

118/ 140

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

122 lines · 7 references

133/ 140

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

121 lines · 7 references

133/ 140

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

121 lines · 7 references

Anti-Patterns for AGENTS.md

Detailed explanations of what NEVER to include in AGENTS.md files and why.

Critical Anti-Patterns with Reasoning

NEVER Include Welcome Language

Examples: “Welcome to…”, “This document explains…”, “You should…”

Why this is problematic:

Token waste: AI systems don’t need social pleasantries or introductions
Processing overhead: Every token counts in context window management
Scanning inefficiency: AI systems scan for actionable information, not narrative flow
Redundant information: The fact that it’s documentation is already clear from context

NEVER Use Placeholder Examples

Examples: <your-file>, [replace-with-actual-path], TODO: add example

Why this is problematic:

Pattern recognition failure: AI systems learn patterns from concrete examples, not abstractions
Implementation uncertainty: Placeholders force AI to guess real file structures
Context switching: AI must mentally map placeholders to actual project structure
Reduced utility: Placeholder examples provide no actionable guidance

NEVER Write Long Prose Paragraphs

Examples: Multi-sentence explanations, narrative descriptions, background context

Why this is problematic:

Scan vs read: AI systems scan for actionable items, not reading comprehension
Information density: Bullets and code blocks are faster to parse than prose
Action extraction: AI needs to extract “what to do” from narrative text
Token efficiency: Headers + bullets convey same information in fewer tokens

NEVER Duplicate Content from Skills

Examples: Copying testing patterns, development workflows, code standards

Why this is problematic:

Redundant loading: Same information loaded multiple times wastes context
Maintenance burden: Updates required in multiple locations
Version conflicts: Outdated copies create inconsistency
Skill undermining: Reduces value of specialized skill system

NEVER Include Obvious Instructions

Examples: “run tests”, “write clean code”, “handle errors properly”

Why this is problematic:

Baseline knowledge: AI systems already know standard development practices
Signal dilution: Obvious content reduces the signal-to-noise ratio
Expert knowledge displacement: Token space better used for project-specific insights
Credibility reduction: Stating obvious things reduces trust in non-obvious guidance

NEVER Explain “Why” Unless Non-Obvious

Examples: “We use React because it’s popular”, “Tests are important for quality”

Why this is problematic:

Action focus: AI systems need “what to do”, not “why it matters”
Assumed knowledge: AI systems understand standard technology rationales
Implementation priority: Limited tokens should focus on “how”, not “why”
Expert knowledge: Only include “why” for non-obvious trade-offs and decisions

NEVER Include Framework Tutorials

Examples: “How to write a React component”, “Express.js routing basics”

Why this is problematic:

Baseline competency: AI systems already know framework fundamentals
Documentation duplication: Official framework docs are authoritative source
Project-specific focus: AGENTS.md should cover project patterns, not framework basics
Maintenance overhead: Framework tutorials become outdated quickly

Good vs Bad Examples

❌ Bad Example

# Welcome to Our Project

This document explains how to work with our codebase. You should read this carefully before making changes.

## About React Components
React components are reusable pieces of UI. In our project, we organize them in folders like this:
- `src/components/<ComponentName>/index.tsx` - Your component goes here
- `src/components/<ComponentName>/styles.css` - Your styles go here

Remember to write tests for your components! Testing is important for code quality.

✅ Good Example

# Project Name

## Component Organization
- Components: `src/components/Button/index.tsx`, `src/components/Modal/index.tsx`
- Styles: Colocated `.css` files
- Tests: `Button/Button.test.tsx`
- Example: Copy pattern from `src/components/Button/`

Usage in Main SKILL.md

Reference this file with explicit loading trigger:

**MANDATORY - READ ENTIRE FILE**: Before writing any AGENTS.md content, 
load `references/anti-patterns.md` to understand what to avoid.

**Do NOT load** other reference files for anti-pattern review.

API / Backend Service Template

Use this template when documenting API or backend service packages.

MANDATORY: Before using this template, analyze the current project to identify:

Backend framework - Run: grep -r "express\|fastify\|koa\|nest\|hapi\|django\|flask\|gin\|fiber" package.json pyproject.toml go.mod | head -3
Route organization - Run: find . -name "*route*" -o -name "*endpoint*" -o -name "*handler*" | grep -v node_modules | head -5
Middleware location - Run: find . -name "*middleware*" -o -name "*auth*" | grep -v node_modules | head -5
Validation approach - Run: grep -r "zod\|joi\|yup\|ajv\|pydantic" package.json pyproject.toml | head -3
Error handling - Run: find . -name "*error*" -o -name "*exception*" | grep -E "\.(js|ts|py|go)$" | head -5

Adaptive Template Structure

## API Patterns
- Framework: [DETECTED_FRAMEWORK] ([Express/Fastify/Django/etc])
- Routes: `[DETECTED_ROUTES_PATH]/**/*` OR "Route organization not found"
- Auth: `[DETECTED_AUTH_PATH]` OR "Auth middleware not detected"
- Validation: [DETECTED_VALIDATION_LIB] schemas in `[SCHEMA_PATH]/**`
- Errors: `[ERROR_CLASS_NAME]` from `[ERROR_FILE_PATH]`
- Example route: `[ACTUAL_ROUTE_EXAMPLE_PATH]`

Detection Instructions

Framework-Specific Patterns

Node.js/Express: Look for app.js, server.js, route files Node.js/Fastify: Look for Fastify plugins, route definitions Node.js/NestJS: Look for controllers, decorators, modules Python/Django: Look for urls.py, views, serializers Python/Flask: Look for route decorators, blueprints Go: Look for handler functions, router setup PHP: Look for route definitions, controllers

Route Organization (Copy from Actual Project)

Before documenting, analyze how routes are actually organized:

Directory structure for routes/endpoints
HTTP method conventions in use
Route parameter patterns found in code
URL structure patterns

Middleware Stack (Detect What Exists)

Find actual middleware in use:

Authentication/authorization middleware files
Validation middleware implementations
Error handling middleware
Request logging setup (if any)

Technology-Specific Adaptations

Express.js Projects

Router usage patterns from existing code
Middleware order and setup
Error handling with next()

FastAPI/Django Projects

Dependency injection patterns
Serializer/Pydantic model usage
Authentication decorators

Go Projects

Handler function signatures
Middleware chain patterns
Error handling approaches

Validation Approaches (Copy from Project)

Find what’s actually implemented:

Schema definition location and format
Input validation middleware usage
Error response structure in use

Development Patterns (Extract from Code)

Look for existing patterns in the codebase:

Route testing approach (if tests exist)
API documentation generation (OpenAPI, etc.)
Request/response typing patterns

Critical Warnings (Universal)

NEVER expose internal error details in API responses
NEVER skip input validation on user inputs
NEVER hardcode API keys or secrets in code
NEVER assume framework without detection

Anti-Patterns for API Documentation

Don’t explain HTTP basics or REST principles
Don’t assume specific framework without verification
Don’t duplicate existing API documentation (OpenAPI/Swagger)
Don’t include framework tutorials - focus on project patterns

Database / Data Layer Template

Use this template when documenting database or data layer packages.

MANDATORY: Before using this template, analyze the current project to identify:

Database type - Run: grep -r "postgres\|mysql\|sqlite\|mongo" package.json | head -3
ORM/Query builder - Run: grep -r "prisma\|drizzle\|typeorm\|sequelize\|mongoose\|knex" package.json | head -3
Schema files - Run: find . -name "schema.*" -o -name "*.sql" -o -name "*prisma*" | grep -v node_modules | head -5
Migration system - Run: find . -name "*migration*" -type d 2>/dev/null
Database config - Run: find . -name "*database*" -o -name "*db*" | grep -E "\.(js|ts|json)$" | head -5

Adaptive Template Structure

## Database
- Database: [DETECTED_DB_TYPE] ([PostgreSQL/MySQL/SQLite/MongoDB/etc])
- ORM/Query: [DETECTED_ORM] ([Prisma/Drizzle/TypeORM/etc])
- Schema: `[DETECTED_SCHEMA_PATH]` OR "Schema files not found"
- Migrations: `[DETECTED_MIGRATION_COMMAND]` OR "No migration system detected"
- Connection: via `[DETECTED_CONNECTION_FILE]` OR "Connection config not found"
- NEVER run migrations in tests

Detection Instructions

Schema Management (Adapt Based on Findings)

Prisma: Look for prisma/schema.prisma, npx prisma migrate Drizzle: Look for drizzle.config.ts, schema in src/db/ TypeORM: Look for entity files, typeorm migration:run Raw SQL: Look for .sql files, custom migration scripts MongoDB: Look for model definitions, no traditional migrations

Connection Management

Find actual connection patterns in the project:

Database URL in .env.example or config files
Connection pool configuration
Environment-specific database configs

Query Patterns (Copy from Existing Code)

Before documenting, find examples in the codebase:

How queries are written in this specific project
Transaction patterns actually used
Error handling approaches in place

Technology-Specific Adaptations

SQL Databases (PostgreSQL, MySQL, SQLite)

Migration commands and workflow
Schema definition files location
Seed data setup if present

NoSQL Databases (MongoDB, etc.)

Model/schema definitions
Index management approach
Data migration strategies (if any)

ORM-Specific Patterns

Copy patterns from existing code, don’t assume:

Entity/model definitions format
Query builder syntax actually used
Relationship definitions in place

Critical Warnings (Universal)

NEVER run migrations against production from local environment
NEVER commit database credentials or connection strings
NEVER run migrations in test suites (use test database setup)
NEVER assume database type - detect from project files

Anti-Patterns for Database Documentation

Don’t explain what databases or ORMs are in general
Don’t document SQL syntax basics
Don’t assume specific database technology without verification
Don’t duplicate ORM documentation that’s already available

Design System / UI Package Template

Use this template when documenting design system or UI component packages.

MANDATORY: Before using this template, analyze the current project to identify:

Component library location - Run: find . -name "components" -type d | head -5
UI framework - Run: grep -r "react\|vue\|angular\|svelte" package.json | head -3
Styling approach - Run: find . -name "*.css" -o -name "*.scss" -o -name "*.styled.*" | head -5
Build tool - Run: ls -la *storybook* vite.config.* webpack.config.* rollup.config.* 2>/dev/null
Design tokens - Run: find . -name "*token*" -o -name "*theme*" | grep -v node_modules | head -5

Adaptive Template Structure

## Design System
- Components: `[DETECTED_COMPONENTS_PATH]/**`
- Design tokens: `[DETECTED_TOKENS_PATH]` OR "No design tokens found"
- [COMPONENT_GALLERY_COMMAND] OR "No component gallery setup found"
- Examples:
  - [EXAMPLE_COMPONENT_1]: `[ACTUAL_PATH_FROM_PROJECT]`
  - [EXAMPLE_COMPONENT_2]: `[ACTUAL_PATH_FROM_PROJECT]`

Detection Instructions

Component Organization

Before documenting, run discovery commands to identify:

Components directory structure (don’t assume src/components/)
Design token files (could be .json, .js, .ts, CSS variables)
Theme configuration location
Styling approach used in the project

Development Commands

Analyze package.json scripts to identify:

Storybook command: grep -r "storybook" package.json
Build command: grep -r "build.*ui\|build.*components" package.json
Test command: grep -r "test.*components\|test.*ui" package.json

Technology-Specific Patterns

React Projects: Look for .tsx, styled-components, emotion Vue Projects: Look for .vue, scoped styles
Angular Projects: Look for .component.ts, Angular Material Web Components: Look for custom element definitions

Usage Pattern Examples

Import Patterns (Adapt Based on Actual Project)

// Example based on what you find in existing files
import { [ComponentName] } from '[ACTUAL_IMPORT_PATH]';

Component API Design (Copy from Existing)

Find the most well-structured component in the project
Copy its prop patterns and API design
Reference it as the standard to follow

Anti-Patterns for Design Systems

Don’t assume React/TypeScript (check what’s actually used)
Don’t hardcode paths without verification
Don’t reference Storybook if it doesn’t exist
Don’t document patterns not used in this specific project

Discovery Commands Reference

Comprehensive commands for analyzing repository structure and detecting actual technologies in use.

Phase 1: Initial Project Scan

Find Existing Documentation

# Find existing AGENTS.md files
find . -name "AGENTS.md" -o -name "AI-DOCS.md" 2>/dev/null

# Find local skills to reference
find .claude/skills -name "SKILL.md" 2>/dev/null
ls plugins/*/skills/*/SKILL.md 2>/dev/null

Project Structure Discovery

# Analyze project structure
find . -name "package.json" -not -path "./node_modules/*" 2>/dev/null
find . -name "pyproject.toml" -o -name "setup.py" -o -name "requirements.txt" 2>/dev/null
find . -name "go.mod" -o -name "go.sum" 2>/dev/null
find . -name "Cargo.toml" -o -name "Cargo.lock" 2>/dev/null

# Check for monorepo tools
ls -la pnpm-workspace.yaml lerna.json turbo.json nx.json 2>/dev/null
grep -r "workspaces" package.json 2>/dev/null

Phase 2: Technology Stack Detection

Programming Languages (Run ALL that apply)

# JavaScript/TypeScript
find . -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" | head -5

# Python
find . -name "*.py" | head -5

# Go
find . -name "*.go" | head -5

# Rust
find . -name "*.rs" | head -5

# PHP
find . -name "*.php" | head -5

# Java/Kotlin
find . -name "*.java" -o -name "*.kt" | head -5

Frontend Frameworks (Check package.json or equivalent)

# JavaScript frameworks
grep -r "react\|vue\|angular\|svelte\|solid" package.json 2>/dev/null | head -5
grep -r "next\|nuxt\|gatsby\|remix\|astro" package.json 2>/dev/null | head -5

# Build tools
grep -r "vite\|webpack\|rollup\|parcel\|esbuild" package.json 2>/dev/null | head -3

Backend Frameworks

# Node.js backends
grep -r "express\|fastify\|koa\|nest\|hapi\|adonis" package.json 2>/dev/null | head -3

# Python backends
grep -r "django\|flask\|fastapi\|tornado" pyproject.toml setup.py requirements.txt 2>/dev/null | head -3

# Go backends
grep -r "gin\|echo\|fiber\|gorilla" go.mod 2>/dev/null | head -3

# Other languages
grep -r "rails\|sinatra" Gemfile 2>/dev/null
grep -r "laravel\|symfony" composer.json 2>/dev/null

Database Technology Detection

# Database types
grep -r "postgres\|mysql\|sqlite\|mongo\|redis\|cassandra" package.json pyproject.toml go.mod Cargo.toml 2>/dev/null | head -5

# ORMs and query builders
grep -r "prisma\|drizzle\|typeorm\|sequelize\|mongoose\|knex" package.json 2>/dev/null | head -3
grep -r "sqlalchemy\|django.db\|peewee" pyproject.toml requirements.txt 2>/dev/null | head -3
grep -r "gorm\|sqlx" go.mod 2>/dev/null | head -3

Testing Frameworks

# JavaScript testing
grep -r "jest\|vitest\|mocha\|jasmine\|ava" package.json 2>/dev/null | head -3
grep -r "playwright\|cypress\|puppeteer\|selenium" package.json 2>/dev/null | head -3

# Python testing
grep -r "pytest\|unittest\|nose" pyproject.toml setup.py requirements.txt 2>/dev/null | head -3

# Other languages
ls -la *_test.go 2>/dev/null | head -3
find . -name "*_test.rs" 2>/dev/null | head -3

Phase 3: File Structure Analysis

Configuration Files Discovery

# Build and development configs
find . -maxdepth 2 -name "*.config.*" -o -name ".*rc*" 2>/dev/null | head -10

# Environment and settings
ls -la .env* docker-compose.* Dockerfile* Makefile 2>/dev/null

# CI/CD configs
ls -la .github/workflows/ .gitlab-ci.yml .circleci/ 2>/dev/null

Styling and Asset Management

# Styling approaches
find . -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.less" | head -5
find . -name "*.styled.*" -o -name "*emotion*" | head -5
grep -r "tailwind\|styled-components\|emotion" package.json 2>/dev/null

# Static assets
ls -la public/ static/ assets/ 2>/dev/null

Phase 4: Package and Service Organization

Multi-Package Structure

# Common monorepo patterns
ls -la apps/ packages/ services/ workers/ libs/ 2>/dev/null

# Service-specific directories
ls -la api/ web/ mobile/ desktop/ backend/ frontend/ 2>/dev/null

# Specialized directories
ls -la components/ utils/ shared/ common/ core/ 2>/dev/null

Development Environment Setup

# Node.js setup
ls -la package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

# Python environment
ls -la poetry.lock Pipfile.lock conda.yml environment.yml 2>/dev/null

# Other environments
ls -la .ruby-version .nvmrc .python-version 2>/dev/null

Analysis Report Template

After running discovery commands, structure findings as:

1. Repository Classification

Type: Simple project / Multi-package / Monorepo
Complexity: [Number of major directories/packages]
Team Structure: Single developer / Small team / Large organization

2. Technology Stack Summary

Primary Language(s): [Detected from file extensions and configs]
Frontend: [Framework + build tool detected]
Backend: [Framework + language detected]
Database: [Type + ORM detected]
Testing: [Framework(s) detected]

3. Build and Development Tools

Package Manager: [npm/yarn/pnpm/poetry/cargo/go modules]
Build System: [Specific tool detected]
Monorepo Tool: [If applicable - Nx/Turborepo/Lerna]
CI/CD: [If detected - GitHub Actions/GitLab CI]

4. File Organization Patterns

Source Code: [Location of main application code]
Tests: [Test file patterns and locations found]
Configuration: [Config file patterns discovered]
Documentation: [Existing docs structure]

5. Existing Skills and Documentation

Local Skills: [List discovered skills with paths]
Documentation: [README, wiki, docs/ folder status]
API Docs: [OpenAPI, GraphQL schema, etc.]

6. Recommended AGENTS.md Structure

Based on analysis:

Approach: Simple single file / Hierarchical structure
Sub-files needed: [List directories requiring own AGENTS.md]
Critical patterns: [Key conventions to document]

Testing Template

Use this template when documenting testing setup and patterns for packages.

MANDATORY: Before using this template, analyze the current project to identify:

Testing framework - Run: grep -r "jest\|vitest\|mocha\|jasmine\|pytest\|go.*test\|cargo.*test" package.json pyproject.toml Cargo.toml go.mod | head -3
Test file patterns - Run: find . -name "*.test.*" -o -name "*.spec.*" | head -5
E2E framework - Run: grep -r "playwright\|cypress\|puppeteer\|selenium" package.json | head -3
Test directories - Run: find . -name "*test*" -type d | grep -v node_modules | head -5
Config files - Run: ls -la jest.config.* vitest.config.* playwright.config.* cypress.config.* pytest.ini 2>/dev/null

Adaptive Template Structure

## Testing
- Framework: [DETECTED_TEST_FRAMEWORK] ([Jest/Vitest/pytest/etc])
- Unit: `[DETECTED_TEST_PATTERN]` ([*.test.ts/test_*.py/etc]) 
- Integration: `[DETECTED_INTEGRATION_PATH]/**` OR "No integration tests found"
- E2E: `[DETECTED_E2E_PATH]/**` ([DETECTED_E2E_FRAMEWORK]) OR "No E2E tests found"
- Run single: `[DETECTED_SINGLE_TEST_COMMAND] [file-path]`
- Mocks: `[DETECTED_MOCK_PATH]/**` OR "Mock location not standardized"

Detection Instructions

Framework-Specific Patterns

Jest: Look for jest.config.js, tests with .test.js/.spec.js Vitest: Look for vitest.config.ts, similar patterns to Jest Mocha: Look for mocha.opts, test directory structure pytest: Look for pytest.ini, test_*.py or *_test.py files Go: Look for *_test.go files, go test commands Rust: Look for #[test] annotations in src/ or tests/

Test Organization (Copy from Actual Project)

Find existing patterns:

Where are unit tests actually located?
How are integration tests organized?
What test file naming convention is used?
Where are test utilities/helpers located?

Commands and Scripts (Extract from package.json/Makefile)

Find actual commands used:

Test runner commands from package.json scripts
Coverage generation commands
Watch mode setup
Specific test file execution pattern

Technology-Specific Adaptations

JavaScript/TypeScript (Jest/Vitest)

Test setup files location
Mock patterns in use
Coverage configuration
Test environment setup

Python (pytest)

Fixture definitions and location
Conftest.py usage
Test markers and parametrization
Virtual environment handling

Go

Test package organization
Table-driven test patterns
Benchmark tests (if present)
Test helper functions

Other Languages

Adapt based on what’s detected in the project

Testing Patterns (Extract from Existing Tests)

Before documenting, examine existing tests for:

Setup/teardown patterns actually used
Mocking approach and conventions
Test data generation methods
Assertion patterns and styles

Critical Warnings (Universal)

NEVER run tests against production data or APIs
NEVER commit real API keys or credentials in test files
NEVER rely on external services in unit tests (use mocks)
NEVER assume testing framework without detection

Anti-Patterns for Testing Documentation

Don’t explain testing concepts or philosophies
Don’t assume specific framework without verification
Don’t document assertion syntax basics
Don’t duplicate framework documentation that’s already available

Troubleshooting Common Issues

Common problems when creating AGENTS.md files and their solutions.

Issue: Unclear Monorepo Structure

Problem: Complex repository with unclear package boundaries or mixed patterns Symptoms:

Packages have different tech stacks
Unclear which directories need own AGENTS.md
Multiple build systems in use

Solution:

Start with root AGENTS.md only
Add sub-files iteratively based on usage
Use JIT index approach to defer complexity
Focus on most-used packages first

Fallback: Create minimal root file pointing to package-specific documentation

Issue: Too Many Local Skills to Reference

Problem: Project has 10+ local skills, overwhelming to list all Symptoms:

Skills list dominates AGENTS.md content
Unclear which skills apply to which scenarios
Maintenance burden keeping list updated

Solution:

Group skills by category (testing, deployment, etc.)
Create skill index files in a local index directory (e.g., docs/agents/)
Reference index files, not individual skills
Use conditional loading based on file types

Example:

## Local Skills
- Frontend: See `docs/agents/frontend-index.md`
- Backend: See `docs/agents/backend-index.md`
- DevOps: Use `deployment` skill for CI/CD tasks

Issue: Mixed Technology Stacks

Problem: Repository contains Python, Node.js, Go, etc. with different patterns Symptoms:

Universal conventions don’t apply
Different package managers and build tools
Language-specific patterns conflict

Solution:

Create language-specific subdirectory AGENTS.md files
Keep root file minimal with routing only
Use technology-specific templates from references/
Avoid forcing universal patterns

Structure:

AGENTS.md (routing only)
services/api-go/AGENTS.md (Go-specific)
services/web-node/AGENTS.md (Node.js-specific)

Issue: Existing Documentation Conflicts

Problem: Project already has README files, wiki pages, or other docs Symptoms:

Information duplication
Conflicting instructions
Unclear which source is authoritative

Solution:

Reference existing docs, don’t duplicate
Focus AGENTS.md on AI-specific needs
Link to authoritative sources
Avoid project overview content

Pattern:

## Architecture
See [Architecture Decision Records](docs/adr/) for design decisions

## API Documentation
Authoritative API docs: [OpenAPI spec](api/openapi.yaml)

Issue: Frequent Changes Break Documentation

Problem: AGENTS.md becomes outdated quickly due to rapid development Symptoms:

File paths in examples no longer exist
Commands don’t work
Build process changed but docs didn’t update

Solution:

Use patterns instead of specific examples where possible
Reference configuration files instead of hardcoding values
Focus on stable patterns, not volatile implementation details
Add validation checks to CI/CD

Stable patterns:

# Good - pattern-based
- Components: `src/components/**/*.tsx`
- Tests: Colocated `*.test.tsx`

# Bad - specific examples that break
- Button: `src/components/Button/Button.tsx`
- Modal: `src/components/Modal/Modal.tsx`

Issue: Team Disagreement on Conventions

Problem: Team members want different approaches documented Symptoms:

Conflicting style guides
Multiple “right ways” to do things
AGENTS.md becomes battleground for opinions

Solution:

Document current patterns, not ideal patterns
Show examples from existing codebase
Avoid prescriptive language (“should”, “must”)
Focus on consistency over perfection

Approach:

## Current Patterns
- New components: Follow `src/components/Button/` structure
- Legacy components: See `src/legacy/` - avoid this pattern
- State management: Redux Toolkit (see `src/store/`)

Edit this page on GitHub