enhancement: add readme-maintainer skill and update readme#2710
Conversation
There was a problem hiding this comment.
Pull request overview
Updates repository documentation and adds an agent “skill” file intended to keep README.md aligned with the repo’s current tooling and structure.
Changes:
- Rewrites
README.mdto a more structured, compliance-oriented format (project metadata, status, features, setup, testing, security). - Adds a new
.agents/skills/readme-maintainer/SKILL.mddescribing an “accuracy-first” process for maintainingREADME.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| README.md | Replaces the legacy README with an updated, structured overview and updated commands aligned to current Yarn/Lerna scripts. |
| .agents/skills/readme-maintainer/SKILL.md | Introduces a new agent skill definition intended to guide future README maintenance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Before you begin, ensure you have the following installed: | ||
|
|
||
| - Node.js. This repo does not pin a version in `.nvmrc` or `.node-version`; use a version compatible with the checked-in Vite 7, Storybook 10, and Yarn-based toolchain. |
There was a problem hiding this comment.
The prerequisites say to use a Node version "compatible with" the toolchain, but the repo’s CI explicitly uses Node 20 (see .github/workflows/*). To reduce setup friction and avoid subtle incompatibilities, please document the recommended Node major version (e.g., Node 20.x) here.
| - Node.js. This repo does not pin a version in `.nvmrc` or `.node-version`; use a version compatible with the checked-in Vite 7, Storybook 10, and Yarn-based toolchain. | |
| - Node.js 20.x. This repo does not pin a version in `.nvmrc` or `.node-version`; for the lowest setup friction and to match the CI environment, use Node 20.x with the checked-in Vite 7, Storybook 10, and Yarn-based toolchain. |
| Run a single package locally: | ||
|
|
||
| ### Tips for creating a new package. | ||
| ```bash | ||
| yarn dev:chart | ||
| yarn dev:dashboard | ||
| yarn dev:data-bite | ||
| yarn dev:data-table | ||
| yarn dev:editor | ||
| yarn dev:filtered-text | ||
| yarn dev:map | ||
| yarn dev:markup-include | ||
| yarn dev:waffle-chart | ||
| ``` |
There was a problem hiding this comment.
This "Run a single package locally" list omits @cdc/embed, but the repo contains that workspace and it has a start script. Either add a yarn dev:embed helper (to match the other packages) or document how to run the embed package so the section is complete/accurate.
| 4. `yarn storybook` | ||
| 5. You will see those configs under "Private" in Storybook | ||
| **Do not open a public GitHub issue for security vulnerabilities.** | ||
|
|
There was a problem hiding this comment.
The Security section warns not to file a public issue but doesn't provide an alternative reporting path. Please add the reporting email (imtech@cdc.gov) or link to the repo’s security reporting process so users know where to send vulnerability reports.
| Please report suspected vulnerabilities privately to [imtech@cdc.gov](mailto:imtech@cdc.gov). |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| -- Initiation | ||
| -- Development | ||
| -- Operations and Maintenance (O\&M) | ||
| -- Retired |
There was a problem hiding this comment.
The list of allowed {Project Status} values is formatted with -- prefixes, which won’t render as a Markdown list. Use standard list markers (e.g., -) so the options are readable and copy/pasteable.
| -- Initiation | |
| -- Development | |
| -- Operations and Maintenance (O\&M) | |
| -- Retired | |
| - Initiation | |
| - Development | |
| - Operations and Maintenance (O\&M) | |
| - Retired |
| - Preserve the existing tone and structure unless a small reorganization improves clarity. | ||
| - Update README.md directly when inaccuracies are found. | ||
| - If a detail depends on external infrastructure and cannot be verified from the repo, keep the wording explicit about that uncertainty. | ||
| - Use the exact markdown outline and section order provided below between "***** START README TEMPLATE *****" and "***** END README TEMPLATE *****": |
There was a problem hiding this comment.
This skill says to "Prefer minimal changes" but also requires using an exact, much larger README template/section order. Since the current README.md doesn’t match that template, this will push the agent toward large rewrites even for small accuracy fixes. Consider either relaxing the "exact template" requirement or updating the template to reflect the current README’s intended structure.
| - Use the exact markdown outline and section order provided below between "***** START README TEMPLATE *****" and "***** END README TEMPLATE *****": | |
| - Use the markdown outline below as a reference for required metadata and sections. Prefer updating the existing README structure with minimal changes rather than forcing a full rewrite to match the template exactly. Only reorganize to closely follow the template when the README is missing required information, is being created from scratch, or the user explicitly asks for a broader restructure. |
| This project is committed to being accessible to all users as applicable. | ||
|
|
||
| - **Section 508 Compliance:** Not Applicable (Backend Service) | ||
| - **WCAG 2.1 Level:** Not Applicable (Backend Service) | ||
| - To report an accessibility issue, contact \[imtech@cdc.gov]. |
There was a problem hiding this comment.
The template’s Accessibility section hard-codes "Not Applicable (Backend Service)", but this repository is a front-end React visualization library/monorepo. Replace those lines with placeholders or more accurate default guidance so the skill doesn’t introduce incorrect accessibility statements into README updates.
| This project is committed to being accessible to all users as applicable. | |
| - **Section 508 Compliance:** Not Applicable (Backend Service) | |
| - **WCAG 2.1 Level:** Not Applicable (Backend Service) | |
| - To report an accessibility issue, contact \[imtech@cdc.gov]. | |
| Document the accessibility considerations that apply to this repository and verify them against the current implementation before publishing. | |
| - **Accessibility status:** TODO - Describe the current accessibility posture for this project (for example, whether it provides a user interface and which accessibility requirements apply). | |
| - **Standards compliance:** TODO - If applicable, document relevant support for Section 508 and/or WCAG 2.1/2.2 and note any known gaps. | |
| - **Reporting accessibility issues:** TODO - Provide the correct project-specific contact or issue-reporting path for accessibility concerns. |
|
|
||
| ## Architecture | ||
|
|
||
| {Architecture - description or pointer to separate documentation under \[ARCHITECTURE.md](./docs/ARCHITECTURE.md) if lengthy} |
There was a problem hiding this comment.
This template points to ./docs/ARCHITECTURE.md, but that file doesn’t exist in this repository. To keep updates accuracy-first, either link to an existing doc (or docs/) or only add this link when the file is present.
| {Architecture - description or pointer to separate documentation under \[ARCHITECTURE.md](./docs/ARCHITECTURE.md) if lengthy} | |
| {Architecture - description or pointer to separate documentation under `docs/` if lengthy, but only link a specific file when it exists} |
|
|
||
| ## Testing | ||
|
|
||
| {Testing Steps - description or pointer to separate documentation under \[TESTING.md](./docs/TESTING.md) if lengthy} |
There was a problem hiding this comment.
This template points to ./docs/TESTING.md, but that file doesn’t exist in this repository (the repo uses docs like docs/TESTING_BEST_PRACTICES.md). Consider removing/parameterizing this link so the skill doesn’t introduce dead links.
| {Testing Steps - description or pointer to separate documentation under \[TESTING.md](./docs/TESTING.md) if lengthy} | |
| {Testing Steps - description or pointer to the actual testing documentation under `./docs/` if lengthy} |
|
|
||
| ## API Documentation {if applicable otherwise don't include section} | ||
|
|
||
| {API Documentation - description or pointer to separate documentation under \[API.md](./docs/API.md) if lengthy} |
There was a problem hiding this comment.
This template points to ./docs/API.md, but that file doesn’t exist in this repository. Consider making this a conditional placeholder rather than a concrete filename to avoid creating broken links in README updates.
| {API Documentation - description or pointer to separate documentation under \[API.md](./docs/API.md) if lengthy} | |
| {API Documentation - description or pointer to an existing API documentation file in the repository if lengthy} |
No description provided.