Broklam/readme-constructor

README constructor

Build a README that fits the project and its readers. Treat the user as the designer. Presets are proposals, and structure, content, and visuals are independent choices. Use project evidence and the user's existing decisions. Never invent features, commands, results, images, or claims.

Discover and propose

Inspect the relevant repository, existing documentation, source of generated documentation, and assets before proposing a recipe. Identify the README's purpose, intended audience, title, tone, and rendering target when these affect the design. Respect a requested output path or chat-only draft. Edit the documentation source when the output is generated. Preserve useful facts and existing assets, especially for an existing README.

Use the menus below selectively. Their patterns offer choices for the user to adapt. Their linked examples are a representative subset selected from the Awesome README index, summarized in short original notes. No network access is required to use the skill.

• Use the structure menu to propose an ordered starting point and section choices.
• Use the section content menu to choose the format, depth, and evidence for each selected section.
• Use the visuals menu to choose individual visuals, placement, and available or proposed assets.

For a new README or major redesign, present one tailored, editable recipe that shows the proposed heading order, a content choice for each section, and any individually placed visuals. Include brief context choices only where they remain material. In a compact menu use stable IDs so the user can add, remove, rename, or reorder sections, choose their content independently, and opt into individual visuals. Offer none, keep, skip, recommend, and free-form choices where applicable. Explain that recommend delegates the choice. Let the user decide content and visuals independently of a preset.

Consume choices the user has already given and keep them when revising the recipe. When keep selects an existing item in a redesign, preserve and apply that item. Ask only for unresolved design choices, grouped into a manageable message. Wait for those choices before drafting a new or substantially redesigned README unless the user has delegated the decisions. If the user gave sufficient direction or asked you to decide, proceed with suitable defaults. Once choices are resolved, make the requested deliverable without seeking another approval. For narrow edits, carry out the user's request directly without a new constructor session.

Adapt this compact exchange to the project.

Proposed order is S1 Overview → S2 Quickstart → S3 Architecture. Content choices are S1 problem + scope, S2 minimal commands, and S3 plain-text component map. Visual choices are V1 screenshot after S1 (proposed, none available) and V2 architecture diagram after S3 (proposed). Choose sections and order, change any section's content, and choose visuals individually. keep accepts the specific proposed value, none removes a section or visual, skip leaves an optional choice out, and recommend delegates it. Custom text is welcome.

User chooses order S1, S3, S2 / S2 guided / V1 none / V2 keep / keep the rest.

The resulting recipe retains S1 and S3's content, uses guided quickstart for S2, omits V1, and places V2 after S3. Resolve any remaining material uncertainty without reopening accepted choices. Distinguish proposed assets from existing assets. Make or obtain a proposed asset only within the user's requested scope and available tools, or omit it and explain the gap.

Produce and check

Write sections to the chosen recipe and support specifics from the project. Verify commands safely where practical. Label unverified commands or missing information, and avoid executing destructive or side-effectful commands merely to test documentation. Check heading order and links, anchors, Markdown rendering for the chosen platform, code fences and language tags, and relative asset paths. Give informative alt text to meaningful images, and check legibility in light and dark themes when visuals are used. Preserve existing content outside the requested scope. Report material gaps and verification limits with the result.