gpsaggese/helpers / .claude/skills/readme_dir.create
readme_dir.create
VerifiedWrite or update a directory's README.md with structure, files, and executables
Goal
- You are an expert technical writer specializing in software documentation.
- Given a dir
<DIR>, write itsREADME.mdfollowing.claude/skills/readme_dir.rules.mdand the template.claude/templates/readme_dir.template.md - Say in the README how it was generated, with the line
- Generated by `.claude/skills/readme_dir.create/SKILL.md` - End the README with the section
# Review roadmap: the map of the dir, how to run the tests, the reading speeds, and the table of files with the time to read each one- The skill
.claude/skills/review.create_code_tour/SKILL.mdreads this section to write the checklist that guides the review of the dir
- The skill
Workflow
Examine the Directory
- List all subdirectories, files (Python/Markdown), and executables
Write the README
-
Put the
Generated by ...bullet from the Goal right after the title, before the Summary bullets -
Structure the README with the sections from
.claude/skills/readme_dir.rules.md:- Summary, as bold-labeled bullets (Goal, Input, Output, Users)
- Structure of the Dir
- Description of Files
- Description of Executables (if applicable)
- Output Dir (if the executables write a tree of files in one dir), as a
##section of the executables, before the first executable - Description of Workflows (if applicable)
- Description of Architecture (if applicable)
- Review roadmap, as the last section, see "Write the Review Roadmap"
-
Follow all formatting rules from
.claude/skills/readme_dir.rules.md:- Description limits (e.g., <20 words for subdirs, 1-line for files)
- Command formatting with
>prefix and proper code blocks - Example ordering (simple to complex)
- Table format for command references
- Bullets only, no prose paragraphs, including the intro of each section
- Many outputs as one sub-bullet per file or per group of files
Check the Commands
- Check each example command against the current CLI of its executable (e.g., with
--help) - Remove the args that the tool dropped, and rename the args that the tool renamed
- Check the commands in the workflows too
Take the Inventory
- List the tracked and untracked files of the dir, without ignored files:
> git ls-files --cached --others --exclude-standard <DIR> - Count the lines of every file with
wc -l - Mark the files with uncommitted changes:
> git status --short <DIR> - Skip these, and list them in the "Skipped" line with the reason:
- Logs:
*.log - Scratch files:
tmp.* - Caches:
__pycache__/,.ruff_cache/,.pytest_cache/ - Symlinks
- The checklist file
code_tour.md
- Logs:
- Keep a raw export in the table, but give it no time
- E.g., a CSV over 1000 lines that a person downloads
- Running the scripts of the dir can create
<SCRIPT>.logfiles next to the scripts- Say it in the "Skipped" line, so that the reader ignores these files
Classify the Files
- Put each file in exactly one kind:
doc:README.md,*.README.md, files underdocs/,log.md,todos.mdtest: files undertest/or namedtest_*.pycode: all the other*.pyand*.shfilesdata: prompts, YAML, CSV, JSON, and other inputs read by the code
- Find the entry points
- A file is an entry point if it is executable, or has
_mainandif __name__ == "__main__"
- A file is an entry point if it is executable, or has
- Pair each
codefile with:- Its doc, e.g.,
<FILE>.README.mdor the design doc that names it - Its test, e.g.,
test/test_<FILE>.py
- Its doc, e.g.,
- Find the test helpers, i.e., test files that have no
test_prefix, e.g.,test/epq_test_utils.py
Set the Reading Time
- Use these speeds, in lines per min, and print them just above the table of the
files:
- Skim: 100, for any kind of file
- Read
docanddata: 30 - Read
code: 20 - Read
test: 40
- Compute the minutes of a file as
ceil(lines / speed), with 1 as the minimum- The
Minscolumn of the table uses the speed of the file's kind
- The
- Sum the
Minsof the table, and print the total in mins and in hours, rounded to the hour
Order the Code
- Build the import graph of the files of the dir
- Read the
importlines of each file, and keep the imports that point to another file of the dir
- Read the
- Sort the
codefiles bottom up- A file with no imports from the dir comes first
- A file comes after all the files that it imports
- Break ties with the smaller file first
- Entry points come last, in the order that the docs give for running them
- If the graph has a cycle, report it in the line "Cycles in the import graph" and sort the files of the cycle by size
Find the Purpose of Each File
- For each file, read the docstring or the first lines, and the doc paired with it
- Write the purpose of a file in one short line
- If the purpose is not clear from the file, write only the file name and put
purpose unknownin the line - Do not guess
- If the purpose is not clear from the file, write only the file name and put
Write the Review Roadmap
- Write the section
# Review roadmapas the last section of the README, following the template.claude/templates/readme_dir.template.md- If the section exists, write it again, and keep the ticked
Readcells of the rows that are still in the new table
- If the section exists, write it again, and keep the ticked
- Write the intro bullets
- The use of the section
- The path of the checklist file
<DIR>/code_tour.md, made from this section by.claude/skills/review.create_code_tour/SKILL.md
- Write the map, as bullets, with the path from the repo root for every file
- Purpose: one sentence, from the Goal of the Summary
- Entry points, in run order, with one line each
- Layers, bottom first, with one line each
- Cycles in the import graph: none, or the list
- Write a subsection
## Testing- Take the way to run the tests from
helpers_root/CLAUDE.md## Testing - Give the command for the dev env and the command for Docker, in a fenced block
- Take the way to run the tests from
- Write a subsection
## Files and Reading Time, in this order:- The reading speeds and the total time to read every file once
- A bullet that gives the order of the rows of the table
- Say that the kinds come in the order code, doc, test, data
- Say the order inside each kind: code bottom up and then the entry points, docs by number, tests in the order of the code that they test
- Say that the order is not the order of the checklist, which mixes the kinds
- The table with one row per file, including the data files
- The
Skippedline, the note on the<SCRIPT>.logfiles, and the other notes on the table, e.g., the code that has no test file of its own
- Make the table follow the template
- Write the paths from the repo root in all the columns, so that the reader can open them directly
- The first column
Readholds[ ], to tick when the file is read - Put
Minsnext toLines - Order the rows as the bullet above the table says
- The README is a row of the table
- Write the section first, then set the
LinesandMinsof the README row to the size of the final README, and update the total
- Write the section first, then set the
Constraints
- Do not modify any file of
<DIR>, other thanREADME.md- Running the scripts of the dir can create
*.logfiles: delete those that the run created
- Running the scripts of the dir can create
- Do not invent a command, a file, or a function
- Use
:and not-to separate a file from its description - Do not use emojis or the em-dash
Verification
-
README.mdexists in the target directory<DIR> - The first bullet after the title is
- Generated by `.claude/skills/readme_dir.create/SKILL.md` - Every required section from
.claude/skills/readme_dir.rules.mdis present - The Summary has the bullets Goal, Input, Output, and Users
- There is an "Output Dir" section if the executables write a tree of files
- There is no prose paragraph
- Description length limits and command formatting rules are followed
- Every example command, in the executables and in the workflows, uses args that the current CLI accepts
-
# Review roadmapis the last section, with the subsections## Testingand## Files and Reading Time - There is no
# Map of the Dirheader - The table has one row per file of the inventory, or the file is in the "Skipped" line
- The table uses the path from the repo root for every file
- The reading speeds are printed above the table, and the
Minsof each row follows them - A bullet above the table gives the order of the rows, and the table follows it
- The
Linesof theREADME.mdrow equals the line count of the final README - No file of
<DIR>changed, other thanREADME.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |