google-scholar

name	google-scholar
description	This skill should be used when the user asks to "search Google Scholar", "find academic papers", "scholar search", "lookup papers", "find citations", "academic search", "search for papers by author", "find journal articles", "get BibTeX", "cite this paper", "download paper", or needs to search Google Scholar for academic literature via the scholar CLI tool.
version	0.2.0

Google Scholar CLI (scholar)

Search Google Scholar for academic papers via the scholar command-line tool.

Requires: scholar on PATH (~/.local/bin/scholar → ~/projects/google-scholar-cli/scholar)

Check: command -v scholar || echo "MISSING: scholar CLI not installed"

IRON LAW: No Hallucinated Metadata

NEVER fabricate paper titles, authors, journals, years, or abstracts from memory.

When the user asks about a specific paper or needs citation details:

User mentions a paper
    ↓
Do you have the exact metadata from a scholar command in this session?
    ↓
YES → Use that data
NO  → Run scholar search/lookup --bibtex FIRST, then report

Rationalization Table

Excuse	Reality	Do Instead
"I know this famous paper"	Training data has wrong years, missing authors, garbled titles	Run scholar lookup "title" --bibtex
"I'll fill in details later"	You won't — the hallucinated version sticks	Get BibTeX first, present after
"It's a well-known paper"	Even well-known papers have co-authors you'll forget	Let Google Scholar provide the metadata
"The user just wants a quick answer"	A wrong answer is worse than a 2-second lookup	--bibtex adds seconds, not minutes

Red Flags — STOP If You Catch Yourself:

• About to type a paper title from memory → STOP. Run scholar lookup.
• About to list authors without a source → STOP. Run --bibtex.
• Saying "published in" without verification → STOP. Check the BibTeX.
• Writing an abstract from memory → STOP. BibTeX includes the abstract.

Authentication

Before first use, authenticate by extracting cookies from an active Chrome session:

# Chrome must be running with remote debugging enabled
scholar auth --port 9222

Cookies are stored in ~/.google-scholar/cookies (mode 0600).

Core Commands

Scholar Labs Search (AI-Enhanced)

Natural language search using Google Scholar Labs API:

# One-shot search
scholar search "what are the key papers on attention mechanisms"

# JSON output for parsing
scholar search "corporate disclosure and information asymmetry" --json

# With BibTeX citations (includes abstracts)
scholar search "attention is all you need" --bibtex

# Download PDFs for results with full-text links (saves to CWD; move to data/papers/ after)
scholar search "transformer architectures" --download

# Interactive multi-turn mode (follow-up questions)
scholar search --interactive

Traditional Keyword Search

Standard Google Scholar full-text search:

# Keyword search
scholar lookup "machine learning transformers"

# Author search
scholar lookup "author:shleifer disclosure" --json

# With BibTeX
scholar lookup "asset pricing" --bibtex

# With PDF download (saves to CWD; move to data/papers/ after)
scholar lookup "deep learning" --download

Cite (BibTeX by Cluster ID)

Fetch BibTeX directly when you already have a cluster ID from search results:

# Single paper
scholar cite 5Gohgn6QFikJ

# Multiple papers, JSON output
scholar cite 5Gohgn6QFikJ 8409835334886051453 --json

Download (Single PDF)

Note: --download works for open-access PDFs (arXiv, NBER, etc.) but is unreliable for papers behind library link resolvers (institutional access). For paywalled papers, return the URL and let the user download manually.

scholar download "https://arxiv.org/pdf/1706.03762" --output data/papers/attention.pdf

Quick Reference

Need	Command
Natural language question	scholar search "question"
Keyword/author search	scholar lookup "keywords"
BibTeX citations	Add --bibtex to search/lookup
BibTeX by cluster ID	scholar cite <clusterId>
Download PDFs	Add --download to search/lookup; move to data/papers/
Download single PDF	scholar download "url" --output data/papers/file.pdf
JSON output	Add --json to any command
Interactive follow-ups	scholar search --interactive
Re-authenticate	scholar auth

