name: paper-to-skill description: "Converts research paper PDFs into structured agent skills, extracting research questions, hypotheses, methodology, key findings, contributions, and limitations. Use when the user wants to study a paper through Claude Code or OpenCode, apply a paper's methods or frameworks while working, or build a reusable knowledge base from academic literature."

Paper-to-Skill Converter

Transform academic research papers into actionable agent skills by extracting structure — not producing summaries.

Philosophy

Research papers contain distilled scientific contributions: hypotheses, methods, experimental designs, and validated findings. This skill extracts that knowledge into a format Claude Code, OpenCode, or another compatible agent can leverage repeatedly.

Extract structure, not summaries. A skill isn't a paper abstract. It's a toolkit of:

Research questions and hypotheses (the "what" and "why")
Methodology and experimental design (the "how")
Key findings and contributions (validated results)
Limitations and future directions (boundaries of the work)
Theoretical frameworks (mental models for the domain)
Formulas, algorithms, and key tables (precise technical artifacts)

Preserve the authors' precision. Technical terms, method names, and metric definitions are intentional. "Transformer attention mechanism" ≠ "a way to focus on relevant parts." Capture the exact formulation.

Layer depth appropriately. Short papers (< 10 pages) → compact skills. Survey papers or multi-paper collections → skills with section files and cross-references.

Modes of Operation

Four paths available. Route based on what the user asks:

1. Full Conversion (Default)

Trigger: User provides one or more PDF paths without special instructions Action: Run all steps below (Steps 0–9) Output: Complete skill with SKILL.md, sections/, glossary, methods, cheatsheet

2. Analyze Only

Trigger: User says "analyze", "just extract", or "I want to review before generating" Action: Run Steps 0–3, then produce a structured extraction report. Stop — do NOT generate skill files. Output: Analysis report for user review

3. Generate from Prior Analysis

Trigger: User has existing analysis notes or previously ran analyze-only Action: Skip Steps 0–3, use the provided analysis as input, run Steps 4–9 Output: Skill files from the provided analysis

4. Update / Fold-in (Existing Skill)

Trigger: User provides new PDF paths and indicates they want to update an existing skill Action: Run Step 0, Step 1, Step 1.5, Step 2. Then skip to Step 5 and run the Update / Fold-in Workflow. Output: Updated existing skill with new papers merged in.

Skill Locations

This converter can run from multiple skill systems. When looking for this converter's helper script or writing the generated paper skill, prefer these locations in order:

Claude Code personal skills: ~/.claude/skills/
OpenCode personal skills: ~/.opencode/skills/
Project-local Claude skills: .claude/skills/
Project-local OpenCode skills: .opencode/skills/

For generated paper skills, pick a destination that the user's host agent can actually discover (see Step 5). When more than one valid root exists, ask the user once and remember the answer for the session.

Step 0 — Out-of-scope check

If no arguments are provided, stop and respond:

"paper-to-skill requires a PDF path, folder, or glob pattern. Usage: paper-to-skill <path-to-pdf-folder-or-glob>... [skill-name-slug]"

Throughout the workflow:

Identify the input paths and the optional skill slug.
If the last argument is not a file, folder, or glob that exists or matches any files, and it looks like a skill slug (e.g. lowercase hyphens, alphanumeric), treat it as SKILL_NAME.
Treat all other arguments as the list of INPUT_PATHS.
If any input path is an existing skill directory (contains SKILL.md and a sections/ sub-folder), or if SKILL_NAME matches an existing skill slug in SKILLS_HOME, flag this run as an Update/Fold-in operation (Mode 4).

Step 1 — Validate input

Verify that there is at least one .pdf file among the INPUT_PATHS. For directories and globs, expand them to find matching PDF files.

If no PDF files are found, stop with a clear error message.

Step 1.5 — Identify paper type

Before extracting, ask the user:

"What kind of paper(s) are these? This helps me choose the best extraction method.

