跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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.ts do 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-manager skill 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:

  1. 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
  2. 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
  3. 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.json for main, module, types, exports fields
  • 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.json for 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 @example blocks 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
阅读完整来源 ↗