Output Directory Convention (HARD RULE)

All downloaded PDFs and extracted text files MUST be placed in data/papers/, never in the repository root.

• When using scholar download, always specify the output path: --output data/papers/<descriptive-name>.pdf
• When using scholar search --download or scholar lookup --download, the scholar CLI saves to the current working directory by default. Either:
  1. cd data/papers && scholar search "..." --download, or
  2. Download then immediately mv *.pdf data/papers/
• All text extracted from PDFs (via pdftotext, pymupdf, or similar) must also be written to data/papers/
• Never save paper files to the repository root — this pollutes the project root and causes untracked files

Decision Tree: Which Command?

Do you have a cluster ID already?
  YES → scholar cite <clusterId>
  NO  ↓
Do you have a natural language research question?
  YES → scholar search "question"
  NO  ↓
Do you need keyword-exact or author-specific results?
  YES → scholar lookup "author:name keyword"
  NO  ↓
Do you want follow-up refinement?
  YES → scholar search --interactive

When to add flags:

Need citation metadata (authors, journal, year, abstract)?
  YES → Add --bibtex
Need to download the PDF (open-access only)?
  YES → Add --download (unreliable for paywalled papers — return the URL instead)
Need machine-readable output?
  YES → Add --json

Verified Paper Information Workflow

When presenting paper information to the user, follow this workflow:

1. Run scholar search/lookup with --bibtex
2. Parse BibTeX fields for authoritative metadata:
   - title, author, journal/booktitle, year, abstract
3. Present ONLY the fields returned by BibTeX
4. If BibTeX is missing a field, say "not available" — do NOT fill from memory

BibTeX includes abstracts: The --bibtex flag injects the snippet as an abstract field in the BibTeX entry. Use this instead of generating abstracts.

Output Format

Table output (default): Columns for #, Title, Authors, Year, Cited, Journal, followed by snippets and URLs.

JSON output (--json): Array of ScholarResult objects:

{
  "title": "Paper Title",
  "authors": "Author A, Author B",
  "journal": "Journal Name",
  "year": "2024",
  "citations": 150,
  "snippet": "Abstract excerpt...",
  "url": "https://...",
  "pdfUrl": "https://... or null",
  "clusterId": "12345",
  "position": 1
}

BibTeX output (--bibtex): Standard BibTeX entries with abstract field:

@article{key,
  title={Paper Title},
  author={Author, A and Author, B},
  journal={Journal Name},
  year={2024},
  abstract={Abstract text from Google Scholar snippet...}
}

Domain Knowledge Integration

When searching Google Scholar, ALWAYS consult the domain knowledge file first:

File: domain-knowledge.local.md (relative to this skill's base directory)

This file contains the user's curated list of trusted journals, authors, and research groups. Use it to:

1. Prioritize results from known-good journals and authors
2. Flag unfamiliar sources - if a result is from an unknown journal, note it
3. Suggest related searches - use known authors to refine queries
4. Assess quality - weight results higher when they appear in trusted venues

How to Use Domain Knowledge

User asks: "find papers on corporate disclosure"
    ↓
1. Read domain-knowledge.local.md
2. Run scholar search/lookup
3. Cross-reference results against trusted journals/authors
4. Present results with quality signals:
   - ★ = from trusted journal or by trusted author
   - Results from unknown sources shown without star

Operational Rules

1. No hallucinated metadata — NEVER cite title/author/journal/year/abstract from memory. Use --bibtex or scholar cite to get verified data.
2. Scholar is for discovery — Use it to find new papers, not to read them
3. Always use --json when results will be processed programmatically
4. Use --bibtex when presenting papers — It provides verified author, journal, year, and abstract fields
5. Cross-reference domain knowledge — Always check trusted journals/authors
6. Auth required — If search fails with auth errors, re-run scholar auth
7. Rate limits — Google Scholar may rate-limit; space out rapid queries