Technical/Quantitative — has formulas, tables, code, algorithms, figures (e.g. ML papers, engineering, CS)

Text-heavy/Qualitative — mostly prose, conceptual frameworks, few formulas (e.g. social science, humanities, review papers)

Not sure — I'll use the fast method and warn you if quality seems limited"

Store the answer as PAPER_TYPE:

Option 1 → PAPER_TYPE=technical
Option 2 → PAPER_TYPE=text
Option 3 → PAPER_TYPE=text

If PAPER_TYPE=technical, inform the user before proceeding:

"📐 Technical mode selected — using Docling for structure-aware extraction (tables, formulas, algorithms preserved as markdown). This takes ~1.5s per page. Starting now…"

If PAPER_TYPE=text, inform:

"📄 Text mode selected — using the fastest suitable extractor. Starting now…"

Step 2 — Extract text from the source PDFs

Run the extraction script, passing the input paths:

SCRIPT_PATH=""
for candidate in \
  "$HOME/.claude/skills/paper-to-skill/scripts/extract.py" \
  "$HOME/.opencode/skills/paper-to-skill/scripts/extract.py" \
  ".claude/skills/paper-to-skill/scripts/extract.py" \
  ".opencode/skills/paper-to-skill/scripts/extract.py"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "Could not find scripts/extract.py for paper-to-skill" >&2
  exit 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <PAPER_TYPE> --install-missing ask

Tip — preflight the environment: run "$PYTHON_BIN" "$SCRIPT_PATH" --check to print a report of which extractors are installed.

This creates:

<tempdir>/paper_skill_work/full_text.txt — combined extracted text of all sources
<tempdir>/paper_skill_work/metadata.json — size, words, pages, token counts, sources

Read <tempdir>/paper_skill_work/metadata.json to inspect the results.

Step 2.5 — Pre-flight cost estimate

Read <tempdir>/paper_skill_work/metadata.json and present the user with an estimate before doing any generation:

📄 Papers detected: <total_sources> paper(s)
<list each source filename from the sources metadata>
📑 Combined Pages: ~<N> | Words: ~<N> | Total tokens: ~<N>K

💰 Estimated token cost (Full Conversion / Update):
   Input  (reading + prompts): ~<N>K tokens
   Output (skill files generated/updated):  ~<N>K tokens
   Total:                           ~<N>K tokens

📁 Files to be generated/updated:
   SKILL.md + section files + glossary + methods + cheatsheet

➡  Proceed with Full Conversion / Update? (or type "analyze only" to preview first)

How to estimate:

Input tokens ≈ estimated_tokens from metadata × 1.3 (prompts overhead per section pass)
Output tokens ≈ sections × per-section budget + 4,000 (SKILL.md) + 4,500 (glossary + methods + cheatsheet)
- Per-section budget midpoint by PAPER_TYPE: text ≈ 1,000, technical ≈ 1,800

Wait for the user to confirm before proceeding. If they say "analyze only", switch to Mode 2.

Step 2.6 — REPL-style access for large paper collections (> 50k tokens)

For paper collections over ~50k tokens, prefer programmatic probes over reading the whole file:

# Size check
wc -w "$FULL_TEXT_PATH"

# Find section offsets
grep -n -E "^\s*(Abstract|Introduction|Method|Results|Discussion|Conclusion)" "$FULL_TEXT_PATH" | head -40

# Pull only the section you need
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# Verify a concept is actually mentioned
grep -c -i "transformer\|attention" "$FULL_TEXT_PATH"

On single papers under 50k tokens, a single read is fine.

Step 3 — Analyze paper structure

Read the first 8,000 characters of the extracted full_text.txt to identify:

Paper title and author(s)
Section structure (Abstract, Introduction, Methods, Results, Discussion, Conclusion)
Research motivation (the real-world problem or gap that drove this research)
Core research question(s) and subject domain
Approximate number of major sections

Then scan for section headings throughout the paper.

