MinerU Skill

An AI Skill that transforms PDF documents into clean Markdown using MinerU's VLM engine.

中文文档 | English

---

🤖 What is a Skill?

A Skill is an AI capability package that extends your AI assistant's abilities. When you ask the AI to do something, it automatically:

1. Recognizes the task from your natural language
2. Activates the appropriate skill
3. Executes the task using the skill's tools
4. Delivers results back to you

Example Conversation

You: 解析这些考研数学真题 PDF 到我的 Obsidian

AI: 📚 发现 40 个 PDF 文件
    ⏳ 开始并行解析 (5 workers)...
    ✅ 1993年考研数学（一）真题 → Markdown
    ✅ 1994年考研数学（一）真题 → Markdown
    ...
    ✅ 完成！已保存到 Obsidian/考研/数学一/

---

🚀 Install as Skill

Vercel Skills (Recommended)

npx skills add Nebutra/MinerU-Skill

Supported: OpenCode, Claude Code, Codex, Cursor, 35+ more

OpenClaw

# Clone to your skills directory
git clone https://github.com/Nebutra/MinerU-Skill.git ~/openclaw-skills/mineru/

# Set API token
export MINERU_TOKEN="your-token-here"  # Get from https://mineru.net/user-center/api-token

ClawHub

# Install via clawhub CLI
clawhub install mineru

Claude Code / Cursor / Windsurf

# Clone to AI skills folder
git clone https://github.com/Nebutra/MinerU-Skill.git ~/.claude/skills/mineru/

---

💬 Usage Examples

Single File

把 ./document.pdf 解析成 Markdown

Batch Directory

解析 ./papers/ 目录下的所有 PDF，输出到 ./output/

Direct to Obsidian

把这些 PDF 解析后直接保存到我的 Obsidian Vault

Chinese Example

解析 1987-2025 年考研数学真题，保存到 Obsidian/考研/数学一/
用 10 个并发，跳过已处理的文件

---

⚡ Features

Feature	Description
📄 PDF Input	Local files, URLs, batch directories
📝 Output	Markdown + JSON metadata + Images
🔢 LaTeX	Math formulas preserved
📊 Tables	Structure extraction
🖼️ Images	Auto-extracted to images/
⚡ Async	15x parallel uploads
🔄 Resume	Skip processed files
📁 Obsidian	Direct vault output

---

🛠️ CLI Reference

You can also use directly via CLI:

# Single file
python scripts/mineru_v2.py --file ./doc.pdf --output ./output/

# Batch with resume
python scripts/mineru_v2.py \
  --dir ./pdfs/ \
  --output ~/Obsidian/MyVault/ \
  --workers 10 \
  --resume

Option	Description
--dir PATH	Input directory
--file PATH	Single file
--output PATH	Output directory
--workers N	Concurrency (default: 5)
--resume	Skip processed files
--token TOKEN	API token

---

📁 Output Structure

output/
├── document-name/
│   ├── document-name.md    # Main Markdown
│   ├── images/             # Extracted images
│   │   ├── image_0_0.png
│   │   └── ...
│   └── content.json        # Metadata
└── ...

---

📊 Performance

Test: 10 PDFs, ~15 pages each (MacBook Air M1)

Configuration	Time	Speed
Sequential	8.5 min	1.2 files/min
Async (5 workers)	3.2 min	3.1 files/min
Async (15 workers)	1.8 min	5.6 files/min

---

🔑 Get API Token

1. Visit MinerU
2. Create free API token
3. Set environment:

export MINERU_TOKEN="your-token-here"

Free Tier: 2000 pages/day, 200MB max file

---

⭐ Star History

---

🏗️ Skill Architecture

┌─────────────────────────────────────────────────────────────┐
│                    USER REQUEST                             │
│      "Parse these PDFs to Markdown"                         │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    AI ASSISTANT                             │
│  • Recognizes PDF parsing task                             │
│  • Activates MinerU skill                                  │
│  • Reads SKILL.md for instructions                         │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  MINERU SKILL ENGINE                        │
│  Scanner ──► Scheduler ──► Worker Pool (N workers)         │
│                           │                                 │
│                           ▼                                 │
│  API: Get URL ──► Upload ──► Poll ──► Download             │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      OUTPUT                                 │
│     Markdown + JSON + Images ──► Obsidian/Files            │
└─────────────────────────────────────────────────────────────┘

---

🤝 Contributing

1. Fork → Branch → Commit → Push → PR

---

📝 License

MIT License - see LICENSE

---

🙏 Acknowledgments

• MinerU - PDF parsing API
• OpenClaw - AI skill framework
• ClawHub - Skill marketplace

---