Skip to content

gpsaggese/helpers / .claude/skills/readme_dir.create

readme_dir.create

Verified

Write 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 its README.md following .claude/skills/readme_dir.rules.md and 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.md reads this section to write the checklist that guides the review of the dir

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
  • 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>.log files 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 under docs/, log.md, todos.md
    • test: files under test/ or named test_*.py
    • code: all the other *.py and *.sh files
    • data: 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 _main and if __name__ == "__main__"
  • Pair each code file with:
    • Its doc, e.g., <FILE>.README.md or the design doc that names it
    • Its test, e.g., test/test_<FILE>.py
  • 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 doc and data: 30
    • Read code: 20
    • Read test: 40
  • Compute the minutes of a file as ceil(lines / speed), with 1 as the minimum
    • The Mins column of the table uses the speed of the file's kind
  • Sum the Mins of 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 import lines of each file, and keep the imports that point to another file of the dir
  • Sort the code files 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 unknown in the line
    • Do not guess

Write the Review Roadmap

  • Write the section # Review roadmap as 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 Read cells of the rows that are still in the new table
  • 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
  • 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 Skipped line, the note on the <SCRIPT>.log files, 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 Read holds [ ], to tick when the file is read
    • Put Mins next to Lines
    • 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 Lines and Mins of the README row to the size of the final README, and update the total

Constraints

  • Do not modify any file of <DIR>, other than README.md
    • Running the scripts of the dir can create *.log files: delete those that the run created
  • 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.md exists 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.md is 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 roadmap is the last section, with the subsections ## Testing and ## Files and Reading Time
  • There is no # Map of the Dir header
  • 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 Mins of each row follows them
  • A bullet above the table gives the order of the rows, and the table follows it
  • The Lines of the README.md row equals the line count of the final README
  • No file of <DIR> changed, other than README.md
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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall