kevinpatrickrobbins/codebase-audit/readme-file-creation

Antigravity README Generator

This skill provides a systematic workflow for analyzing a repository and generating a state-of-the-art README.md file that follows modern documentation best practices.

When to Use This Skill

Trigger conditions:

• User mentions creating or updating a README
• User asks to "document my repo" or "generate documentation"
• User says "I need a README" or "help me write a README"
• User asks for project documentation
• Repository lacks a README or has an outdated one

Initial approach: Confirm with the user that they want a comprehensive README generated. Explain that the process involves:

1. Scanning the repository structure
2. Analyzing key files and components
3. Identifying the project type and tech stack
4. Generating a comprehensive README with all standard sections

Workflow

Phase 1: Repository Discovery

Goal: Understand the project structure, purpose, and technical details.

Step 1: Identify Repository Location

Ask the user for the repository path. Common scenarios:

• Repository is in /mnt/user-data/uploads (user uploaded files)
• Repository is at a specific path they'll provide
• Current working directory contains the repo

If unclear, use view to check the current directory and /mnt/user-data/uploads.

Step 2: Scan Repository Structure

Perform a comprehensive scan to understand the project:

# Get directory structure
find [repo_path] -type f -name "README*" -o -name "package.json" -o -name "requirements.txt" -o -name "Cargo.toml" -o -name "go.mod" -o -name "pom.xml" -o -name "build.gradle" -o -name "Makefile" -o -name "Dockerfile" -o -name ".gitignore"
 
# Get general structure (limit depth for large repos)
tree -L 3 [repo_path] || find [repo_path] -maxdepth 3 -type d

