README blueprint generator
Analyze repository guidance and project documentation, extract the facts a new developer or user needs, and produce a concise, well-structured README.md with high-level architecture, cross-references, Markdown formatting, and no invented project claims.
When to invoke
- "Generate a README for this repository."
- "Create a README.md from our GitHub Copilot docs."
- "Build a README blueprint from .github/copilot."
- "Refresh the README with architecture, stack, workflow, and tests."
- "Use copilot-instructions.md to document this project."
Source inventory
Scan the repository for these sources, using available files as evidence and noting gaps rather than inventing content:
| Source |
Extract |
.github/copilot/Architecture |
Project architecture, major components, diagrams, runtime boundaries. |
.github/copilot/Code_Exemplars |
Contribution examples, conventions, patterns worth linking. |
.github/copilot/Coding_Standards |
Naming, formatting, review, and implementation rules. |
.github/copilot/Project_Folder_Structure |
Directory map and ownership of major folders. |
.github/copilot/Technology_Stack |
Languages, frameworks, tools, and versions when available. |
.github/copilot/Unit_Tests |
Test framework, commands, coverage expectations, fixtures. |
.github/copilot/Workflow_Analysis |
Branching, PR flow, release, CI, and development workflow. |
.github/copilot-instructions.md or .github/copilot-instructions.md equivalent |
Repository-wide instructions and conventions. |
Existing README.md, package manifests, workflow files |
Fill missing setup, commands, badges, and license facts only when evidenced. |
README sections
| Section |
Required content |
Primary source |
| Project name and description |
Project name, purpose, and what it does. |
Existing README, manifests, architecture docs. |
| Technology stack |
Languages, frameworks, services, versions when available. |
Technology_Stack. |
| Project architecture |
High-level architecture and simple diagram if already described. |
Architecture. |
| Getting started |
Prerequisites, installation, setup, configuration, first run. |
Stack docs, manifests, existing scripts. |
| Project structure |
Brief folder overview. |
Project_Folder_Structure. |
| Key features |
Main functionality and user/developer value. |
Architecture and project docs. |
| Development workflow |
Branching, PR, CI, release, and local workflow. |
Workflow_Analysis. |
| Coding standards |
Project-specific conventions. |
Coding_Standards, copilot-instructions.md. |
| Testing |
Test approach, commands, and tools. |
Unit_Tests, package scripts, workflows. |
| Contributing |
How to contribute and where exemplars live. |
Code_Exemplars, instructions. |
| License |
License name or "Not specified" if no evidence exists. |
LICENSE, package metadata, existing docs. |
Generation rules
- Prefer facts from documentation over guesses from code shape.
- Include version information only when a source states it.
- Use badges only when build status, package version, coverage, or license data is available.
- Include links to repository-local documentation files when they exist and are useful.
- Keep the README concise yet informative; optimize for a new developer's first successful setup.
- Use clear headings, subheadings, lists, tables, and fenced code blocks for commands.
- If a source file is missing, omit the unsupported detail or add a short "Not documented yet" note only when the gap matters.
Gotchas
- Do not fabricate setup commands: derive commands from manifests, scripts, or existing docs.
- Do not overfit to
.github/copilot names: some repositories may use equivalent documentation; preserve source evidence.
- Do not turn README into an architecture spec: link deeper docs and keep the README navigational.
- Do not include empty badges or placeholder links: every badge and link must resolve to real repository content.
Output template
# <Project Name>
<One-paragraph description of what the project does and who it is for.>
## Technology stack
| Area | Technology | Version/source |
| --- | --- | --- |
| <area> | <tool/framework> | <version or source file> |
## Architecture
<High-level architecture summary.>
## Getting started
### Prerequisites
- <requirement>
### Install
```bash
<install command>
Run
<run command>
Project structure
Key features
Development workflow
Coding standards
Testing
<test command>
Contributing
License
<license or "Not specified in repository files.">
## Quality gate
- [ ] `.github/copilot` and `copilot-instructions.md` sources were scanned when present.
- [ ] Architecture, technology stack, project structure, workflow, standards, tests, exemplars, and license are either documented or explicitly omitted for lack of evidence.
- [ ] Commands, versions, badges, and links are backed by repository files.
- [ ] The README is concise, developer-focused, and formatted as valid Markdown.
- [ ] No unsupported project claims or placeholder sections remain.
1---2name: readme-blueprint-generator3description: Generate a comprehensive README.md blueprint by analyzing repository documentation, .github/copilot files, copilot-instructions.md, architecture notes, technology stack, workflow, standards, tests, and exemplars. Use when asked to create or refresh a developer-focused README.4---56<!-- Generated from harness/github-copilot/skills/readme-blueprint-generator/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# README blueprint generator910Analyze repository guidance and project documentation, extract the facts a new developer or user needs, and produce a concise, well-structured `README.md` with high-level architecture, cross-references, Markdown formatting, and no invented project claims.1112## When to invoke1314- "Generate a README for this repository."15- "Create a README.md from our GitHub Copilot docs."16- "Build a README blueprint from .github/copilot."17- "Refresh the README with architecture, stack, workflow, and tests."18- "Use copilot-instructions.md to document this project."1920## Source inventory2122Scan the repository for these sources, using available files as evidence and noting gaps rather than inventing content:2324| Source | Extract |25| --- | --- |26| `.github/copilot/Architecture` | Project architecture, major components, diagrams, runtime boundaries. |27| `.github/copilot/Code_Exemplars` | Contribution examples, conventions, patterns worth linking. |28| `.github/copilot/Coding_Standards` | Naming, formatting, review, and implementation rules. |29| `.github/copilot/Project_Folder_Structure` | Directory map and ownership of major folders. |30| `.github/copilot/Technology_Stack` | Languages, frameworks, tools, and versions when available. |31| `.github/copilot/Unit_Tests` | Test framework, commands, coverage expectations, fixtures. |32| `.github/copilot/Workflow_Analysis` | Branching, PR flow, release, CI, and development workflow. |33| `.github/copilot-instructions.md` or `.github/copilot-instructions.md` equivalent | Repository-wide instructions and conventions. |34| Existing `README.md`, package manifests, workflow files | Fill missing setup, commands, badges, and license facts only when evidenced. |3536## README sections3738| Section | Required content | Primary source |39| --- | --- | --- |40| Project name and description | Project name, purpose, and what it does. | Existing README, manifests, architecture docs. |41| Technology stack | Languages, frameworks, services, versions when available. | `Technology_Stack`. |42| Project architecture | High-level architecture and simple diagram if already described. | `Architecture`. |43| Getting started | Prerequisites, installation, setup, configuration, first run. | Stack docs, manifests, existing scripts. |44| Project structure | Brief folder overview. | `Project_Folder_Structure`. |45| Key features | Main functionality and user/developer value. | Architecture and project docs. |46| Development workflow | Branching, PR, CI, release, and local workflow. | `Workflow_Analysis`. |47| Coding standards | Project-specific conventions. | `Coding_Standards`, `copilot-instructions.md`. |48| Testing | Test approach, commands, and tools. | `Unit_Tests`, package scripts, workflows. |49| Contributing | How to contribute and where exemplars live. | `Code_Exemplars`, instructions. |50| License | License name or "Not specified" if no evidence exists. | `LICENSE`, package metadata, existing docs. |5152## Generation rules5354- Prefer facts from documentation over guesses from code shape.55- Include version information only when a source states it.56- Use badges only when build status, package version, coverage, or license data is available.57- Include links to repository-local documentation files when they exist and are useful.58- Keep the README concise yet informative; optimize for a new developer's first successful setup.59- Use clear headings, subheadings, lists, tables, and fenced code blocks for commands.60- If a source file is missing, omit the unsupported detail or add a short "Not documented yet" note only when the gap matters.6162## Gotchas6364- **Do not fabricate setup commands**: derive commands from manifests, scripts, or existing docs.65- **Do not overfit to `.github/copilot` names**: some repositories may use equivalent documentation; preserve source evidence.66- **Do not turn README into an architecture spec**: link deeper docs and keep the README navigational.67- **Do not include empty badges or placeholder links**: every badge and link must resolve to real repository content.6869## Output template7071```markdown72# <Project Name>7374<One-paragraph description of what the project does and who it is for.>7576## Technology stack7778| Area | Technology | Version/source |79| --- | --- | --- |80| <area> | <tool/framework> | <version or source file> |8182## Architecture8384<High-level architecture summary.>8586## Getting started8788### Prerequisites89- <requirement>9091### Install92```bash93<install command>94```9596### Run97```bash98<run command>99```100101## Project structure102103| Path | Purpose |104| --- | --- |105| `<path>` | <purpose> |106107## Key features108109- <feature>110111## Development workflow112113<workflow summary>114115## Coding standards116117- <standard>118119## Testing120121```bash122<test command>123```124125## Contributing126127<contribution guidance and links to exemplars>128129## License130131<license or "Not specified in repository files.">132```133134## Quality gate135136- [ ] `.github/copilot` and `copilot-instructions.md` sources were scanned when present.137- [ ] Architecture, technology stack, project structure, workflow, standards, tests, exemplars, and license are either documented or explicitly omitted for lack of evidence.138- [ ] Commands, versions, badges, and links are backed by repository files.139- [ ] The README is concise, developer-focused, and formatted as valid Markdown.140- [ ] No unsupported project claims or placeholder sections remain.
paulasilvatech