If mode is "Analyze Only": produce the extraction report now and stop. Structure:

## Extraction Report — <Title>

### Research Motivation
- **Problem/Gap**: <what real-world problem or knowledge gap motivated this research>
- **Why it matters**: <practical or theoretical significance>

### Research Questions & Hypotheses
- **RQ<N>**: <research question>
- **H<N>**: <hypothesis, if stated>

### Core Contributions
- <Contribution 1>: <what is novel and why it matters>

### Methodology
- **Design**: <experimental/theoretical/survey/etc.>
- **Key Methods**: <specific techniques used>

### Key Findings
- <Finding>: <result with metrics if available>

### Limitations & Future Work
- <Limitation>: <impact on generalizability>

### Suggested Skill Name
`{first-author-lastname}-{core-concept}` — e.g. `vaswani-attention`, `he-resnet`

### Sections Detected
| # | Title | Key Concepts |

Step 4 — Ask purpose (Full Conversion only)

Before generating, ask the user:

"What should this skill help you do? (Pick one or more)

Apply the paper's methods/algorithms in my work

Think with the paper's theoretical frameworks

Reference specific sections, formulas, and results

All of the above"

Use the answer to weight what gets highlighted in the SKILL.md Core section.

Derive DEPTH from the answer:

Answer is only option 3 → DEPTH=reference — lean, fast-lookup sections.
Answer includes option 1, 2, or 4 → DEPTH=study — deeper sections with worked examples.

Step 5 — Determine skill name

If SKILL_NAME was provided, use it as the skill slug. Otherwise, propose two options and let the user choose:

By author-concept: {first-author-lastname}-{core-concept} (e.g. vaswani-attention, he-resnet)
By title: lowercase hyphens from paper title (e.g. attention-is-all-you-need)

Default to author-concept format.

Choose the destination skill root (SKILLS_HOME). Probe the user's filesystem:

| Host agent | Personal skill root (probe in order) | Project-local root | |---|---|---| | Claude Code | ~/.claude/skills | .claude/skills | | OpenCode | ~/.opencode/skills | .opencode/skills |

Selection rules:

If exactly one of the host's candidate roots exists on disk, use it without asking.
If none exist (fresh machine), ask the user which root to create.
If the user explicitly asked for project-local output, prefer the project-local row.
If you cannot identify the host, ask: "Which agent are you running this in — Claude Code or OpenCode?"

Set SKILLS_HOME to the selected root and check if $SKILLS_HOME/<skill_name>/ already exists. If it does, prompt the user to choose:

Update / Fold-in (Mode 4)
Overwrite
Rename

Step 6 — Create skill directory structure

mkdir -p "$SKILLS_HOME/<skill_name>/sections"

Step 7 — Generate section summaries

TOKEN BUDGET RULE — CRITICAL (adaptive):

| | DEPTH=reference | DEPTH=study | |---|---|---| | PAPER_TYPE=text | 800–1,200 tokens | 1,000–1,800 tokens | | PAPER_TYPE=technical | 1,200–1,800 tokens | 2,000–3,000 tokens |

For EACH major section identified in Step 3, create $SKILLS_HOME/<skill_name>/sections/<NN>-<slug>.md using the structure below.

Adapt emphasis based on PAPER_TYPE:

technical → prioritize "Formulas & Algorithms", "Tables & Figures", "Implementation Details"
text → prioritize "Theoretical Framework", "Key Arguments", "Conceptual Models"

# Section N: <Full Title>

## Core Idea
<1–2 sentences: the single most important thing this section contributes>

## Research Context
- **Motivation**: <why this aspect of the problem needs to be addressed>
- **Problem addressed**: <what gap or question this section tackles>
- **Relation to paper's thesis**: <how it supports the overall argument>

## Key Concepts
- **<Term>**: <precise definition in 1 sentence>
(5–10 most important terms from this section)

