refreshing-docs
Refreshes README.md documentation tables including the packages table and core namespace index. Reads from package.json files and core module JSDoc.
When & Why to Use This Skill
The Refreshing Docs Claude skill automates the maintenance of project documentation by synchronizing README.md tables directly with the codebase. It intelligently parses package.json files and core module JSDoc comments to ensure that package lists and namespace indices are always accurate, preventing documentation rot and reducing manual overhead in complex software projects.
Use Cases
- Case 1: Automatically updating the main README.md packages table whenever a new package is added to a monorepo or a package description is modified.
- Case 2: Synchronizing the core namespace index with the latest JSDoc descriptions in the source code to ensure developers always see up-to-date API summaries.
- Case 3: Maintaining consistent project documentation in CI/CD pipelines by programmatically refreshing auto-generated sections before releases.
| name | refreshing-docs |
|---|---|
| description | Refreshes README.md documentation tables including the packages table and core namespace index. Reads from package.json files and core module JSDoc. |
Refreshing Docs
Update auto-generated documentation tables in README.md.
Steps
- Run the script at
.claude/skills/refreshing-docs/scripts/docs-refresh.ts
Reference
The script updates two sections in README.md:
- Packages table - Lists all packages from
packages/*/package.json - Core namespace index - Lists modules from
core/src/*/_.tswith JSDoc descriptions
Sections are marked with HTML comments:
<!-- PACKAGES_TABLE_START -->
| Package | Description |
| ------- | ----------- |
| [`@kitz/core`](./packages/core) | Core utilities |
...
<!-- PACKAGES_TABLE_END -->
<!-- CORE_NAMESPACE_INDEX_START -->
| Module | Description |
| ------ | ----------- |
| `Arr` | Array utilities |
...
<!-- CORE_NAMESPACE_INDEX_END -->
Notes
- Run after adding/removing packages or modifying package descriptions
- Run after adding/modifying core modules or their JSDoc
- The markers must exist in README.md for the script to work