Skip to content

gpsaggese/helpers / .claude/skills/related_books.create

related_books.create

Verified

Create or update related_books.md for a dir from its content

FileKindSize
SKILL.mdskill md5.7 KB
---
description: Create or update related_books.md for a dir from its content
model: sonnet
---

# 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
  ```markdown
  - 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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall