Reading Agent
Create structured reading notes for academic papers. This skill can operate standalone or integrate with lit-synthesis.
Project Integration
This skill reads from project.yaml when available:
# From project.yaml
paths:
lit_synthesis: literature/synthesis/Project type: This skill works for all project types. Reading and analyzing literature is essential for qualitative, quantitative, and mixed methods research.
Saves reading notes to literature/synthesis/reading-notes/ by default, or to the path specified in project.yaml.
File Management
This skill uses git to track progress. After creating or updating reading notes:
- Stage and commit:
git add [files] && git commit -m "reading-agent: Notes for [author-year]"
Do NOT create version-suffixed copies (e.g., -v2, -final, -working). The git history serves as the version trail.
When to Use This Skill
Use this skill when you need to:
- Create reading notes for a single paper
- Batch-process multiple PDFs into structured notes
- Extract consistent metadata and analysis across papers
- Prepare papers for literature synthesis
Quick Start
/reading-agent
I need to read: /path/to/paper.pdfOr with a citation key:
/reading-agent
Citation key: smithCulturalFrames2020Workflow
Step 0: Identify the Paper
Ask the user for:
- Paper source: PDF path, citation key (for local library lookup), or pasted text
- Identifiers (at least one, prefer citation key):
- Citation key (e.g., smithCulturalFrames2020) — from lit-search database or references.bib - OpenAlex ID (e.g., W2123456789) - DOI (e.g., 10.1086/123456)
Step 1: Access Paper Content
If PDF or EPUB provided (new paper): Ingest into the local library (converts to markdown + adds metadata to references.bib):
uv run plugins/sociology-skillset/scripts/ingest.py --file "/path/to/paper.pdf"
# Copies to library/pdfs/, converts to library/markdown/ (docling for PDFs, pandoc for EPUBs), appends to references.bibIf PDF provided for a paper already in references.bib (e.g., from lit-search but PDF was missing):
uv run plugins/sociology-skillset/scripts/ingest.py --file "/path/to/paper.pdf" --citekey Thompson2022_Inequality --update
# Converts the PDF, copies files to library/, updates the existing bib entry with pdf_path and md_pathIf citation key provided: Look up the key in references.bib to find the md_path field, then read the markdown file at that path directly.
If markdown/text: Use directly.
Step 2: Read and Extract
For single-paper mode (default): Read the paper directly and create structured notes.
For batch mode: Spawn haiku agents using the Task tool:
Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku"
- prompt: [reading prompt with content and identifiers]
- description: "Read paper: AuthorYear"Step 3: Save Notes
Save reading notes to: reading-notes/author-year-slug.md
The filename uses author-year-slug for readability, but frontmatter identifiers are the authoritative match back to source papers.
Reading Note Template
All reading notes must follow this structure with required frontmatter:
---
citation_key: smithCulturalFrames2020 # From references.bib or lit-search database (preferred)
openalex_id: W2123456789 # From lit-search database
doi: 10.1086/123456 # Digital Object Identifier
first_author: Smith
year: 2020
short_title: cultural-frames
---
# Smith 2020 - Cultural Frames
## Bibliographic Info
- **Authors**: [all authors]
- **Year**: [publication year]
- **Title**: [full title]
- **Journal**: [venue/publisher]
- **DOI**: [as link if available]
- **OpenAlex**: https://openalex.org/W2123456789
## Core Argument
[1-2 sentences: What is the paper arguing?]
## Theoretical Framework
- **Tradition**: [e.g., Bourdieusian, institutionalist, interactionist, framing theory]
- **Key concepts**: [list main theoretical concepts used]
- **Theory deployment**: [description | extension | critique | synthesis]
## Empirical Strategy
- **Data**: [what kind of data - interviews, content analysis, survey, etc.]
- **Methods**: [how data was analyzed]
- **Sample**: [who/what was studied, N if applicable]
## Key Findings
1. [Finding 1]
2. [Finding 2]
3. [Finding 3]
## Contribution Claim
[What does the paper claim to contribute to the literature?]
## Limitations
[As noted by the authors]
## Key Quotes
> "[Quote 1 - captures core argument or key concept]" (p. X)
> "[Quote 2 - methodological or theoretical insight]" (p. Y)
> "[Quote 3 - finding or implication]" (p. Z)
## Connections
[What other papers, concepts, or debates does this connect to?]
## Analytical Notes
[Your observations: How is the argument constructed? What assumptions underlie it? How does this relate to the broader project?]Batch Processing Mode
For multiple papers:
- Gather papers: List of PDFs, EPUBs, or citation keys
- Ingest all files: Run
uv run plugins/sociology-skillset/scripts/ingest.py --file <pdf>on each - Prepare identifiers: From lit-search database or references.bib
- Spawn parallel agents: Multiple haiku agents via Task tool
- Collect outputs: Save to
reading-notes/directory
Example batch invocation:
/reading-agent
Batch process these papers:
- /papers/smith2020.pdf (DOI: 10.1086/123456)
- /papers/jones2019.pdf (OpenAlex: W2123456789)
- Citation key: brownMovementSpillover2021The skill will spawn haiku agents in parallel for cost-effective processing.
Haiku Agent Prompt
When spawning agents for batch processing, use this prompt template:
You are a research assistant creating structured reading notes for a sociology literature synthesis project.
## Paper Identifiers
- Citation Key: {citation_key}
- OpenAlex ID: {openalex_id}
- DOI: {doi}
- PDF source: {pdf_path}
## Paper Content
{markdown_content}
## Instructions
Create reading notes following the exact template structure provided. Include:
1. YAML frontmatter with all available identifiers
2. All sections from Bibliographic Info through Analytical Notes
3. At least 3 key quotes with page numbers
4. Specific, observable details rather than vague summaries
Focus on:
- What the paper ARGUES, not just what it studies
- How theory is DEPLOYED, not just what theory is mentioned
- TENSIONS or gaps the paper leaves unresolvedScripts
PDF/EPUB Conversion
Always use ingest.py to add papers — this ensures the PDF, markdown, and references.bib metadata stay linked via the citation key:
uv run plugins/sociology-skillset/scripts/ingest.py --file "/path/to/paper.pdf"Uses docling for PDFs (with --image-export-mode placeholder) and pandoc for EPUBs. Files are organized as library/pdfs/{citekey}.pdf and library/markdown/{citekey}.md.
Setup
Install dependencies:
pip install docling # for PDF conversion
brew install pandoc # for EPUB conversion (or apt-get install pandoc)Integration with Other Skills
From lit-search: Use the database.json to get OpenAlex IDs and DOIs for papers you've identified.
Finding related papers: Use semantic search to discover related papers in your library:
uv run plugins/sociology-skillset/scripts/rag.py search "topic from the paper you just read"To lit-synthesis: Reading notes feed directly into:
- Phase 2: Theoretical mapping (uses Tradition and Key concepts)
- Phase 3: Thematic clustering (uses Findings and Methods)
- Phase 4: Debate mapping (uses Connections and Analytical Notes)
With argument-builder: Key quotes and contribution claims inform prose drafting.
Model Recommendations
| Mode | Model | Rationale |
|---|---|---|
| Single paper (deep) | Opus | Nuanced analysis, theoretical depth |
| Batch processing | Haiku | Cost-effective structured extraction |
Use Opus when you need to understand how an argument is constructed. Use Haiku when you need consistent extraction across many papers.
Output Directory Structure
reading-notes/
├── smith2020-cultural-frames.md
├── jones2019-institutional-logics.md
├── brown2021-movement-spillover.md
└── ...Each file contains full structured notes with frontmatter identifiers for reliable cross-referencing.
Starting the Reading
When the user invokes this skill:
- Identify source: "What paper do you want to read? Provide a PDF path, citation key (for local library lookup), or paste the text."
- Gather identifiers: "What identifiers do you have? I need at least one of: citation key, OpenAlex ID, or DOI."
- Choose mode (if multiple papers): "Single paper or batch? For batch, I'll spawn haiku agents to process in parallel."
- Confirm output location: "I'll save reading notes to
reading-notes/. Does that work, or do you want a different location?" - Begin reading: Convert PDF if needed, then extract structured notes.
Key Reminders
- Identifiers are essential: Every note needs at least one unique identifier in frontmatter (prefer
citation_key) - Quotes need page numbers: Include (p. X) for every quote
- Arguments over summaries: Capture what the paper argues, not just what it describes
- Tensions are valuable: Note unresolved questions and potential gaps
- Consistency enables synthesis: Following the template exactly allows cross-paper analysis