## Methodology Details *(methods sections only)*
- **Design**: <experimental setup, data sources, sample>
- **Procedure**: <step-by-step method>
- **Metrics**: <how results are measured>

## Formulas & Algorithms *(technical papers only — omit if PAPER_TYPE=text)*
<!-- Reproduce the most important formula or algorithm from this section. -->
```<math or pseudocode>
<key formula or algorithm>

What it computes: <one line>
Variables: <brief definition of each variable>

Tables & Figures (technical papers only — omit if PAPER_TYPE=text)

Worked Example (DEPTH=study only — omit for DEPTH=reference)

Key Findings

<Finding with metric/evidence>
<Finding with metric/evidence>
<Finding with metric/evidence>

Connects To

Section N: <why this section relates>
<External work>: <connection to other papers or concepts>


---

## Step 8 — Generate supporting files

### glossary.md
Create `$SKILLS_HOME/<skill_name>/glossary.md`:
- Every significant technical term from the paper(s), alphabetically sorted
- Format: `**Term** — definition (Section N)`
- Max 1,500 tokens

### methods.md
Create `$SKILLS_HOME/<skill_name>/methods.md`:
- All concrete methods, algorithms, experimental procedures from the paper(s)
- Format: `## Method Name\n**When to use**: ...\n**How**: ...\n**Assumptions/Limitations**: ...`
- Max 2,000 tokens

### cheatsheet.md
Create `$SKILLS_HOME/<skill_name>/cheatsheet.md`:

**This is the most differentiated layer of the skill — treat it as a reasoning aid, not a keyword list.**

Prioritize, in order:
1. **Decision rules** — "When X, use method Y, because Z." The conditional logic for applying the paper's methods.
2. **Comparison tables** — competing methods/approaches scored on dimensions the authors evaluate.
3. **Key results summary** — the headline numbers and what they mean practically.
4. **Hyperparameter guidance** — specific numbers, thresholds, or defaults from the paper.
5. **Reproducibility notes** — what you need to replicate the results (data, compute, libraries).

- Format mostly as compact tables and decision rules.
- Max 1,200 tokens.

---

## Step 9 — Generate the master SKILL.md

**CRITICAL TOKEN BUDGET: Keep SKILL.md body under 4,000 tokens.**

Create `$SKILLS_HOME/<skill_name>/SKILL.md`:

