deep-reading
Use when reading books, academic papers, or long-form documents from URLs or PDFs and needing structured analysis, comprehension, or comparison
Best use case
deep-reading is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when reading books, academic papers, or long-form documents from URLs or PDFs and needing structured analysis, comprehension, or comparison
Teams using deep-reading should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/deep-reading/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How deep-reading Compares
| Feature / Agent | deep-reading | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when reading books, academic papers, or long-form documents from URLs or PDFs and needing structured analysis, comprehension, or comparison
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Deep Reading Agent v2
## Overview
深度阅读助手,支持 YouTube 视频、PDF 书籍、播客、网页等内容的深度阅读和笔记管理。基于 Mortimer Adler 的《如何阅读一本书》实现三层阅读:检视阅读、分析阅读、对比阅读。
## When to Use
当用户说以下内容时,自动触发此 skill:
- "帮我看/读/学习这个视频" + YouTube URL
- "深度阅读这个内容"
- "分析这个视频/文章"
- "阅读这本书" + PDF 路径
- "播放 xxx" (已下载的内容)
## Quick Start - AI 操作流程
### 1. YouTube 视频处理
当用户提供 YouTube URL 时:
```bash
# Step 1: 下载内容
cd /Users/liweixin/.claude/skills/deep-reading
python3 -m src.fetcher.cli "YOUTUBE_URL"
# Step 2: 生成检视阅读报告
python3 -m src.processor.cli youtube_VIDEO_ID
# Step 3: 告诉用户笔记已生成,可在 Obsidian 查看
```
### 2. PDF 书籍处理
当用户提供 PDF 文件路径或 Zotero 目录时:
```bash
# Step 1: 处理 PDF(提取文本和元数据)
python3 -m src.fetcher.cli "/path/to/file.pdf"
# 或提供包含 PDF 的目录(如 Zotero storage)
python3 -m src.fetcher.cli "/Users/liweixin/Zotero/storage/VDEZ72XG"
# Step 2: 生成检视阅读报告
python3 -m src.processor.cli pdf_XXXXXX
# Step 3: 告诉用户笔记已生成
```
### 3. 播放已下载内容
```bash
# 列出所有已下载内容
python3 -m src.player.cli -l
# 播放指定内容 (交互式,需要用户操作)
python3 -m src.player.cli SOURCE_ID
```
### 4. 查看生成的笔记
笔记保存在: `~/smart notes/DeepReading/Sources/`
## 完整工作流示例
**用户:** "帮我深度阅读这个视频 https://www.youtube.com/watch?v=RSNuB9pj9P8"
**AI 操作:**
```bash
cd /Users/liweixin/.claude/skills/deep-reading
# 1. 下载视频内容
python3 -m src.fetcher.cli "https://www.youtube.com/watch?v=RSNuB9pj9P8"
# 2. 生成检视阅读报告到 Obsidian
python3 -m src.processor.cli youtube_RSNuB9pj9P8
```
**AI 回复:**
"已完成!
- 📥 下载了视频: [标题]
- 📝 生成了检视阅读报告: ~/smart notes/DeepReading/Sources/[标题].md
- 🎧 如需播放音频,请告诉我
笔记包含:
- 视频元信息
- 快速摘要(待 AI 分析后填充)
- 核心观点
- 关键概念
- 思考问题
是否需要我帮你播放这个视频?"
**用户:** "阅读这本书 /Users/liweixin/Zotero/storage/VDEZ72XG"
**AI 操作:**
```bash
# 1. 处理 PDF
python3 -m src.fetcher.cli "/Users/liweixin/Zotero/storage/VDEZ72XG"
# 2. 生成报告
python3 -m src.processor.cli pdf_XXXXXX
```
**AI 回复:**
"已完成!
- 📖 处理了书籍: [标题]
- 📝 生成了检视阅读报告: ~/smart notes/DeepReading/Sources/[标题].md
- 📄 共 XX 页
笔记包含:
- 书籍元信息(标题、作者、页数)
- 快速摘要(待 AI 分析后填充)
- 核心观点
- 关键概念
- 思考问题"
## 缓存和数据位置
```
~/.deep-reading/
├── cache/
│ ├── youtube/{video_id}/
│ │ ├── audio.mp3 # 音频文件
│ │ ├── transcript.vtt # 带时间戳的字幕
│ │ ├── transcript.txt # 纯文本字幕
│ │ └── metadata.json # 视频元数据
│ └── pdf/{pdf_id}/
│ ├── source.pdf # PDF 副本
│ ├── content.txt # 提取的文本
│ └── metadata.json # PDF 元数据
├── db/deep_reading.db # SQLite 数据库
└── config.py # 配置文件
~/smart notes/DeepReading/
└── Sources/ # Obsidian 笔记
└── {标题}.md
```
## 播放控制键 (告知用户)
| 按键 | 功能 |
|------|------|
| `空格` | 暂停/播放 |
| `j` | 快进 30 秒 |
| `k` | 后退 10 秒 |
| `J` | 快进 60 秒 |
| `K` | 后退 30 秒 |
| `+` / `=` | 加速 |
| `-` | 减速 |
| `q` | 退出 |
## 错误处理
1. **无字幕**: 某些视频可能没有字幕,会报错
2. **网络问题**: 下载失败时提示用户检查网络
3. **已存在**: 如果内容已下载,会使用缓存
4. **PDF 解析**: 需要安装 PyMuPDF (`pip install PyMuPDF`)
## 后续功能 (M2-M6)
- M2: TUI 播放器 + 字幕同步
- M3: AI 自动章节分割 + 概念卡片
- M4: Obsidian 双链自动生成
- M5: 播客支持
- M6: 网页支持
## 笔记编写规范
### Obsidian 双向链接 [[]] 规则
**重要:只在目标文件已存在时才使用 `[[]]` 链接!**
- ❌ **禁止**:添加指向不存在文件的空链接,如 `[[效价]]`、`[[强化学习]]`
- ✅ **正确**:先创建笔记文件,再在其他笔记中添加 `[[文件名]]` 链接
- ✅ **正确**:对于尚未创建的概念,使用纯文本描述,如 "效价(Valence)"
### 检查链接是否有效
添加 `[[]]` 链接前,确认文件存在:
```bash
ls "~/smart notes/DeepReading/Sources/目标文件名.md"
```
### 示例
```markdown
# 正确做法
- 父笔记:A Brief History of Intelligence.md
- 相关概念:效价(Valence)、两侧对称动物
# 错误做法(目标文件不存在)
- 父笔记:[[A Brief History of Intelligence]]
- 相关概念:[[效价]]、[[两侧对称动物]]
```Related Skills
deepstack
Detects your project's full technology stack, then generates a comprehensive research prompt tailored to a specific topic like security, performance, or testing.
deepagents-filesystem
Using FilesystemMiddleware with virtual filesystems, backends (State, Store, Filesystem, Composite), and context management for Deep Agents.
deep-review
Run a comprehensive deep review combining architecture analysis, code review, error handling audit, type design analysis, comment verification, test coverage analysis, accessibility audit, localization review, concurrency analysis, performance analysis, code simplification, and platform-specific reviews (iOS, macOS, Android, Angular, TypeScript, Next.js, Vue.js, Python, Django, Ruby, Rust, Go, Rails, Flutter, Java/Spring Boot, C#/.NET, PHP/Laravel, C/C++, React Native, Svelte/SvelteKit, Elixir/Phoenix, Kotlin Server, Scala, Terraform, Shell/Bash, Docker, Kubernetes, GraphQL, GitHub Actions, SQL, Swift Data). Platform reviewers are automatically included when relevant. Distinguishes between NEW issues (introduced by PR) and PRE-EXISTING issues (technical debt). Use when reviewing PR changes, before merging, or for thorough code quality assessment. Supports flags --pr, --branch, --changes for scope detection.
deep-research
Multi-agent deep research pipeline for complex questions (EIP analysis, architecture decisions, cross-client comparisons, protocol design). Use when single-shot answers are insufficient and you need decomposition, parallel investigation, adversarial critique, and a formal output document.
deep-mem
Search and retrieve memories from Nowledge Mem knowledge base with progressive disclosure. This skill should be used when the user asks to search memories, recall past knowledge, find saved information, look up conversation history, expand thread details, or mentions keywords like "记忆", "知识库", "之前说过", "我保存的", "历史对话".
deep-dive
再帰的な質問で要件・課題を深堀りし、推測をなくし、品質・信頼性を向上させるスキル。トリガーキーワード: 「深堀り」「検討して」「ultrathink」「よく考えて」「他にはないか」「他の案は?」。使用場面: 新機能設計、問題解決、技術調査、学習用途、機能追加など。
chatgpt-deep-research
DEPRECATED - Use gpt-researcher skill instead. This browser automation approach has been replaced with the local GPT-Researcher framework using OpenAI o1.
beazley-deep-python
Write Python code in the style of David Beazley, author of Python Cookbook. Emphasizes generators, coroutines, metaprogramming, and understanding Python's internals. Use when writing advanced Python that requires deep language mastery.
aposd-designing-deep-modules
Enforce Design-It-Twice workflow: generate 2-3 radically different approaches, compare them, then implement. Use when designing modules, APIs, or classes before implementation. Triggers on: design, create class, add module, implement feature, new service, API design, before implementing. Produces structured design document with approaches, comparison table, choice rationale, and depth check.
analyzing-deeply
Performs deep structured analysis on complex or ambiguous problems. Activates when problems are unclear, have multiple perspectives, or require careful thinking before proceeding. Uses ultrathink methodology for systematic exploration of problem space.
academic-deep-research
Transparent, rigorous research with full methodology — not a black-box API wrapper. Conducts exhaustive investigation through mandated 2-cycle research per theme, APA 7th citations, evidence hierarchy, and 3 user checkpoints. Self-contained using native OpenClaw tools (web_search, web_fetch, sessions_spawn). Use for literature reviews, competitive intelligence, or any research requiring academic rigor and reproducibility.
22-understand-deep-150
[22] UNDERSTAND. Deep research from all sources — internal (code, git, logs) AND external (web, docs, best practices). Use when choosing libraries, investigating solutions, understanding legal/technical questions, comparing approaches, or anytime you need comprehensive knowledge from both project context and world knowledge. Triggers on "research", "investigate", "find best approach", "what do others do", "compare options", or complex questions requiring multiple sources.