illustration-finder - SKILL.md Agent Skill

name: illustration-finder description: | Find and manage a personal library of illustrations — stories, quotes, analogies, stats, and examples — to sharpen writing. Supports two modes:

ADD MODE: Save a new illustration to the local bank. Triggers on: "/illustration-add", "add illustration", "save this story to my illustration bank", "add this to my illustration bank", "save this example", "add this quote".

FIND MODE: Search for illustrations to use in writing. Triggers on: "/illustration-find", "find an illustration", "illustration for [topic]", "do I have a story about", "find me an example of", "search my illustration bank". Add "--web" flag to also search the internet for stories, quotes, and case studies. Web results are cited in Turabian style.

Global bank: ~/.claude/illustration-bank.md (persists across all projects). Project banks: ./illustration-bank.md in any project directory (separate context per project).

Illustration Finder

A personal illustration bank that grows over time. Stories you'd forget are preserved and surfaced automatically.

Banks: Global vs. Project-Local

Global bank (default): ~/.claude/illustration-bank.md

Shared across all projects and sessions
Use for illustrations that apply broadly (professional stories, universal examples)

Project-local bank: ./illustration-bank.md in any directory

Scoped to that project only (e.g., a YG ministry project, a specific client)
Keeps personal, spiritual, or client-specific content separate from general writing

To use a project-local bank, add --db ./illustration-bank.md to any command. To search both banks, run the search script twice — once for each db path.

Mode 1: Add an Illustration

Trigger: User says /illustration-add, "add illustration", or "save this to my bank".

Step 1: Gather the entry details

If the user hasn't provided them, ask for:

Title — a short memorable name for the illustration
Type — one of: story, quote, analogy, stat, example
Themes — 2-5 keywords for when this would be useful (e.g. "resilience, failure, pivot")
Content — the full illustration text (story, quote, statistic, etc.)
Source — where it came from (optional but encouraged: "Personal experience, client project", book title, URL)

If the user pastes a block of text, extract these fields from it. Confirm with the user before saving.

If the user doesn't specify which bank, ask: "Should this go in your global bank or a project-local bank?"

Step 2: Run the add script

Global bank (default):

python3 ~/.claude/skills/illustration-finder/scripts/add_illustration.py \
  --title "TITLE" \
  --type TYPE \
  --themes "theme1,theme2,theme3" \
  --content "CONTENT" \
  --source "SOURCE"

Project-local bank:

python3 ~/.claude/skills/illustration-finder/scripts/add_illustration.py \
  --title "TITLE" \
  --type TYPE \
  --themes "theme1,theme2,theme3" \
  --content "CONTENT" \
  --source "SOURCE" \
  --db ./illustration-bank.md

Step 3: Confirm

Tell the user the entry was saved, which bank it went to, and show the themes so they know how to find it later.

Mode 2: Find an Illustration

Trigger: User says /illustration-find [topic], "find an illustration about X", or asks for a story/example/quote about a topic.

Step 1: Search the bank(s)

Always search local first. If a project-local bank exists in the current directory, search it too.

# Global bank
python3 ~/.claude/skills/illustration-finder/scripts/search_illustrations.py "QUERY" --limit 5

# Project-local bank (if ./illustration-bank.md exists)
python3 ~/.claude/skills/illustration-finder/scripts/search_illustrations.py "QUERY" --limit 5 --db ./illustration-bank.md

Use the user's topic as the query. If they said "resilience through failure", use that as-is.

Step 2: Present local results

If results found, present them clearly:

Found X illustration(s) in your bank matching "[topic]":

1. [STORY] The Excel Spreadsheet No One Could Read
   Themes: data, problem-solving, AI, translation
   "A client had a spreadsheet where payment status was stored as cell background color..."
   → Use this to illustrate: hidden complexity, translating systems, AI as interpreter

For each result, add a one-line "→ Use this to illustrate:" suggestion fitting the user's context.

If no local results: say so clearly, then ask if they want a web search.

Step 3: Web search (--web flag or user request)

Only search the web if the user included --web, or explicitly asks after seeing local results.

Search for:

A narrative from business, sports, science, or history that makes the concept concrete
A real case study with verifiable numbers
A quote from a credible voice in the relevant field

Use 2-3 targeted searches. Good query patterns:

"[topic]" story example business case study
"[topic]" famous quote [relevant field]
"[topic]" statistics research site:hbr.org OR site:nytimes.com OR site:economist.com

Step 4: Present web results with Turabian citations

Read references/turabian.md for the exact citation format before presenting web results.

Present each web result as:

[Web] Title of the Story or Study
Citation: Author Last, First. "Title." *Site Name*. Month Day, Year. URL.
→ Use this to illustrate: [how it fits the user's writing context]

"Key quote or summary of the finding..."

Always verify the quote or statistic before presenting. If uncertain, note it.