runbook-generator

Generate operational runbooks from project files. Scans Dockerfiles, docker-compose.yml, systemd units, Makefiles, package.json, and config files to produce...

Security Scan

The skill's code and instructions match its stated purpose (scanning project infra files to generate runbooks); it requests no credentials, has no installer, and uses only Python stdlib, but it does read potentially sensitive local files (like .env) so exercise caution when pointing it at production directories.

Purpose & Capability

Name/description, SKILL.md, STATUS.md, and the included Python scanner are consistent: the tool scans Dockerfiles, docker-compose.yml, systemd units, Makefiles, package.json, .env, nginx.conf and generates runbooks. No unrelated binaries or credentials are requested.

Instruction Scope

The runtime instructions explicitly ask the agent/user to point the script at a project directory; the script reads many infrastructure files (including .env and systemd units). The script masks .env values in its extraction logic, but it still reads those files into memory. Avoid pointing the tool at directories containing production secrets or root/system config unless you trust the code and environment.

Install Mechanism

There is no install spec (instruction-only skill with a bundled Python script). That is low risk; nothing is downloaded or written to system locations by an installer.

Credentials

No environment variables, credentials, or config paths are declared or required. The script does scan .env files in project directories (which is expected for its purpose) and attempts to mask values in .env parsing.

Persistence & Privilege

always is false, the skill is user-invocable and can be autonomously invoked by the agent (default). It does not request permanent presence or modify other skills or system-wide agent settings.

Assessment

This skill appears to do what it says: it scans project infrastructure files and produces runbooks using only Python stdlib. Before running or giving an agent access to it: 1) Review scripts/generate_runbook.py locally to confirm behavior (no network calls or subprocesses were seen in the visible code). 2) Run it on a copy of your repo or in an isolated environment, especially if the project contains production secrets — the script reads .env and systemd unit files (it attempts to mask .env values but still reads them). 3) If you plan to allow autonomous agent invocation, consider restricting which directories the agent can point it to and avoid exposing host-level/system directories. 4) If you need stronger guarantees, ask the owner for source provenance or audit the rest of the file (the provided file was truncated in the review text); absence of detected network calls in the shown code is reassuring, but verify the full file before trusting it with sensitive projects.

Generate operational runbooks by scanning project infrastructure files. Produces structured Markdown runbooks with procedures for common ops tasks.

Quick Generate

python3 scripts/generate_runbook.py /path/to/project

Output Formats

# Markdown (default)
python3 scripts/generate_runbook.py /path/to/project

# JSON (structured)
python3 scripts/generate_runbook.py /path/to/project --format json

# Specific output file
python3 scripts/generate_runbook.py /path/to/project -o RUNBOOK.md

What It Scans

File	What It Extracts
Dockerfile	Base image, exposed ports, entrypoint, build steps
docker-compose.yml	Services, ports, volumes, dependencies, env vars
systemd units (.service)	ExecStart/Stop/Reload, dependencies, restart policy
Makefile	Targets (build, test, deploy, clean, etc.)
package.json	Scripts (start, build, test, dev, deploy)
.env / .env.example	Required environment variables
nginx.conf	Upstream servers, listen ports, locations

Generated Sections

1. Overview — Service name, description, tech stack
2. Prerequisites — Required tools, access, credentials
3. Environment Variables — Required vars with descriptions
4. Build — How to build the project
5. Deploy — Step-by-step deployment procedure
6. Start/Stop/Restart — Service lifecycle commands
7. Health Check — How to verify the service is running
8. Rollback — How to revert to previous version
9. Troubleshooting — Common issues and solutions
10. Monitoring — Logs, metrics, alerts
11. Contacts — On-call, escalation (template)

Workflow

1. User points to a project directory
2. Script scans for infrastructure files
3. Extracts operational information
4. Generates structured runbook
5. Present to user for review and customization