accelint-readme-writer
Use when creating or editing a README.md file in any project or package. Analyzes the codebase from the README location, identifies missing or stale documentation, and generates thorough, human-sounding README content with copy-pasteable code blocks and practical examples.
accelint · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add gohypergiant/agent-skills --skill accelint-readme-writer技能说明
name: accelint-readme-writer description: Use when creating or editing a README.md file in any project or package. Analyzes the codebase from the README location, identifies missing or stale documentation, and generates thorough, human-sounding README content with copy-pasteable code blocks and practical examples. license: Apache-2.0 metadata: author: accelint version: "1.3.0"
README Writer
Use this skill to create or update README documentation that stays aligned with the actual codebase.
The workflow analyzes the code from the README location, compares it with existing documentation, and produces thorough README content with copy-pasteable commands and practical examples.
Hard stops
- NEVER run discovery serially when sub-agents are available — spawn parallel discovery agents for different parts of the codebase, such as entry points, dependencies, examples, and existing docs. Serial file-by-file scanning wastes time.
- NEVER document non-exported internal functions — document only the public API that is accessible through package entry points. Internal helper functions that are not re-exported from
index.tsdo not belong in the README. - NEVER fabricate usage examples — extract real examples from test files, JSDoc blocks, or
examples/directories. Made-up examples often contain subtle errors that confuse users. - NEVER use the wrong package manager commands — check for lockfiles (
pnpm-lock.yaml,package-lock.json,yarn.lock,bun.lockb) and use the matching package manager in all commands. Wrong commands break the user's first experience. - NEVER skip comparing code to the existing README — when updating documentation, identify what is missing, what is stale, and what signature changes occurred. Silent drift between code and docs causes user frustration.
- NEVER write robotic, AI-sounding text — use the
accelint-english-managerskill in strict audit+rewrite mode to remove inflated language, promotional tone, and AI writing patterns. Documentation should sound like a helpful human wrote it.
When to use this skill
Use this skill when:
- Creating a new README.md for a project or package
- Updating an existing README.md after code changes
- Auditing documentation for completeness and accuracy
- Converting sparse documentation into thorough guides
- User asks to "document this package" or "write a README"
- User mentions README in context of a monorepo subdirectory
When not to use this skill
Do not use this skill for:
- API documentation generation (use JSDoc/TSDoc tools)
- Changelog or release notes
- Internal developer notes not meant for README
- Documentation in formats other than Markdown
Workflow
Step 1: Locate the README Context
Identify where the README should live. In monorepos, this determines the scope of codebase analysis:
project-root/ # README here documents entire monorepo
├── packages/
│ └── my-lib/ # README here documents only my-lib
│ └── README.md
└── README.md
Step 1.5: Check for Related Documentation
Before analyzing the codebase, check if other onboarding documents exist:
-
Check for openspec/config.yml or openspec/config.yaml
- If exists: Read it to extract:
- Package manager (use this instead of lockfile detection)
- Tech stack summary
- Key libraries and frameworks
- Skip redundant codebase scanning for these facts
- If exists: Read it to extract:
-
Check for ARCHITECTURE.md
- If exists: Read it to understand:
- System components and their purposes
- Deployment model
- External integrations
- Use for "Architecture & Development Guides" cross-reference section
- If exists: Read it to understand:
-
Check for AGENTS.md or CLAUDE.md
- If exists: Note for "Contributing" section
- Reference it for contribution guidelines
Benefits:
- Reduces scanning when other docs exist
- Ensures consistency (README uses same package manager as config.yml)
- Creates proper cross-references automatically
Step 2: Parallel Codebase Discovery
Use parallel sub-agents when available to discover different aspects of the codebase simultaneously. If sub-agents are not available, perform these discovery tasks inline in the same systematic order.
Spawn these discovery agents in parallel when sub-agents are available:
Agent A — Entry Points & Public API
- Check
package.jsonformain,module,types,exportsfields - Read the main entry point file (e.g.,
src/index.ts) - Trace all re-exports to map the complete public API
- List all exported functions, classes, types, constants with signatures
- Return: entry point paths, complete export list with types
Agent B — Dependencies & Configuration
- Read
package.jsonfor dependencies, devDependencies, peerDependencies, scripts - Check lockfile type (
pnpm-lock.yaml,package-lock.json,yarn.lock,bun.lockb) - Look for configuration files:
tsconfig.json,.eslintrc*,vitest.config.*, etc. - Return: dependency list (separate runtime vs peer), available scripts, package manager, configs found
Agent C — Examples & Usage Patterns
- Search for
examples/or__examples__/directory - Read test files (
*.test.ts,*.spec.ts) for usage patterns - Extract JSDoc
@exampleblocks from source files - Look for inline comments showing usage
- Return: example file paths, extracted usage patterns from tests, JSDoc examples
Agent D — Documentation Context (optional, runs concurrently)
- Check for existing README.md
- Look for CHANGELOG.md, CONTRIBUTING.md, LICENSE
- Check for TypeDoc/JSDoc configuration
- Return: existing doc files and their key sections
After all agents complete: merge findings and identify documentation gaps (what exists in code but not in README, what's documented but doesn't exist, signature mismatches)
Step 3: Compare Against Existing README
Extract external findings first — check whether the invoking prompt includes a findings: list:
- Parse the prompt