README Env Table Sync

Generate and sync a README environment-variable table from .env.example using marker blocks, with drift detection for CI.

Security Scan

The skill is internally consistent: it parses a .env template and updates a marked README block using only local file access (bash + python3) and does not request unrelated credentials or network access.

Purpose & Capability

Name/description match the included script and SKILL.md: the tool only needs bash and python3 to parse an env template and update a README marker block. Nothing requested or included (no extra binaries, no credentials) is out of scope for this purpose.

Instruction Scope

Runtime instructions and the embedded Python script only read the specified ENV_FILE and README_FILE, compare/generate a markdown table, and optionally overwrite the README between provided markers. No other files, environment secrets, or network endpoints are accessed.

Install Mechanism

Instruction-only skill with no install spec and one bundled script; nothing is downloaded or installed. This is low-risk and proportional for the task.

Credentials

No required environment variables, credentials, or config paths are declared. The optional runtime variables (ENV_FILE, README_FILE, SYNC_MODE, markers) are appropriate and sufficient for operation.

Persistence & Privilege

Skill does not request always:true or any persistent/system-wide privileges. It will only modify the README file when run with SYNC_MODE=apply, which is expected behavior for a sync tool.

Assessment

This script is straightforward: it reads the env template and README you point it at and will overwrite the README block between your start/end markers when run with SYNC_MODE=apply. Before using apply in a repository, ensure you run it from the repo root (or set ENV_FILE/README_FILE to the correct paths), verify the markers exist, and review changes (e.g., via git diff) before committing. No network or credential access is performed by the skill; the main risk is accidental overwriting of README content if markers are mis-specified—keep backups or use version control to revert if needed.

Use this skill to keep README environment-variable docs aligned with the real .env.example file.

What this skill does

• Parses env keys from .env.example (or another env template file)
• Generates a markdown table with key/default values
• Detects doc drift by comparing generated table with the README marker block
• Optionally applies the update directly into README

Inputs

Optional:

• ENV_FILE (default: .env.example)
• README_FILE (default: README.md)
• SYNC_MODE (report or apply, default: report)
• TABLE_START_MARKER (default: <!-- ENV_TABLE_START -->)
• TABLE_END_MARKER (default: <!-- ENV_TABLE_END -->)

Run

Drift report (CI-friendly):

ENV_FILE=.env.example \
README_FILE=README.md \
bash skills/readme-env-table-sync/scripts/sync-readme-env-table.sh

Apply sync:

ENV_FILE=.env.example \
README_FILE=README.md \
SYNC_MODE=apply \
bash skills/readme-env-table-sync/scripts/sync-readme-env-table.sh

Run against included fixtures:

ENV_FILE=skills/readme-env-table-sync/fixtures/.env.sample \
README_FILE=skills/readme-env-table-sync/fixtures/README.sample.md \
SYNC_MODE=apply \
bash skills/readme-env-table-sync/scripts/sync-readme-env-table.sh

Output contract

• Exit 0 when table is already in sync (report) or update is applied (apply)
• Exit 1 on invalid inputs, missing markers, parse errors, or detected drift in report mode
• Prints a short summary with key count and mode