85 added, 199 removed. Audit A to A.
---
name: docs-init
- description: Initialize comprehensive documentation structure for a project based
- on detected technologies and configuration. This skill should be used when users
- want to set up project documentation from scratch, bootstrap docs for a new project,
- or create initial documentation structure.
+ description: Bootstraps a documentation structure (architecture, onboarding, data-model,
+ deployment, security, contributing, and a first ADR) for a project that has little
+ or no docs/ directory, exploring the codebase and populating templates only with
+ content evidenced in the code. Use when the user wants to set up docs, bootstrap
+ documentation, initialize project docs, scaffold a docs/ folder, or create docs from
+ scratch for a new or undocumented project. Not for refreshing or syncing docs that
+ already exist (use docs-update). Not for generating a standalone architecture or
+ ER diagram without the surrounding document (use docs-diagram).
metadata:
author: mgiovani
- version: 1.0.0
- source: https://github.com/mgiovani/skills
+ version: 2.0.0
disable-model-invocation: true
argument-hint: '[context]'
- allowed-tools: Read, Write, Grep, Glob, Bash(git *), Task
+ allowed-tools: Read, Write, Grep, Glob, Bash(git *), Bash(find *), Task
context: fork
agent: general-purpose
---
- # Docs Init
-
- > **Cross-Platform AI Agent Skill**
- > This skill works with any AI agent platform that supports the skills.sh standard.
-
# Initialize Project Documentation
- Generate comprehensive documentation structure for a project based on detected technologies and configuration.
+ Bootstrap a `docs/` structure for a project with little or no existing documentation. Only generate what the codebase actually evidences.
## Anti-Hallucination Guidelines
- **CRITICAL**: Before documenting ANY feature, component, or capability:
- 1. **Verify existence** - Read the actual file/directory to confirm it exists
- 2. **Count accurately** - Use `ls` or `find` to get exact counts, do not estimate
- 3. **Quote actual code** - Reference real function names, not assumed ones
- 4. **Check empty directories** - A directory existing does not mean content exists
- 5. **Never assume** - If it cannot be verified, do not document it
+ Every claim in generated docs must trace to something read or grepped in this run:
+ 1. Verify a file/directory exists before referencing it.
+ 2. Get counts from `ls`/`find`/`grep` — never estimate.
+ 3. Quote real function/class/table names, not assumed ones.
+ 4. An empty directory is not a feature — don't document it.
+ 5. If a claim can't be verified, drop it rather than guess.
+
## Workflow
- ### Phase 1: Deep Codebase Exploration (Explore Codebase)
+ ### 1. Explore the codebase
- Use the available exploration and search capabilities to thoroughly analyze the codebase before generating any documentation.
+ Find: source directories with actual code, package manager files (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, ...), database/ORM files, infrastructure configs (Docker, k8s, Terraform), and any existing `docs/`. See Detection Commands below for the exact patterns.
- ### Phase 2: Verify Findings
+ If a Task/subagent tool is available, delegate this to an Explore agent with that scope. Otherwise run the same `grep`/`find` commands inline and `Read` each hit — the result must be the same either way.
- After exploration, verify each finding by reading the actual files:
- - Read package.json/pyproject.toml to confirm tech stack
- - Read model files to confirm database entities exist
- - Check directories are not empty before claiming components exist
+ Verify every finding before using it: read the package manifest, read the model file, confirm a directory has real files inside it, not just an empty folder.
- ### Phase 3: Detect Project Characteristics
+ ### 2. Detect project characteristics
- - Technology stack (language, frameworks, databases)
- - Project type (web app, CLI, library, microservice, etc.)
- - Infrastructure (Docker, K8s, cloud configs)
- - Database/ORM presence (SQLAlchemy, Prisma, TypeORM, Django, etc.)
+ From the exploration, determine: language/framework stack, project type (web app, CLI, library, service), whether a database/ORM is present, and whether infrastructure/deployment configs exist.
- ### Phase 4: Determine Relevant Documentation
+ ### 3. Decide which docs to generate
- **Core Documentation** (always generate):
- - `docs/architecture.md` - System architecture overview
- - `docs/onboarding.md` - Developer onboarding guide
- - `docs/adr/0001-record-architecture-decisions.md` - First ADR (meta-ADR)
+ - **Always**: `docs/architecture.md`, `docs/onboarding.md`, `docs/adr/0001-record-architecture-decisions.md` (Nygard-format meta-ADR — generate inline, no template file)
+ - **If a database/ORM was found**: `docs/data-model.md`
+ - **If deployment configs were found** (Dockerfile, k8s manifest, CI workflow, IaC): `docs/deployment.md`, `docs/security.md`
+ - **If the project looks collaborative** (multiple contributors in `git log`, an open-source license, no existing CONTRIBUTING): `docs/contributing.md`, `docs/rfc/` directory
- **Data Documentation** (if database detected):
- - `docs/data-model.md` - Database schema and ER diagrams
+ Don't generate a doc type with no supporting evidence — an empty data-model.md for a stateless CLI is worse than no file at all.
- **Infrastructure Documentation** (if deployment configs found):
- - `docs/deployment.md` - CI/CD and deployment procedures
- - `docs/security.md` - Security architecture
+ ### 4. Check for existing docs
- **Development Documentation** (if collaborative project):
- - `docs/contributing.md` - Contribution guidelines
- - `docs/rfc/` - RFC directory for proposals
+ Scan `docs/`. For any target file that already exists, do not overwrite it — list it under "skipped" and ask the user before touching it. This skill is safe to rerun: by default it only fills gaps.
- ### Phase 5: Check for Existing Documentation
+ ### 5. Populate templates
- - Scan `docs/` directory
- - If files exist, ask user before overwriting
- - Show what will be created vs what exists
+ Templates live in `assets/templates/` (see reference table below). For each one you're using:
- ### Phase 6: Load and Populate Templates
+ 1. Grep it for its actual placeholder set: `grep -oE '\{\{[A-Z_0-9]+\}\}' assets/templates/<name>.md | sort -u`
+ 2. Map every placeholder to a value from step 1/2's verified findings. Never leave a placeholder as a literal `{{TOKEN}}` in the output.
+ 3. Templates mark some sections as conditional with an HTML comment ("delete if...", "only if evidenced"). Where the codebase gives no evidence for that section, delete the whole section — heading included, not just the placeholder text.
+ 4. After writing the file, grep it for `\{\{[A-Z_0-9]+\}\}` again. Zero matches. If any remain, resolve or delete them before moving on.
- Templates are in `assets/templates/`. Replace placeholders:
- - `{{PROJECT_NAME}}` - From git repo name or directory name
- - `{{DATE}}` - Current date (YYYY-MM-DD format)
- - `{{TECH_STACK}}` - Detected technologies
- - `{{DESCRIPTION}}` - Brief project description from README or git
- - `{{CONTEXT}}` - Gathered context from codebase analysis
+ **Worked example** — a FastAPI + PostgreSQL service:
- ### Phase 7: Verify Before Writing
+ ```
+ $ grep -oE '\{\{[A-Z_0-9]+\}\}' assets/templates/architecture.md | sort -u
+ {{COMPONENT_DEPENDENCIES}}
+ {{COMPONENT_DESCRIPTION}}
+ {{COMPONENT_NAME}}
+ {{DATA_FLOW}}
+ {{DATE}}
+ {{DEPLOYMENT_SUMMARY}}
+ ...
+ ```
- Before writing each document, verify claims:
- 1. Re-read the source file to confirm the claim
- 2. If claiming "X components exist", verify the count with ls/find
- 3. If referencing a function/class, grep to confirm it exists
- 4. Remove any claims that cannot be verified
+ Map each to a verified finding — `{{TECHNOLOGY_STACK}}` becomes "Python 3.12, FastAPI 0.115, PostgreSQL 16 via SQLAlchemy", read from `pyproject.toml` and the model files, not assumed. If `security.md`'s Compliance section has no GDPR/HIPAA evidence in the codebase (no consent flow, no PHI handling), delete that whole section rather than fill it with a guess.
- ### Phase 8: Generate Documentation
+ ### 6. Write the files
- - Create `docs/` directory if it does not exist
- - Create subdirectories: `docs/adr/`, `docs/rfc/` (if needed)
- - Generate each relevant documentation file
- - Populate with project-specific content
+ Create `docs/` (and `docs/adr/`, `docs/rfc/` if needed). Write each file that isn't being skipped.
- ### Phase 9: Report Results
+ ### 7. Report
- - List all documentation files created
- - Show what was skipped (already exists)
- - Provide next steps
+ List what was created, what was skipped (already existed), and next steps.
- ## Context Detection Examples
+ ## Template Reference
- ```bash
- # Check for language/framework
- !`find . -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" | head -5`
+ | Document | Template | Generated when |
+ |----------|----------|-----------------|
+ | Architecture | `architecture.md` | always |
+ | Onboarding | `onboarding.md` | always |
+ | First ADR | inline (Nygard format) | always |
+ | Data Model | `data-model.md` | database/ORM detected |
+ | Deployment | `deployment.md` | deployment config detected |
+ | Security | `security.md` | deployment config detected |
+ | Contributing | `contributing.md` | collaborative project |
- # Check for database
- !`find . -name "*models.py" -o -name "*schema.prisma" -o -name "*entity.ts" | head -5`
+ ## Detection Commands
- # Check for infrastructure
- !`find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "*.k8s.yaml" | head -5`
+ Run these directly (or hand them to the Explore agent from step 1):
- # Get project name
- !`basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)`
+ ```bash
+ # Language/framework
+ find . -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" | head -5
- # Get project description
- !`head -20 README.md 2>/dev/null || echo ""`
- ## Template Locations
+ # Database/ORM
+ find . -name "*models.py" -o -name "*schema.prisma" -o -name "*entity.ts" | head -5
- Templates are loaded from `assets/templates/`:
+ # Infrastructure
+ find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "*.k8s.yaml" | head -5
- | Document Type | Template File |
- |--------------|---------------|
- | Architecture | `architecture.md` |
- | Onboarding | `onboarding.md` |
- | ADR (first) | `adr/nygard.md` |
- | Data Model | `data-model.md` |
- | Deployment | `deployment.md` |
- | Security | `security.md` |
- | Contributing | `contributing.md` |
+ # Project name and description
+ basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+ head -20 README.md 2>/dev/null
+ ```
## Usage Examples
- Basic initialization (auto-detect everything):
```
docs-init
- With additional context:
- ```
docs-init for Python FastAPI microservice
docs-init for Next.js SaaS application
- docs-init for React component library
- ## Important Notes
-
- - **Zero-config**: Works without any configuration file
- - **Smart detection**: Only generates relevant documentation
- - **Safe**: Always asks before overwriting existing files
- - **Customizable**: User context in command is used to enhance generation
- - **Git-aware**: Uses git information when available
- - **Incremental**: Can be run multiple times safely
+ ```
## Example Output
```
Documentation Initialization Complete
Created:
docs/architecture.md - System architecture overview
docs/onboarding.md - Developer onboarding guide
docs/adr/0001-record-architecture-decisions.md - Meta-ADR
docs/data-model.md - Database schema (SQLAlchemy detected)
docs/deployment.md - Deployment guide (Docker detected)
Skipped (already exists):
docs/contributing.md
- Next Steps:
- 1. Review and customize generated documentation
- 2. Run docs-diagram er to generate ER diagram
- 3. Run docs-diagram arch to generate architecture diagram
- 4. Create ADRs for key decisions: docs-adr "Decision Title"
- ## When to Run
-
- - Starting a new project
- - Adding documentation to an existing project
- - Reorganizing project documentation
- - Onboarding new team members
-
- **Note**: This skill can be run multiple times. It will only create missing files and ask before overwriting existing ones.
-
- ## Claude Code Enhanced Features
-
- This skill includes the following Claude Code-specific enhancements:
-
- ## Workflow
-
- ### Phase 1: Deep Codebase Exploration (Use Explore Agent)
-
- Use the Task tool with `subagent_type: "Explore"` to thoroughly analyze the codebase before generating any documentation.
-
- ```
- Use Task tool with Explore agent:
- - prompt: "Analyze this codebase structure. Find: 1) All source directories with actual code files, 2) Package manager files (package.json, pyproject.toml, etc.), 3) Database/ORM files, 4) Infrastructure configs (Docker, K8s), 5) Existing documentation. Return ONLY verified findings with file paths."
- - subagent_type: "Explore"
+ Next steps:
+ 1. Review and customize the generated docs
+ 2. docs-diagram er / docs-diagram arch for standalone diagrams
+ 3. docs-adr "Decision Title" for future ADRs
```
- ### Phase 2: Verify Findings
-
- After exploration, verify each finding by reading the actual files:
- - Read package.json/pyproject.toml to confirm tech stack
- - Read model files to confirm database entities exist
- - Check directories are not empty before claiming components exist
-
- ### Phase 3: Detect Project Characteristics
-
- - Technology stack (language, frameworks, databases)
- - Project type (web app, CLI, library, microservice, etc.)
- - Infrastructure (Docker, K8s, cloud configs)
- - Database/ORM presence (SQLAlchemy, Prisma, TypeORM, Django, etc.)
-
- ### Phase 4: Determine Relevant Documentation
-
- **Core Documentation** (always generate):
- - `docs/architecture.md` - System architecture overview
- - `docs/onboarding.md` - Developer onboarding guide
- - `docs/adr/0001-record-architecture-decisions.md` - First ADR (meta-ADR)
-
- **Data Documentation** (if database detected):
- - `docs/data-model.md` - Database schema and ER diagrams
-
- **Infrastructure Documentation** (if deployment configs found):
- - `docs/deployment.md` - CI/CD and deployment procedures
- - `docs/security.md` - Security architecture
-
- **Development Documentation** (if collaborative project):
- - `docs/contributing.md` - Contribution guidelines
- - `docs/rfc/` - RFC directory for proposals
-
- ### Phase 5: Check for Existing Documentation
-
- - Scan `docs/` directory
- - If files exist, ask user before overwriting
- - Show what will be created vs what exists
-
- ### Phase 6: Load and Populate Templates
-
- Templates are in `assets/templates/`. Replace placeholders:
- - `{{PROJECT_NAME}}` - From git repo name or directory name
- - `{{DATE}}` - Current date (YYYY-MM-DD format)
- - `{{TECH_STACK}}` - Detected technologies
- - `{{DESCRIPTION}}` - Brief project description from README or git
- - `{{CONTEXT}}` - Gathered context from codebase analysis
-
- ### Phase 7: Verify Before Writing
-
- Before writing each document, verify claims:
- 1. Re-read the source file to confirm the claim
- 2. If claiming "X components exist", verify the count with ls/find
- 3. If referencing a function/class, grep to confirm it exists
- 4. Remove any claims that cannot be verified
-
- ### Phase 8: Generate Documentation
-
- - Create `docs/` directory if it does not exist
- - Create subdirectories: `docs/adr/`, `docs/rfc/` (if needed)
- - Generate each relevant documentation file
- - Populate with project-specific content
-
- ### Phase 9: Report Results
+ ## Notes
- - List all documentation files created
- - Show what was skipped (already exists)
- - Provide next steps
+ - Safe to rerun — only fills gaps, asks before overwriting existing files.
+ - User-supplied context (e.g. "for a FastAPI microservice") steers detection but doesn't replace verification — still confirm the stack from the actual files.