```markdown
---
name: <skill_name>
description: "Knowledge base from \"<Paper Title>\" by <Author(s)> (<Year>). Use when applying <authors>'s methods for <key topics>, studying the paper, or referencing its contributions."
---

<!-- argument-hint: [topic, method name, or section] -->

# <Paper Title>
**Authors**: <Author(s)> | **Year**: <YYYY> | **Pages**: ~<N> | **Venue**: <conference/journal> | **Generated**: <YYYY-MM-DD>

## How to Use This Skill

- **Without arguments** — load core contributions and methods for reference
- **With a topic** — ask about `attention`, `loss function`, or another indexed topic; I find and read the relevant section
- **With section** — ask for `sec03`; I load that specific section
- **Browse** — ask "what sections do you have?" to see the full index

When you ask about a topic not covered in Core Contributions below, I will read
the relevant section file before answering.

---

## Abstract
<paper's abstract, condensed to 2–3 sentences>

## Research Motivation
<1–2 sentences: what real-world problem or knowledge gap motivated this research, why existing solutions are insufficient>

## Core Contributions & Methods
<!-- ~2,000 tokens: the paper's most important contributions, methods, and findings.
     Preserve exact method names. Write as "Use X when Y", "X outperforms Y because Z".
     This is a toolkit, not a summary. -->

<generate 2,000 tokens of the most critical contributions and methods here>

---

## Section Index

| # | Title | Key Concepts |
|---|-------|--------------|
| [sec01](sections/01-<slug>.md) | <Title> | <concept1>, <concept2> |
| [sec02](sections/02-<slug>.md) | <Title> | <concept1>, <concept2> |
...

## Topic Index

<!-- Alphabetical. Major terms/methods → section(s) that cover them. -->
- **<Term>** → sec<N>[, sec<N>]
- **<Term>** → sec<N>

## Supporting Files

- [glossary.md](glossary.md) — all key terms with definitions
- [methods.md](methods.md) — all methods, algorithms, and procedures
- [cheatsheet.md](cheatsheet.md) — quick reference tables and decision guides

---

## Scope & Limits

This skill covers the paper content only. For hands-on implementation in your codebase,
combine with project-specific tools. For topics beyond this paper, check related skills
or ask the agent directly.

Step 10 — Cleanup and report

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" - <<'PY'
import os
import shutil
import tempfile
from pathlib import Path
shutil.rmtree(
    os.environ.get("PAPER_SKILL_WORKDIR", Path(tempfile.gettempdir()) / "paper_skill_work"),
    ignore_errors=True,
)
PY

Then report to the user:

✅ Skill created: $SKILLS_HOME/<skill_name>/

📄 Paper: <Paper Title> — <Author(s)> (<Year>)
📑 Pages: ~<N> | Sections: <N>

Files generated:
  SKILL.md         — core contributions + index   (~X tokens)
  sections/        — <N> section summaries        (~X tokens each, ~X total)
  glossary.md      — key terms                    (~X tokens)
  methods.md       — methods & algorithms         (~X tokens)
  cheatsheet.md    — quick reference              (~X tokens)
  ─────────────────────────────────────────────────────
  Total skill size: ~X tokens (loaded on-demand, not all at once)

Usage:
  Ask for <skill_name>                  → load core contributions
  Ask <skill_name> about <topic>        → find and explain a topic
  Ask <skill_name> for sec<N>           → dive into a specific section

Reload (if your agent doesn't auto-detect new skills):
  Claude Code:  restart the session
  OpenCode:     restart the session

Update / Fold-in Workflow

When performing an Update/Fold-in operation on an existing skill at $SKILLS_HOME/<skill_name>/:

1. Read Existing Skill Structure

Read $SKILLS_HOME/<skill_name>/SKILL.md to parse the existing Section Index, Topic Index, metadata, and Core Contributions.
List all files in $SKILLS_HOME/<skill_name>/sections/ to find the highest section number.
Read glossary.md, methods.md, and cheatsheet.md.

2. Match Content & Identify Revisions vs. Additions

Analyze the new extracted text to identify if the new content represents:

Updates to existing sections: merge new details into existing section files.
New additions: create new section summary files numbered after the highest existing section.

3. Generate or Update Section Summary Files

For each new or revised section, follow Step 7 formatting.

4. Merge Supporting Files

Merge glossary.md: combine and alphabetize existing and new terms.
Merge methods.md: append new methods with consistent formatting.
Merge cheatsheet.md: integrate new comparison rules and decision tables.

5. Re-generate the Master SKILL.md

Update metadata, section count, and dates.
Fold in high-impact contributions from new papers.
Append new sections to the index.
Merge topic index alphabetically.

6. Cleanup and Proceed to Step 10

Quality Rules

Extract structure, not summaries — capture research questions, methods, findings, contributions; not section recaps
Preserve the authors' precision — "Transformer self-attention" ≠ "a way to weigh inputs"; keep exact naming
Density over completeness — a 1,000-token extraction beats a 10,000-token excerpt
Practitioner voice — write "Use X when Y", not "The paper explains X"
Front-load SKILL.md — most important content comes first
Section files are on-demand — they don't count against skill budget until loaded
Never copy raw paper text — always synthesize, extract signal
Topic index is critical — it's how the agent navigates to the right section file
Cite with precision — include table/figure/equation numbers when referencing specific results
Distinguish claims from evidence — note whether findings are statistically validated, qualitative, or theoretical

Convertisseur d'article en compétence

Recommandé pour