paper-discover

<Purpose> Search academic databases (Semantic Scholar) for papers relevant to a topic or related to an existing vault note. Returns ranked results with relevance assessment against vault content. Optionally creates formatted paper notes in the vault's inbox for processing. </Purpose> <Use_When> - User asks to find papers on a topic ("find papers about scaling laws") - User wants papers related to an existing note ("what papers connect to this?") - User is /processing a paper and wants to find related work - User asks "what should I read about X?" - User provides a DOI or paper title and wants similar papers - User wants to fill gaps in a knowledge domain </Use_When> <Do_Not_Use_When> - User has a paper file to analyze (use /paper or /book-analyzer) - User wants to process an existing vault note (use /process) - User wants general web research, not academic papers (use /research) </Do_Not_Use_When> <Execution_Policy> - Search first, present results, then create notes only if user approves - Always check vault for existing paper notes before creating duplicates - Rank by vault relevance, not just citation count - Cap at 10 results per search — quality over quantity - Respect Semantic Scholar rate limits (100 req/5min) </Execution_Policy> <Steps> ## Stage 1: PARSE QUERY AND CONTEXT Determine the search mode from user input: **Mode A — Topic search** (default): User provides a topic or question. Extract search terms. ``` "find papers about scaling laws for LLMs" → query: "scaling laws large language models" ``` **Mode B — Similar papers**: User references an existing vault note or provides a paper ID/DOI. 1. Read the referenced note to extract title, key concepts 2. Use the paper's Semantic Scholar ID or DOI for recommendations 3. Fall back to keyword search if no ID available **Mode C — Gap filling**: User asks about a domain. Search vault first to identify what's covered, then search for papers on uncovered subtopics. ## Stage 2: SEARCH Run the search script: ```bash SKILL_DIR="${CLAUDE_SKILL_DIR}" # Topic search python3 "$SKILL_DIR/scripts/search_papers.py" "QUERY" --limit 20 --min-citations 5 # With year filter python3 "$SKILL_DIR/scripts/search_papers.py" "QUERY" --limit 20 --year-from 2020 # Get recommendations from a paper python3 "$SKILL_DIR/scripts/search_papers.py" "" --recommend-from "DOI:10.xxxx/xxxxx" # Look up specific paper python3 "$SKILL_DIR/scripts/search_papers.py" "" --paper-id "DOI:10.xxxx/xxxxx" ``` Script returns JSON array of papers with: title, authors, year, abstract, tldr, citation_count, influential_citations, url, doi, arxiv_id, fields_of_study. ## Stage 3: RANK AND PRESENT Read the agent definition from `agents/paper-writer.md` in the skill directory. Search the vault for existing paper notes on this topic using the MCP tool: ``` search_notes(query="KEYWORD", limit=20) ``` Or fall back to Grep if MCP is unavailable: ``` Grep(pattern="KEYWORD", path="notes/", glob="*.md", head_limit=20) ``` Launch the paper-writer agent to rank and present: ``` Agent( subagent_type="general-purpose", model="sonnet", run_in_background=false, prompt="You are Paper Writer. Follow these instructions exactly: [INSERT FULL CONTENT OF agents/paper-writer.md HERE] SEARCH CONTEXT: - User query: [original query] - Search mode: [topic/similar/gap] - Vault topics: [detected from search/tags] EXISTING VAULT PAPERS: [List any matching paper notes already in the vault] SEARCH RESULTS: [INSERT JSON FROM STAGE 2 HERE] Rank these papers by relevance to the vault's existing knowledge. Present the top 10 with your assessment. Do NOT create notes yet — just present the ranked list for user triage." ) ``` ## Stage 4: CREATE NOTES (on user approval) After user selects which papers to add: For each selected paper, create a vault note: 1. Generate timestamp ID: `date +%Y%m%d%H%M%S` 2. Create the note file with proper frontmatter and body 3. Check for duplicate titles before creating Note template: ```markdown --- id: YYYYMMDDHHMMSS created_date: YYYY-MM-DD updated_date: YYYY-MM-DD type: paper category: link: [paper URL] processing_status: inbox --- # Title - **🏷️Tags** : #paper #topic-tag #MM-YYYY [ ](#anki-card) ## Abstract - [Synthesized abstract bullets] ## Notes ## Questions ## Related links - [Paper URL](url) - [[(Type) Related Vault Note]] ``` Place the note in `notes/paper/` (or appropriate topic folder). </Steps> <Tool_Usage> - **Bash**: Run search_papers.py script, generate timestamps - **Read**: Read agent definition, read existing vault notes for context - **Write/Edit**: Create paper notes in vault - **Agent**: Delegate ranking/presentation to paper-writer (sonnet) - **Grep/Glob**: Search vault for existing papers and related notes - **TodoWrite**: Track progress through stages </Tool_Usage> <Examples> <Good> User: "find papers about scaling laws for neural networks" 1. Search → 20 results from Semantic Scholar 2. Check vault → found 3 existing scaling law papers 3. Agent ranks → filters to 8 new papers, ranked by vault relevance 4. Present: "Found 8 papers you don't have. Top pick: 'Chinchilla' (2022, 4200 citations) — connects to your [[Scaling Laws]] and [[Compute-Optimal Training]]" 5. User picks 3 → create 3 paper notes in notes/paper/ with inbox status </Good> <Good> User: "what papers are related to this one?" (while viewing a paper note) 1. Read current note → extract title, DOI 2. Get recommendations via Semantic Scholar API 3. Check vault → filter out papers already present 4. Present ranked list with connections to existing notes </Good> <Bad> User: "find papers about ML" - Too broad — should ask: "ML is a wide field. What aspect? Scaling laws, reinforcement learning, attention mechanisms, optimization...?" </Bad> </Examples> <Escalation_And_Stop_Conditions> - **No results**: Try broader query, suggest alternative terms - **API rate limited**: Wait and retry (script handles this automatically) - **Query too broad**: Ask user to narrow down the topic - **All results already in vault**: Report "your vault already covers this well" - **Network error**: Inform user, suggest trying again later </Escalation_And_Stop_Conditions> $ARGUMENTS