Goal

• You are an expert in the literature of the field and in technical writing.
• Given a dir <DIR>, create or update the file <DIR>/related_books.md, which lists all the books related to the content of <DIR>
• Follow the rules .claude/skills/related_books.rules.md
• Follow the template .claude/templates/related_books.template.md
• Say in the file how it was generated, with the line

  - Generated by `.claude/skills/related_books.create/SKILL.md`
  

Workflow

Pick the Mode

• If <DIR>/related_books.md exists, update it
  • Read it, and keep every book section that is still valid
• If it does not exist, create it
• If <DIR> has books in an old format, merge them into the new file
  • E.g., a related_books.md with only one line per book, book_list.md, book_info.md, book_info.tsv, books.md
  • E.g., the Related books, Books, Recommended Reading, and Books & Learning Resources sections of book_map.md, resources.md, and slide files
  • Rename the old file with git mv when it is a plain list of books that has no other use, e.g., book_list.md
  • Do not delete book_info.md and book_info.tsv, which .claude/skills/book_list.gather_info/SKILL.md generates
  • Do not remove the book lists inside book_map.md and similar files
  • Delete another old file with git rm, only after every book of the old file is in the new file

Read the Content of the Dir

• List the lectures, slides (*.smd), notebooks (*.ipynb), markdown files, and bibliographies of <DIR>
• Write down:
  • The topics of the content
  • The lesson or chapter tags, e.g., 03.2, taken from the names of the lecture files or from book_map.md
  • The books that the content names or cites

Find the Candidate Books

• Start from the books that the content names or cites
• Keep the data of an old list as it is
  • Do not rewrite a title, an author, a year, or an ID of an old list
  • Do not drop an entry. If an entry is not a book, say so in the report
• If the dir has no list yet, search the web for the main books of each topic
  • Prefer books with a public page of the publisher
• Keep a book only if a lesson or a chapter in <DIR> can use it
• Drop an item that is a paper, a package, a topic, or a web page

Group the Books

• Group the books by primary topic into clusters
  • Name each cluster with a short noun phrase
  • Write the topic of the cluster in one line
• Put each book in exactly one cluster
• Use 3 to 12 clusters

Collect the Fields

• Fill the fields of a book in the order of the rules
• Copy every field that the source gives, and leave out every field that it does not give
  • Do not invent an author, a year, a publisher, a URL, or a score
• To fill a missing field, search the web, and use the page of the publisher
  • Check each URL with curl -sI <URL>
  • If a check fails, add ??? after the URL
• Collect the scores with .claude/skills/book_list.gather_info/SKILL.md
  • Do not guess a score. Use n/a for a value that is not found
• Set the Lessons from the places where the content names or cites the book
• Set the Alternatives from the books of the same cluster

Write the File

• Write the header: the title, the Generated by line, Scope, and Ratings as of
• Write the section Rating Scales
• Write the sections of the clusters and of the books in the order of the rules
• Write the tables Topic Clusters and Book Summary from the sections
  • Align the columns of the tables
  • Drop a column of Book Summary when all its values are n/a
• Wrap the prose at 85 characters, and keep the URLs on one line
• Do not run lint_text.py on the file
  • It capitalizes the words of the headers and of the Alternatives bullets

Update an Existing File

• Add the new books, and place them in the right cluster and position
• Fill the fields that were missing and are now found
• Keep the Content, Caveats, and Alternatives that are correct
• Do not delete a book without a reason
  • If a book is gone from the content, say so in the report and leave it
• Report the changes: the books added, the fields filled, and the fields fixed

Check the File

• Run the checks of the # Verification section
• Fix every failed check

Constraints

• Do not modify any file other than <DIR>/related_books.md
  • Exception: the old-format files that are merged into it
• Do not invent a book, an author, a year, a publisher, a URL, or a score
• Do not commit the changes
• Do not use emojis or the em-dash

Examples

• A filled file with scores: book_AI_Software_Engineering/related_books.md
• A filled file with lessons: book_Causal_Probabilistic_ML/related_books.md
• A file with IDs from an old registry: book_springer/related_books.md

Verification

• The file is named <DIR>/related_books.md
• The first bullet after the title is - Generated by `.claude/skills/related_books.create/SKILL.md`
• The file has one # header
• Every book has ID, Authors, and Year, and the fields are in the order of the rules
• Every ID is unique, and no ID of an old list changed
• Every book appears in exactly one cluster
• The books are ordered by year, newest first, inside each cluster
• The tables Topic Clusters and Book Summary list exactly the books of the sections, in the same order
• Every name in Alternatives is an ID that has a section in the file
• Every entry of the old files is in the new file, or is named in the report as not a book
• No old-format file is left in <DIR> with books that are not in the new file
• No other file of <DIR> changed