AI Skill Report Card
Generating Project Docs
Quick Start13 / 15
Given a project directory, produce a docs/ (or guides/) folder with:
docs/
README.md # entry point, links to everything else
getting-started.md # install, setup, first run
architecture.md # high-level design, key modules
usage.md # common workflows/examples
api-reference.md # generated from code signatures/comments
Start by scanning the repo for: entry points (main.*, index.*), config files (package.json, pyproject.toml, etc.), and existing README/docs to avoid duplication.
Recommendation▾
Add a 'bad output' example (e.g., docs with invented features or stale API signatures) to show contrast with good outcomes
Workflow14 / 15
Progress:
- Step 1: Scan repo structure — identify language, entry points, dependencies, existing docs
- Step 2: Extract facts — read source for public APIs, CLI commands, config options, exported functions
- Step 3: Draft
README.md— one-paragraph summary, install command, minimal usage example, link to other docs - Step 4: Draft
getting-started.md— prerequisites, install steps, first successful run/output - Step 5: Draft
architecture.md— module/folder map, data flow, key design decisions (only if project has >3 modules) - Step 6: Draft
usage.md— 3-5 realistic task-based examples with input/output - Step 7: Draft
api-reference.md— generated table of functions/classes/CLI flags with signatures and one-line descriptions - Step 8: Cross-link all docs from README, verify no broken links, verify code examples actually match current API
Recommendation▾
Include a third example covering a more complex multi-module project to demonstrate architecture.md generation
Examples14 / 20
Example 1:
Input: A Python CLI tool with cli.py exposing parse, convert, validate subcommands, no existing docs.
Output:
docs/README.md:
# mytool
CLI for converting and validating data files.
Recommendation▾
Provide a concrete template/skeleton for api-reference.md table format rather than just prose description
Install
pip install mytool
Quick Start13 / 15
mytool convert input.csv output.json
See usage.md for more.
Plus `usage.md` with one example block per subcommand (`parse`, `convert`, `validate`), each showing command + expected output.
**Example 2:**
Input: A Node.js library exporting `createClient(config)` returning an object with `.get()`/`.post()` methods.
Output: `api-reference.md` containing:
createClient(config)
Creates a client instance.
config.baseUrl(string, required)config.timeout(number, optional, default 5000) Returns: Client
Client.get(path)
Sends a GET request. Returns Promise<Response>.
Best Practices
- Derive every claim from actual source code or config, never invent behavior.
- Keep README under 100 lines; push detail into linked pages.
- One example per doc page must be copy-pasteable and runnable as-is.
- Use consistent heading levels across all docs (H1 title, H2 sections).
- Prefer tables for parameter/flag references over prose.
- Name files in lowercase-kebab-case for cross-platform link consistency.
Common Pitfalls
- Don't document planned/aspirational features as if they exist — check the code.
- Don't duplicate the same install instructions across multiple files; link instead.
- Don't generate
architecture.mdfor trivial single-file projects — skip if unnecessary. - Don't leave placeholder text like "TODO" or "[description here]" in final output.
- Don't let API reference drift from actual function signatures — regenerate, don't hand-edit stale docs.