Agent skill

agents-md-generator

Generate hierarchical AGENTS.md structures for codebases. Use when user asks to create AGENTS.md files, analyze codebase for AI agent documentation, set up AI-friendly project documentation, or generate context files for AI coding assistants. Triggers on "create AGENTS.md", "generate agents", "analyze codebase for AI", "AI documentation setup", "hierarchical agents".

View SKILL.md on GitHub Repository
Stars 133
Forks 18

Install this agent skill to your Project

npx add-skill https://github.com/julianromli/opencode-template/tree/main/skill/agents-md-generator

SKILL.md

AGENTS.md Generator

Generate hierarchical AGENTS.md structures optimized for AI coding agents with minimal token usage.

Core Principles

  1. Root AGENTS.md is LIGHTWEIGHT - Only universal guidance, links to sub-files (~100-200 lines max)
  2. Nearest-wins hierarchy - Agents read closest AGENTS.md to file being edited
  3. JIT indexing - Provide paths/globs/commands, NOT full content
  4. Token efficiency - Small, actionable guidance over encyclopedic docs
  5. Sub-folder files have MORE detail - Specific patterns, examples, commands

Workflow

Phase 1: Repository Analysis

Analyze and report:

  1. Repository type: Monorepo, multi-package, or simple?
  2. Tech stack: Languages, frameworks, key tools
  3. Major directories needing own AGENTS.md:
    • Apps (apps/web, apps/api, apps/mobile)
    • Services (services/auth, services/transcribe)
    • Packages (packages/ui, packages/shared)
    • Workers (workers/queue, workers/cron)
  4. Build system: pnpm/npm/yarn workspaces? Turborepo? Lerna?
  5. Testing setup: Jest, Vitest, Playwright, pytest?
  6. Key patterns: Organization, conventions, examples, anti-patterns

Present as structured map before generating files.

Phase 2: Root AGENTS.md

Create lightweight root (~100-200 lines):

markdown
# Project Name

## Project Snapshot
[3-5 lines: repo type, tech stack, note about sub-AGENTS.md files]

## Root Setup Commands
[5-10 lines: install, build all, typecheck all, test all]

## Universal Conventions
[5-10 lines: code style, commit format, branch strategy, PR requirements]

## Security & Secrets
[3-5 lines: never commit tokens, .env patterns, PII handling]

## JIT Index
### Package Structure
- Web UI: `apps/web/` -> [see apps/web/AGENTS.md](apps/web/AGENTS.md)
- API: `apps/api/` -> [see apps/api/AGENTS.md](apps/api/AGENTS.md)

### Quick Find Commands
- Search function: `rg -n "functionName" apps/** packages/**`
- Find component: `rg -n "export.*ComponentName" apps/web/src`
- Find API routes: `rg -n "export const (GET|POST)" apps/api`

## Definition of Done
[3-5 lines: what must pass before PR]

Phase 3: Sub-Folder AGENTS.md

For each major package, create detailed AGENTS.md:

markdown
# Package Name

## Package Identity
[2-3 lines: what it does, primary tech]

## Setup & Run
[5-10 lines: install, dev, build, test, lint commands]

## Patterns & Conventions
[10-20 lines - MOST IMPORTANT SECTION]
- File organization rules
- Naming conventions
- Examples with actual file paths:
  - DO: Use pattern from `src/components/Button.tsx`
  - DON'T: Class components like `src/legacy/OldButton.tsx`
  - Forms: Copy `src/components/forms/ContactForm.tsx`
  - API calls: See `src/hooks/useUser.ts`

## Key Files
[5-10 lines: important files to understand package]
- Auth: `src/auth/provider.tsx`
- API client: `src/lib/api.ts`
- Types: `src/types/index.ts`

## JIT Index Hints
[5-10 lines: search commands for this package]
- Find component: `rg -n "export function .*" src/components`
- Find hook: `rg -n "export const use" src/hooks`
- Find tests: `find . -name "*.test.ts"`

## Common Gotchas
[3-5 lines if applicable]
- "Auth requires NEXT_PUBLIC_ prefix for client-side"
- "Always use @/ imports for absolute paths"

## Pre-PR Checks
[2-3 lines: copy-paste command]
pnpm --filter @repo/web typecheck && pnpm --filter @repo/web test

Phase 4: Special Templates

Design System / UI Package

markdown
## Design System
- Components: `packages/ui/src/components/**`
- Use design tokens from `packages/ui/src/tokens.ts`
- Component gallery: `pnpm --filter @repo/ui storybook`
- Examples:
  - Buttons: `packages/ui/src/components/Button/Button.tsx`
  - Forms: `packages/ui/src/components/Input/Input.tsx`

Database / Data Layer

markdown
## Database
- ORM: Prisma / Drizzle / TypeORM
- Schema: `prisma/schema.prisma`
- Migrations: `pnpm db:migrate`
- Connection: via `src/lib/db.ts` singleton
- NEVER run migrations in tests

API / Backend Service

markdown
## API Patterns
- REST routes: `src/routes/**/*.ts`
- Auth middleware: `src/middleware/auth.ts`
- Validation: Zod schemas in `src/schemas/**`
- Errors: `ApiError` from `src/lib/errors.ts`
- Example: `src/routes/users/get.ts`

Testing

markdown
## Testing
- Unit: `*.test.ts` colocated
- Integration: `tests/integration/**`
- E2E: `tests/e2e/**` (Playwright)
- Single test: `pnpm test -- path/to/file.test.ts`
- Mocks: `src/test/mocks/**`

Output Format

Provide files in order:

  1. Analysis Summary
  2. Root AGENTS.md (complete)
  3. Each Sub-Folder AGENTS.md (with file path)

Format:

---
File: `AGENTS.md` (root)
---
[content]

---
File: `apps/web/AGENTS.md`
---
[content]

Quality Checklist

Before generating, verify:

  • Root AGENTS.md under 200 lines
  • Root links to all sub-AGENTS.md files
  • Each sub-file has concrete examples (actual paths)
  • Commands are copy-paste ready
  • No duplication between root and sub-files
  • JIT hints use actual patterns (ripgrep, find, glob)
  • Every "DO" has real file example
  • Every "DON'T" references real anti-pattern
  • Pre-PR checks are single commands

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

julianromli/opencode-template

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

133 18
Explore
julianromli/opencode-template

code-refactoring

Code refactoring patterns and techniques for improving code quality without changing behavior. Use for cleaning up legacy code, reducing complexity, or improving maintainability.

133 18
Explore
julianromli/opencode-template

using-superpowers

Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions

133 18
Explore
julianromli/opencode-template

ui-ux-pro-max

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.

133 18
Explore
julianromli/opencode-template

task-generator

Generate structured task lists from specs or requirements. IMPORTANT: After completing ANY spec via ExitSpecMode, ALWAYS ask the user: "Would you like me to generate a task list for this spec?" Use when user confirms or explicitly requests task generation from a plan/spec/PRD.

133 18
Explore
julianromli/opencode-template

next-best-practices

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

133 18
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results