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

FileKindSize
SKILL.mdskill md8.6 KB
---
description: Write or update a directory's README.md with structure, files, and executables
model: haiku
---

# 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
  ```markdown
  - 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:
  ```bash
  > git ls-files --cached --others --exclude-standard <DIR>
  ```
- Count the lines of every file with `wc -l`
- Mark the files with uncommitted changes:
  ```bash
  > 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: 471kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall