I wrote the four files you asked for, all under docs/. I didn't run anything, so every command and example is untested.
| File | Lines (about) | Content |
|---|---|---|
01_architecture.md |
170 | Three layers, an annotated directory tree, the modules, and a "where is X" table |
04_code_walkthrough.md |
220 | Walk-through of creating a short link and following one, with sequence diagrams |
README.md |
35 | Which chapters to read for which goal, plus the skipped chapters |
.project-map.md |
90 | My reading notes, glossary and open questions |
- Skipped: chapters 02, 03 and 05–09 are listed in the index with the reason: you asked for a shorter run. The numbers are kept, so they can be added later. Chapters 05 and 06 note that the project has little to say there (no concurrency code, no build step).
- Length: 01 and 04 are well under the skill's 300-line target. The whole project is about 90 lines of Python, so I didn't pad them.
- Not verified:
- The README's run commands:
pip install,python -m shortlink.appandpytest. - The
curlexample. - My reading that sqlite3's
withblock doesn't close the connection. This is marked in the text.
- The README's run commands:
- Not covered in the docs:
- Behaviour under concurrent requests.
shortlink/__init__.py, which is empty.- The project isn't a git repo, so the docs have no commit to point at.
While reading the code I noticed two things:
create_linkdoesn't catch theRuntimeErrorthatshortenraises after five failed attempts at a unique code, so that case returns a 500.link_statscallsstoragedirectly and skips the service layer.
Both are in the docs as observations, not fixes.
Real run in a throwaway directory with a ~90-line Flask sample project (shortlink). Tools were limited to Skill, Read, Glob and Write, with no shell, so no command was executed. To keep the run short the prompt asked for only chapters 01 and 04 plus the project map and index. The skill wrote four files (about 505 lines in total); only the model's final message is shown, verbatim. The generated docs came out in Chinese because the skill's templates are Chinese.
What it does
Generates up to nine onboarding documents for a new teammate from the real code of any project, and writes them to the project's docs/ folder.
How it works
- Reads the project in three passes (layout, skeleton, one end-to-end flow) and records paths, classes, a glossary and open questions in
docs/.project-map.md. - Picks which of the nine chapters to write based on the project type (system, web backend, web frontend, library, data script). Skipped chapters keep their number and the reason is written down.
- Writes each chapter from a template. Every code snippet must be re-read from the actual file first and cited as
path:line; commands that were not run are marked unverified. - Writes
docs/README.md(which chapters to read for which goal), runs a self-check list, and reports what was skipped and what is still unclear.
It can also write only some chapters, or update existing docs by diffing against the commit recorded in the project map.
Good for
- Handing a codebase to a new teammate
- Understanding an unfamiliar repository
- Refreshing stale architecture docs
The skill's templates are in Chinese, so the documents it writes default to Chinese even when you ask in English.
Medium risk: it creates and rewrites Markdown files under the project's docs/ folder, including a hidden docs/.project-map.md. If docs/ already has content, the skill is instructed to ask first whether to overwrite, skip existing files or back them up to docs.bak/. It contains no scripts, makes no network calls and does not delete anything. Tried once on a ~90-line sample project in a throwaway directory with only the Skill, Read, Glob and Write tools and no shell, so no command was run and its build and run instructions are unverified; the overwrite prompt was not exercised because docs/ did not exist. Commit or back up docs/ before running it, and review the generated docs for wrong paths or class names.