Agent skill

docs-generator

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

View SKILL.md on GitHub Repository

Stars 1

Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ajianaz/skills-collection/tree/main/skills/docs-generator

SKILL.md

Documentation Generator

Generate hierarchical documentation structures optimized for AI coding agents with minimal token usage. Supports AGENTS.md, agent.d, and custom documentation formats.

Core Principles

Root documentation is LIGHTWEIGHT - Only universal guidance, links to sub-files (~100-200 lines max)
Nearest-wins hierarchy - Agents read closest documentation to file being edited
JIT indexing - Provide paths/globs/commands, NOT full content
Token efficiency - Small, actionable guidance over encyclopedic docs
Sub-folder files have MORE detail - Specific patterns, examples, commands
Flexible output formats - Support for AGENTS.md, agent.d, and custom documentation types

Workflow

Phase 0: Document Type Confirmation

Before generating, confirm with user:

Document format: AGENTS.md, agent.d, or custom name?
Target audience: AI agents, developers, or both?
Scope: Root only, sub-folders only, or full hierarchy?
Special requirements: Any specific sections or patterns?

Phase 1: Repository Analysis

Analyze and report:

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

Present as structured map before generating files.

Phase 2: Root Documentation

Create lightweight root (~100-200 lines):

For AGENTS.md format:

markdown

# Project Name

## Project Snapshot
[3-5 lines: repo type, tech stack, note about sub-documentation 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]

For agent.d format:

# Project Name

## project_snapshot
repo_type: "monorepo"
tech_stack: ["typescript", "react", "node"]
note: "See subdirectories for agent.d files"

## root_setup
install: "pnpm install"
build: "pnpm build"
test: "pnpm test"
typecheck: "pnpm typecheck"

## conventions
code_style: "prettier + eslint"
commit_format: "conventional"
branch_strategy: "gitflow"

## jit_index
packages = {
  web_ui = "apps/web/agent.d"
  api = "apps/api/agent.d"
}

## quick_find
search_function = "rg -n \"functionName\" apps/** packages/**"
find_component = "rg -n \"export.*ComponentName\" apps/web/src"
find_api = "rg -n \"export const (GET|POST)\" apps/api"

For Custom Documentation:

markdown

# Project Documentation

## Overview
[Brief project description and architecture]

## Getting Started
[Setup instructions for new developers]

## Architecture
[High-level system design and patterns]

## Development Guidelines
[Coding standards and best practices]

## Module Index
[Links to detailed documentation for each module]

Phase 3: Sub-Folder Documentation

For each major package, create detailed documentation:

AGENTS.md format:

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

agent.d format:

# Package Name

## package_identity
purpose = "React web application"
tech = ["react", "typescript", "tailwind"]

## setup
install = "pnpm install"
dev = "pnpm dev"
build = "pnpm build"
test = "pnpm test"
lint = "pnpm lint"

## patterns
file_organization = """
src/
  components/    # React components
  hooks/         # Custom hooks
  lib/           # Utilities
  types/         # TypeScript types
"""

naming = "PascalCase for components, camelCase for functions"

examples = [
  { do = "Use pattern from src/components/Button.tsx" }
  { dont = "Class components like src/legacy/OldButton.tsx" }
  { forms = "Copy src/components/forms/ContactForm.tsx" }
  { api = "See src/hooks/useUser.ts" }
]

## key_files
auth = "src/auth/provider.tsx"
api_client = "src/lib/api.ts"
types = "src/types/index.ts"

## jit_hints
find_component = "rg -n \"export function .*\" src/components"
find_hook = "rg -n \"export const use\" src/hooks"
find_tests = "find . -name \"*.test.ts\""

## gotchas
[
  "Auth requires NEXT_PUBLIC_ prefix for client-side"
  "Always use @/ imports for absolute paths"
]

## pre_pr_checks
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:

Analysis Summary
Root documentation (complete)
Each Sub-Folder documentation (with file path)

Format:

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

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

Or for agent.d:

---
File: `agent.d` (root)
---
[content]

---
File: `apps/web/agent.d`
---
[content]

Or for custom documentation:

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

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

Quality Checklist

Before generating, verify:

Root documentation under 200 lines
Root links to all sub-documentation 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
Document format matches user requirements
All requested sections are included

Maintainer

ajianaz Core maintainer

Source details

Full Name: ajianaz/skills-collection
Branch: main
Path in repo: skills/docs-generator
License: Other

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

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

ajianaz/skills-collection

task-planner

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.

1 0

Explore

ajianaz/skills-collection

security-auth

Comprehensive security and authentication workflow that orchestrates security architecture, identity management, access control, and compliance implementation. Handles everything from authentication system design and authorization frameworks to security auditing and threat protection.

1 0

Explore

ajianaz/skills-collection

shadcn-svelte-management

Manage UI components using MCP tools with primary focus on Svelte ecosystem. Specialized in Svelte component libraries including shadcn-svelte, Skeleton UI, and Melt UI. Use when user needs to: (1) Add new Svelte UI components to a project (2) Build complex UI features requiring multiple components (3) Research component implementations and examples (4) Get component installation commands (5) Choose appropriate Svelte component library Triggers: "add components", "UI components", "build UI", "install component", "create form", "create dialog", "svelte components", "shadcn-svelte", "skeleton ui"

1 0

Explore

ajianaz/skills-collection

svelte-ui-animator

Analyze and implement purposeful UI animations for Svelte/SvelteKit + Tailwind projects. Specialized in Svelte transitions, actions, and animation patterns. Use when user asks to add animations, enhance UI motion, animate pages/components, or improve visual feedback. Triggers on "add animations", "animate UI", "motion design", "hover effects", "scroll animations", "page transitions", "micro-interactions".

1 0

Explore

ajianaz/skills-collection

mobile-devops

Comprehensive mobile DevOps workflow that orchestrates mobile application development, CI/CD for mobile, app store deployment, and mobile device testing. Handles everything from mobile app build automation and testing to app store submission, monitoring, and mobile-specific DevOps practices.

1 0

Explore

ajianaz/skills-collection

svelte-design

Create distinctive, production-grade frontend interfaces with high design quality. Specialized in Svelte/SvelteKit applications with full-stack capabilities. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

1 0

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Documentation Generator

Core Principles

Workflow

Phase 0: Document Type Confirmation

Phase 1: Repository Analysis

Phase 2: Root Documentation

For AGENTS.md format:

For agent.d format:

For Custom Documentation:

Phase 3: Sub-Folder Documentation

AGENTS.md format:

agent.d format:

Phase 4: Special Templates

Design System / UI Package

Database / Data Layer

API / Backend Service

Testing

Output Format

Quality Checklist

Recommended Agent Skills

task-planner

security-auth

shadcn-svelte-management

svelte-ui-animator

mobile-devops

svelte-design