readme-generation

main@e655f93
Download ZIP
SpecterOps/skills/plugins/workflows-development/skills/readme-generation
npx skills add SpecterOps/skills --skill readme-generation
SKILL.md
namereadme-generation
descriptionGenerate a professional README.md for a project. Works on local codebases and remote GitHub repos. Use when a project needs a README, when an existing README is outdated, or when documenting someone else's tool.
metadata{"author":"GhostWorks"}

README Generator

Analyze a codebase and produce a complete, professional README.md.

Parse the user's input to determine:

  • Target: a local path, a remote GitHub repo (e.g., fortra/impacket), or current directory (default)
  • Style: security-tool, library, cli, webapp, minimal, or auto-detect (default)
  • Update mode: if the user says "update" or the project already has a README, preserve custom sections

Common patterns:

  • $readme-generation → generate for current directory, auto-detect style
  • $readme-generation ~/projects/mytool → generate for local path
  • $readme-generation fortra/impacket → clone and generate for remote repo
  • $readme-generation --style security-tool → force a specific style
  • $readme-generation --update → update existing README, keeping custom sections

Steps

1. Acquire the codebase

  • If a remote repo is given: gh repo clone owner/repo /tmp/readme-target and work from there
  • If a local path is given: use that directory
  • Otherwise: use current working directory

2. Deep scan the project

Read and analyze these files (skip any that don't exist):

Project metadata:

  • pyproject.toml, setup.py, setup.cfg — Python project info, dependencies, entry points
  • Cargo.toml — Rust project info
  • go.mod — Go module info
  • package.json — Node.js project info
  • Makefile, Justfile — Build commands
  • Dockerfile, docker-compose.yml — Container setup
  • .github/workflows/ — CI/CD configuration

Source code (sample, don't read everything):

  • Entry points: main.py, cli.py, main.go, main.rs, src/main.*, cmd/
  • Top-level source files for imports and structure
  • CLI argument definitions (argparse, typer, cobra, clap)
  • Config file examples

Existing docs:

  • Current README.md (if updating)
  • CONTRIBUTING.md, CHANGELOG.md, LICENSE
  • docs/ directory contents

Git context:

  • git log --oneline -30 — recent activity and feature descriptions
  • git tag --sort=-v:refname | head -5 — version history
  • git remote -v — origin URL

3. Determine project type and style

Auto-detect from user input or infer:

Signal Type
nmap/scanning/enum imports, --target flags security-tool
Library with no CLI, published to PyPI/crates library
CLI with subcommands, --help output cli
Web framework (Flask, FastAPI, Express, Next.js) webapp
Few files, single purpose minimal

4. Generate README using the appropriate template

Security Tool Template

# [Name]

[One-line description of what it does and why you'd use it]

## Features

- [Key capability 1]
- [Key capability 2]
- [Key capability 3]

## Installation

[Package manager install or build from source — include both if applicable]

## Quick Start

```bash
[Single command showing the most common usage]

Usage

[Full --help output or manual command reference]

Examples

# [Description of scenario 1]
[command]

# [Description of scenario 2]
[command]

# [Description of scenario 3]
[command]

Output Formats

[If the tool supports multiple output formats, show examples of each]

Requirements

  • [Runtime dependencies]
  • [System requirements]
  • [Required access/permissions]

Building from Source

[Build steps]

License

[License type and link]


#### Library Template
```markdown
# [Name]

[One-line description]

## Installation

```bash
[pip install / cargo add / go get command]

Quick Start

[Minimal working example — 5-10 lines]

API Reference

[Module/Class Name]

function_name(params) -> return_type

[Description and example]

Configuration

[Config options if applicable]

Contributing

[How to contribute, run tests, submit PRs]

License

[License]


#### CLI Template
```markdown
# [Name]

[One-line description]

## Installation

```bash
[Install command]

Usage

[Command syntax overview]

Commands

command-name

[Description, flags, example]

Configuration

[Config file location and format if applicable]

Examples

[2-3 real-world usage scenarios]

License

[License]


#### Webapp Template
```markdown
# [Name]

[One-line description]

## Tech Stack

- [Frontend framework]
- [Backend framework]
- [Database]
- [Deployment]

## Getting Started

### Prerequisites

[Required software and versions]

### Setup

```bash
[Clone, install deps, configure, run — step by step]

Environment Variables

Variable Description Default
VAR_NAME What it does default

Development

[Dev server, test, lint commands]

Deployment

[How to deploy]

License

[License]


#### Minimal Template
```markdown
# [Name]

[One-line description]

## Usage

```bash
[Primary usage command]

Install

[Install steps]

License

[License]


### 5. Writing guidelines

- **First line matters most** — the description after `# Name` should explain what the tool does AND why someone would use it, in one sentence
- **Show, don't tell** — real command examples over descriptions of what's possible
- **Copy-pasteable** — every code block should work if pasted into a terminal
- **No filler** — skip badges, excessive formatting, or sections with no content
- **Accurate dependencies** — only list what's actually required, pulled from the project files
- **Version-aware** — if the project has tags, reference the latest version in install commands

### 6. Update mode

When updating an existing README (user said "update" or `--update`):

1. Read the existing README fully
2. Identify **custom sections** — any section not in the standard template (acknowledgments, special notes, contributor lists, etc.)
3. Regenerate the standard sections with current project data
4. **Preserve custom sections in their original position** — do not delete or rewrite them
5. If a standard section has user-added content beyond what the template provides (e.g., extra examples), keep the user additions and only update the generated parts
6. Show a diff summary of what changed before writing

### 7. Output

- Write the README to the project directory
- If working on a remote repo in `/tmp/`, also copy the output to the current directory as `README-[project-name].md`
- Report the file path and a brief summary of what was generated