(find/tree are POSIX commands — on Windows run them in Git Bash, or use the agent's file-search tools such as Glob instead.)

Look for key indicators:

• Package/dependency files (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
• Configuration files (.env.example, config/, etc.)
• Documentation directories (docs/, documentation/)
• Test directories (test/, tests/, __tests__, spec/)
• Source code directories (src/, lib/, app/, etc.)
• Build files (Dockerfile, docker-compose.yml, Makefile)
• CI/CD files (.github/workflows/, .gitlab-ci.yml, etc.)

Step 3: Identify Project Type and Tech Stack

Based on the repository scan, determine:

• Project type: Library, application, framework, tool, service, etc.
• Primary language(s): JavaScript/TypeScript, Python, Rust, Go, Java, etc.
• Framework/runtime: React, Vue, Django, FastAPI, Express, Next.js, etc.
• Package manager: npm, yarn, pnpm, pip, cargo, go modules, maven, gradle
• Key dependencies: Read package files to identify major dependencies

Step 4: Analyze Key Files

Read and analyze critical files to extract information:

1. Package/dependency files - Extract:

• Project name and version
• Description
• Main dependencies
• Scripts/commands
• Entry points

1. License file - Identify license type

1. Configuration files - Understand:

• Required environment variables
• Configuration structure

1. Main source files - Understand:

• Entry points
• Core functionality
• Architecture patterns

1. Existing README (if present) - Extract:

• Current description
• Features mentioned
• Any special notes

Step 5: Identify Special Features

Look for and document:

• API endpoints (scan for route definitions)
• CLI commands (look for CLI frameworks, argument parsers)
• Database usage (ORMs, database clients)
• Authentication/authorization
• Testing frameworks
• Deployment configurations
• Docker support
• CI/CD pipelines
• Monitoring/logging setup

Phase 2: Content Generation

Goal: Generate comprehensive README content following best practices.

README Structure

Generate a README with these sections (adjust based on project type):

1. Title & Badges (if applicable)

• Project name
• Relevant badges (build status, version, license, etc.)

1. Description

• Clear, concise project description
• What problem it solves
• Key features/capabilities (3-5 bullet points)

1. Table of Contents (for longer READMEs)

1. Prerequisites

• Required software versions
• System requirements
• Dependencies to install globally

1. Installation

• Step-by-step installation instructions
• Platform-specific notes if needed
• Example commands

1. Configuration (if applicable)

• Environment variables
• Configuration file examples
• Setup instructions

1. Usage

• Basic usage examples
• Common use cases
• Code snippets
• CLI command examples
• API usage examples

1. Development

• How to set up development environment
• Running tests
• Build process
• Development server commands

1. API Documentation (if applicable)

• Key endpoints
• Request/response examples
• Authentication details

1. Project Structure (optional, for complex projects)

• Directory layout explanation
• Key files and their purposes

1. Contributing (if applicable)

• How to contribute
• Code style guidelines
• PR process

1. Testing

• How to run tests
• Test coverage information
• Testing frameworks used

1. Deployment (if applicable)

• Deployment instructions
• Environment setup
• Platform-specific guidance

1. Built With

• Major technologies
• Key frameworks
• Important libraries

1. License

• License type
• Link to LICENSE file

1. Authors/Contributors (if identifiable)

1. Acknowledgments (optional)

Content Guidelines

Writing Style:

• Clear, concise, and professional
• Use active voice
• Provide concrete examples
• Include actual commands users can copy/paste
• Explain why, not just what

Code Examples:

• Use proper syntax highlighting
• Include comments for clarity
• Show realistic, working examples
• Provide both basic and advanced examples when relevant

Commands:

• Always use code blocks for commands
• Show expected output when helpful
• Include alternative commands for different platforms if needed

Completeness:

• Every section should be actionable
• No placeholder text like "TODO" or "Coming soon"
• If information is unknown, either research it or omit the section

Phase 3: README Creation

Step 1: Generate README Content

Create the complete README content with all identified sections. Ensure:

• All code blocks use proper markdown syntax with language tags
• All links are functional
• All commands are accurate
• Examples are realistic and testable

Step 2: Create README.md File

Write the README.md to the repository root:

# Create README.md in repository root

Use create_file to write the README.md at [repo_path]/README.md.

Step 3: Validation

After creating the README:

1. Verify the file was created successfully
2. Check that all links are properly formatted
3. Ensure code blocks are properly formatted
4. Validate that commands are correct for the project

Step 4: Present to User

Show the user:

• Confirmation that README.md was created
• Location of the file
• Brief summary of what was included
• Suggestions for customization (if any)

Offer to:

• Make adjustments to any section
• Add additional sections
• Clarify any content
• Generate additional documentation files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc.)

Best Practices

Modern README Standards

Follow these contemporary README best practices:

1. Start with a hook - Immediately explain what the project does and why it matters
2. Show, don't tell - Include screenshots, GIFs, or code examples early
3. Progressive disclosure - Basic info first, advanced details later
4. Action-oriented - Focus on what users can DO
5. Copy-pasteable - All commands should be ready to use
6. Platform-aware - Note OS-specific requirements
7. Keep it current - Only include information that's accurate and maintained

Section-Specific Guidelines

Installation:

• Start with the quickest path to getting started
• Separate quick start from comprehensive setup
• Include troubleshooting for common issues

Usage:

• Show the simplest example first
• Build up to complex examples
• Include common pitfalls and solutions

Development:

• Make it easy for contributors to get started
• Document the development workflow
• Explain the architecture if complex

API Documentation:

• Keep it concise in the README
• Link to full API docs if available
• Show realistic request/response examples

Quality Markers

A state-of-the-art README should:

• Be readable in under 5 minutes
• Get users from zero to running in under 10 minutes
• Answer common questions preemptively
• Have zero ambiguity in instructions
• Include visual aids when helpful
• Work for both beginners and advanced users
• Be maintainable and easy to update

Handling Edge Cases

No package files found:

• Analyze source code directly
• Look for import statements to identify dependencies
• Document setup steps generically

Multiple languages/technologies:

• Create sections for each major component
• Clearly separate setup instructions
• Use subsections effectively

Large/complex repository:

• Focus on getting started quickly
• Link to detailed documentation
• Provide a project structure overview
• Create additional documentation files if needed

Unclear purpose:

• Ask user for clarification
• Read through main source files more carefully
• Check for documentation comments in code
• Ask about the project's goals and use cases

Existing README is comprehensive:

• Ask if user wants to update/improve it or start fresh
• Offer specific improvements (better examples, clearer instructions, etc.)
• Respect existing structure and voice while enhancing clarity

User Interaction

Throughout the process:

• Keep user informed of progress ("Scanning repository structure...")
• Ask for clarification when needed
• Offer options when multiple approaches are valid
• Show enthusiasm for their project
• Provide helpful suggestions beyond the README

After completion:

• Offer to create related documentation (CONTRIBUTING.md, CHANGELOG.md, etc.)
• Suggest improvements to project structure if observed
• Recommend tools or practices that could help
• Ask if they want badges added (GitHub Actions, npm version, etc.)

Technical Implementation Notes

File Reading:

• Use view for reading file contents
• For binary files or very large files, use bash_tool with appropriate commands
• Respect .gitignore patterns when scanning

Path Handling:

• Always use absolute paths
• Handle spaces in filenames properly
• Support both Unix and Windows path conventions

Error Handling:

• Gracefully handle missing files
• Provide helpful errors for permission issues
• Suggest solutions for common problems

Performance:

• Don't read extremely large files entirely
• Limit directory traversal depth for huge repositories
• Sample files if there are too many to analyze