Readme Creator

README Creator

This skill guides agents in creating and updating comprehensive README files that follow the autonomous-bits development standards.

When to Use This Skill

Use this skill when:

• Creating a new project or repository
• Updating existing README files to meet current standards
• Reviewing README completeness and quality
• Ensuring consistent documentation across projects
• Asked to "create a README", "update docs", or "improve documentation"

Prerequisites

• Access to the project repository
• Understanding of the project's purpose and architecture
• Knowledge of project dependencies and setup requirements
• Access to related documentation (CONTRIBUTING.md, CHANGELOG.md, etc.)

Instructions

1. Assess Current State

Check for existing README:

• Read the current README.md if it exists
• Identify missing sections
• Note outdated information
• Review against the checklist below

2. Create README Structure

Use this essential sections checklist:

1. Project Name and One-Line Description

   • Clear, concise title at the top
   • Brief summary (1-2 sentences) of what the project does
   • Example: "A Nomos provider that reads Terraform/OpenTofu remote state files"

2. Purpose and Overview

   • Why does this project exist?
   • What problem does it solve?
   • High-level architecture or approach

3. Prerequisites and Supported Platforms

   • Required software with specific versions (e.g., "Go 1.25+")
   • Operating system requirements
   • Development tools (Docker, Make, etc.)
   • External dependencies

4. Installation and Setup Steps

   • Clone repository command
   • Dependency installation (e.g., make deps, npm install)
   • Initial configuration steps
   • Database/service setup if needed

5. Configuration

   • Environment variables with descriptions
   • Configuration files and their purposes
   • Secrets management (never include actual secrets)
   • Feature flags if applicable
   • Example: Create .env.example reference

6. How to Run Locally

   • Development server commands
   • Build commands (e.g., make build)
   • Run commands (e.g., make run, npm start)
   • Port information and access URLs

7. How to Run Tests and Linters

   • Unit test commands (e.g., make test, go test ./...)
   • Integration test commands with any required tags
   • Linting and formatting (e.g., make verify, npm run lint)
   • Coverage requirements (e.g., "80%+ coverage required")
   • Race detection commands (e.g., go test -race)

8. Deployment Instructions

   • Deployment process overview
   • CI/CD pipeline information
   • Environment-specific considerations
   • Release process and versioning

9. Basic Usage Examples

   • Common use cases with code examples
   • CLI command examples with expected output
   • API usage snippets
   • Configuration examples

10. Links to Further Documentation

    • Architecture decision records (ADRs)
    • API documentation
    • Design documents
    • Contributing guidelines (CONTRIBUTING.md)
    • Changelog (CHANGELOG.md)
    • Related repositories

11. Contact/Owner Information

    • Project maintainers or team name
    • How to get support
    • Issue tracker URL
    • Communication channels (Slack, Discord, etc.)

3. Apply Language-Specific Guidelines

For Go Projects:

## Prerequisites

- Go 1.25+
- Make
- Docker (optional)

## Installation

\```bash
git clone <repository-url>
cd <project-name>
make deps && make tidy
\```

## Testing

\```bash
make test              # Unit tests (80%+ coverage required)
make verify            # fmt + vet + lint + test
go test -race ./...    # Run with race detection
\```

For TypeScript/Node.js Projects:

## Prerequisites

- Node.js 20+
- npm or yarn

## Installation

\```bash
npm install
\```

## Development

\```bash
npm run dev          # Start dev server
npm run build        # Production build
npm test             # Run tests
npm run lint         # Run linter
\```

For Python Projects:

## Prerequisites

- Python 3.11+
- pip or poetry

## Installation

\```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
\```

## Testing

\```bash
pytest                 # Run tests
pytest --cov          # With coverage
\```

4. Include Examples and Code Blocks

Always provide:

• Actual command examples users can copy-paste
• Expected output where helpful
• Configuration file snippets
• API usage examples

Example:

## Usage

### Starting the Provider

\```bash
# Set environment variables
export BACKEND_TYPE=local
export STATE_FILE=/path/to/terraform.tfstate

# Run the provider
./bin/nomos-provider-terraform-remote-state
\```

The provider will print:
\```
PROVIDER_PORT=50051
\```

5. Add Best Practices Section

Include project-specific best practices:

## Best Practices

- Always run `make verify` before committing
- Keep test coverage above 80%
- Update CHANGELOG.md with every release
- Follow conventional commit format (see commit-messages.md)
- Never commit secrets or credentials

6. Reference Related Standards

Link to other standard documents:

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.

- **Commit Messages**: Follow [commit message standards](./commit-messages.md)
- **Code Review**: See [development standards](./CONTRIBUTING.md#code-review)
- **Architecture**: Review [architecture docs](./docs/architecture/)

7. Validate README Completeness

Quality checklist:

• All 11 essential sections present
• Commands are tested and work correctly
• No hardcoded secrets or credentials
• Links are valid and up-to-date
• Code examples are accurate
• Platform-specific instructions included
• Prerequisites clearly listed with versions
• Troubleshooting section for common issues (if applicable)

8. Keep README Maintainable

Best practices:

• Keep it concise - link to detailed docs instead of duplicating
• Test all documented commands
• Update with breaking changes immediately
• Use relative links for repo files
• Include "Last Updated" date if helpful
• Place README at repository root

Examples

Minimal Go Project README

# Project Name

Brief one-line description of what this project does.

## Prerequisites

- Go 1.25+
- Make

## Installation

\```bash
git clone <repo-url>
cd <project-name>
make deps
\```

## Running Tests

\```bash
make test              # 80%+ coverage required
make verify            # Complete validation
\```

## Usage

\```bash
make build
./bin/<binary-name>
\```

## Documentation

- [Architecture](./docs/architecture.md)
- [Contributing](./CONTRIBUTING.md)
- [Changelog](./CHANGELOG.md)

## Contact

- Team: [Team Name]
- Issues: [GitHub Issues URL]

README with Configuration Example

## Configuration

Create a `.env` file or set environment variables:

\```bash
# Backend Configuration
BACKEND_TYPE=azure           # Options: local, azure
STORAGE_ACCOUNT=myaccount    # Required for Azure
CONTAINER_NAME=tfstate       # Required for Azure
STATE_PATH=prod.tfstate      # Path within backend

# Optional Settings
LOG_LEVEL=info               # Options: debug, info, warn, error
PORT=50051                   # gRPC port (default: auto-assign)
\```

See [.env.example](./.env.example) for complete configuration options.

Best Practices

Do's ✅

• Start with the essential 11 sections
• Include working, tested commands
• Provide concrete examples
• Link to detailed documentation
• Keep it updated with code changes
• Use clear, imperative language
• Test all instructions as a new user would

Don'ts ❌

• Don't include actual secrets or credentials
• Don't duplicate extensive documentation (link instead)
• Don't use vague instructions ("install dependencies")
• Don't forget to update after breaking changes
• Don't assume prior knowledge without prerequisites
• Don't leave outdated information
• Don't make it too verbose

Troubleshooting

Issue: README is too long and overwhelming Solution: Move detailed content to docs/ folder and link from README

Issue: Commands don't work on different platforms Solution: Include platform-specific instructions or use cross-platform tools

Issue: README gets outdated quickly Solution: Add README updates to your PR checklist and CI validation

Resources

• README Guidelines
• Project Structure Standards
• Go Development Standards
• Commit Message Standards