Belongs to the SOIA personal knowledge management domain (
soia-pkm-*) "interpretation" step: for long articles/papers clipped into the vault, the AI directly provides a structured interpretation, helping you judge whether this piece is worth investing in before digging deeper (distill).
Client-readable description
What this skill can do
For long articles/papers clipped into the vault, the AI directly provides an interpretation: a five-part structure of content overview / core points / key insights / critical perspective / further reading. Default is quick read (2-3 sentences per section); saying "close read/deep interpretation" upgrades it to section-by-section expansion + argument chain verification. Produces a standalone <原文件名>-AI解读.md, placed in the same directory as the original file and double-linked back to the original, never touching the original, never writing into the original's ## 我的看法 section.
| Client wants | Skill will do | Client can see |
|---|---|---|
| Quickly judge whether a long article/paper is worth a close read | Quick read: five-part AI interpretation with 2-3 sentences per section | <原文件名>-AI解读.md, double-linked back to the original |
| Close-read an important article, needing section-by-section argument verification | Close read: section-by-section expansion + argument chain verification, marking places the original does not make clear | A more detailed interpretation file, with at least one critical perspective |
| Batch-interpret the same batch of articles (more than 3) | First report the list (filenames + topics), wait for scope confirmation | List to be interpreted → per-article interpretation files + summary receipt |
| Want to refine this into your own views, rather than see what the AI thinks | Indicate this is not this skill's responsibility, point to soia-pkm-distill |
boundary explanation, will not be mistaken for your views |
How clients use it
- Provide the article to interpret: say "this one" (= the article involved in the current conversation) or give the filename/title, and the Agent locates it under
<vault-articles-dir>/. - Single article: the Agent executes directly, no extra confirmation needed. Batch (a single request involving more than 3 articles): the Agent first lists the items (filenames + rough topics), waits for the client to confirm the interpretation scope (all / pick a few / pause), then executes one by one.
- Depth defaultquick read(five-part, 2-3 sentences per section); when the client says "close read" "deep interpretation" "section-by-section verification", upgrade toclose read(section-by-section expansion + argument chain verification, see two depth levels)。
- Interpretation alwayswrites to disk first, reports after: the produced
<原文件名>-AI解读.mdis placed in the same directory as the original file, the body double-links back to the original, never modifying or overwriting the original file (including the## 我的看法section). - The final reply must give the client a complete receipt: depth, number of articles, output file paths, how many places were marked "not clear in the original/needs verification", and remaining risks.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-interpret -y
| Dependency | Type | Install / configure | How to handle when missing |
|---|---|---|---|
| Obsidian vault (any structure) | Method reference, not a hard dependency | No separate installation required | This skill can interpret any Markdown/plain-text article; it does not require the file to be inside a vault. Only when vault frontmatter and the two-way-link return convention are involved should the vault context be referenced |
soia-pkm-clip-* series |
Upstream source, not a hard dependency | No installation required, unless the client needs to archive before interpreting | It is merely a common input source; this skill does not call or modify any files of these skills |
soia-pkm-distill |
Downstream/parallel skill, not a dependency | No installation required | This skill does not write ## 我的看法; when the client wants "my views", prompt them to use that instead, and do not execute it in its place |
Configuration convention:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-interpret/config.yml
SOIA_PKM_INTERPRET_CONFIG_FILE=<custom-config-path>
- This skill is a pure-document / pure-prompt skill with no scripts, and usually does not require
config.yml; if the client wants to fix preferences such as "default depth" or "batch confirmation threshold", this file can be created, with fields consistent with this document. - It does not need to, and should not, read any API key, cookie, session, or account credentials—this skill only reads the text files provided by the client.
Logs and completion receipt
Every execution must let the client see the full process of determination, depth, batch confirmation, and output. Minimum receipt format:
完成:<一句话说明本次解读了什么文件、什么深度>。
日志摘要:
- 定位:<文件路径,如何找到的(客户直接给的 / 在 vault 内搜到的)>
- 深度:<快读 / 精读,以及判定依据(客户是否明确要求精读)>
- 批量确认:<单篇写"不适用";批量则写是否先报清单、客户确认了什么范围>
- 待核对:<解读中标注"原文未明确/需核对"的条数,简述位置>
文件变化:
- 新建:<绝对路径,`<原文件名>-AI解读.md`>
- 未改动:<原文件路径,确认未被覆盖,`## 我的看法` 段未被触碰>
问题与下一步:
- <值不值得深挖的判断 / 建议客户回复"精读"升级 / 建议客户对这篇跑 soia-pkm-distill;没有则写"无,可直接使用产出">
Boundary with soia-pkm-distill (must be observed)
This is where this skill is most easily confused—the boundary must be prominent and hold by default before every execution:
| Dimension | soia-pkm-interpret (this skill) | soia-pkm-distill |
|---|---|---|
| Interpretation subject | AI Reads the full text and gives a judgment | UserSpeaks orally; the AI only helps ask questions and helps put the text down |
| Interaction mode | Generates a five-part interpretation in one go, not question-by-question and answer-by-answer | Socratic style, raising only one question at a time and waiting for the user to answer |
| Output content | The AI's overview / key points / inspirations / critique / extensions | The user's own position, experience, and judgment |
| Placement location | Standalone file <原文件名>-AI解读.md |
Within the original file, the ## 我的看法 section |
| Timing of use | Just archived, not yet finished reading, and wanting to first judge whether it is worth digging deeper | Already decided to take a stance on this piece and to distill views |
| Red line | Never write into the original text's ## 我的看法 section—that is exclusive to the user |
Never take a stance on the user's behalf—the content must come from the user's answers |
- If during interpretation the client says "How do I view this piece", "Help me distill my views", "My take on this piece is...", uniformly prompt: "This is the responsibility of
soia-pkm-distill, do you want to switch over?", and do not answer or write on their behalf within this skill. - The product of interpret isdecision support: helping the client judge "whether this piece is worth going into distill for deeper digging"; it is not the viewpoint itself, and should not be mistaken for the client's viewpoint.
Two depth levels
| Depth | Trigger words | Output form |
|---|---|---|
| Quick read(default) | When intensive reading is not explicitly requested | Five-part format, 2-3 sentences per part, covering the full text but not expanding section by section |
| Close Reading | "Close Reading" "In-depth Interpretation" "Section-by-Section Verification" | On the basis of the five-section format, expand section by section + argument chain verification (see below) |
Close Reading Mode: Argument Chain Verification
During close reading, before the "Critical Perspective" section, first conduct a section-by-section argument chain verification, confirming point by point:
- What is the core argument of this section?
- What is the evidence/data/citation supporting this argument, and from which paragraph of the original text does it come?
- Is there a leap between the argument and the evidence—the evidence can only support a weaker conclusion, but the original text asserts a stronger conclusion?
- For premises/definitions/boundary conditions that the original text does not clarify, mark "not explicit in the original text/needs verification"; do not fill them in on behalf of the original text.
The verification results serve as the basis for the "Critical Perspective" section, rather than being listed in a separate paragraph; avoid the close reading output becoming two disconnected pieces: "overview + verification checklist."
Five-Section Interpretation Structure (Output Template)
Output file <原文件名>-AI解读.md The body structure is fixed as:
# AI 解读:《{文章标题}》
> 原文:[[<原文件名>]]
> 解读深度:{快读 / 精读}
> 解读时间:{YYYY-MM-DD}
---
## 内容总览
{快读 2-3 句 / 精读可展开到一小段:文章讲了什么、核心结论是什么}
## 核心要点
{分条目提炼文章主干信息,通常 4-8 条,每条给出处(如"见第 3 节"/"见引言部分")}
- **要点 1**(出处:……):……
- **要点 2**(出处:……):……
## 关键启发
{至少 3 条,每条说明"是什么 → 为什么重要 → 对你可能怎么用",不写"这个方法很有前景"式空话}
- **启发 1**:……
- **启发 2**:……
- **启发 3**:……
## 批判视角
{至少 1 条"这篇可能错在哪"——论证漏洞、证据不足、以偏概全、时效性问题等;精读模式基于上面的论证链核查填写;不确定处写"原文未明确/需核对",不替作者圆场也不无端苛责}
- ……
## 延伸阅读
{2-4 条值得继续探索的方向或值得对照读的资料;如果 vault 内已有相关文章/MOC,用双链标出}
- ……
- All uncertain content must be explicitly marked "not explicit in the original text/needs verification"; never fabricate data, experiments, or conclusions that the original text does not contain.
- When citing the original text, give the source paragraph (section title, "Introduction"/"Paragraph X", etc.), so the client can check back against the original text.
Locate the article
- When the client says "this article" = the article involved in the current conversation; otherwise use the filename/title under
<vault-articles-dir>/to locate via Glob/Grep. - Read the article's
## 原文paragraph (the clip family has a unified body structure:## 摘要 / 原文 / 我的看法 / 关联); when there is only an abstract and no full text, before interpreting, first inform the client that "this time it is based on the abstract rather than the full text, so the confidence level of the conclusions is relatively low," and note this in the "Content Overview" of the interpretation file. - Do not read or modify the client's existing
## 我的看法paragraph—that content is unrelated to this skill.
Implementation Rules
- Path: same directory as the original filesame directory, filename
<原文件名>-AI解读.md。 - frontmatter: create a new independent frontmatter (not a copy of the original file's frontmatter), containing at least:
interpreted_from: <原文件名或相对路径>
interpret_depth: <quick 或 deep>
interpreted_at: <YYYY-MM-DD>
- In the body, use
[[<原文件名>]]double-link back to the original text, for convenient bidirectional jumping. - Never overwrite, never edit the original file—including frontmatter,
## 摘要、## 原文、## 我的看法、## 关联any paragraph; if an interpretation file with the same name already exists, first inform the client and wait for confirmation on whether to overwrite the old interpretation (an overwrite-type risky action requires prior confirmation).
Batch Strategy
- Single article (this request involves only 1 article): execute directly, without additional confirmation.
- Batch (this request involves more than 3 articles, such as "interpret all the articles under this MOC"): first list them (filename + one-sentence topic guess), report "N articles in total; which ones do you suggest interpreting first/all of them?", wait for the client to confirm the scope, then execute one by one; each article still follows "save to disk first, report afterward," and after all are completed, provide a consolidated receipt (see Logs and Completion Receipt)。
- 2-3 articles: regarded as a small batch and can be executed directly, but still report in one sentence which articles will be processed before starting.
Delivery Order
Save to disk first, report afterward: the output file must first be written to disk and pass content verification (the file actually exists, the five sections are complete, and there is at least one critical perspective), and only then send a completion receipt to the client. It is not allowed to first describe it as "completed" and then fill in the file afterward.
Boundaries and Limitations
- Do not replace
soia-pkm-distill: This skill never writes into the original file's## 我的看法section, nor does it impersonate the client's stance in the first person. - Do not fabricate: Any information not provided in the original text must be marked "not specified in the original / needs verification"; do not invent data, experiments, citations, or conclusions.
- Do not perform external retrieval for verification: Interpretation is based on the original text itself; if the critical perspective relies on external fact-checking, only remind the client that "this point needs to be verified by the client themselves"; do not arbitrarily fabricate verification results.
- Do not perform translation/conversion: Foreign-language articles must first be understood via
soia-pkm-translateor by the client themselves before interpretation; this skill does not coversoia-pkm-transform's product conversion (PPT/mind map, etc.) responsibilities. - This skill is a pure document / pure prompt skill, carries no scripts, and does not read credentials such as accounts, cookies, or sessions.
Closed-loop position
clip(收) → organize(整理) → ★interpret(AI 解读,辅助判断) → distill(点:你的观点) → compose(写) → publish(发)
- Upstream:
soia-pkm-organize's organized article library is the main input source; you can also directly interpret a single article that has just beenclipin and has not yet been organized. - Downstream: after the client reads the AI interpretation and decides "this article is worth digging into", they turn to
soia-pkm-distillto refine their own viewpoint;soia-pkm-interpret's output is not a required input fordistillorcompose, it is only a decision reference.
Third-party skill relationships
| Third-party skill | Relationship to soia-pkm-interpret Relationship to |
|---|---|
soia-pkm-distill |
The division of labor boundaries is shown in the table above; this skill does not call it, nor does it write its exclusive ## 我的看法 section |
soia-pkm-clip-* series |
Common upstream source, not a dependency; this skill does not modify these skills' files |
soia-pkm-organize |
Common upstream, not a dependency; this skill does not require the article to have been organized by organize |
soia-pkm-translate |
Translation prerequisite for foreign-language articles, not a dependency; this skill does not perform translation |
Receipt after completion
After executionmustoutput to the user (do not silently finish):
- What was done — a one-sentence summary of which file was interpreted this time, at what depth, and whether it was batch processing.
- File changes — the full path of the newly created interpretation file; clearly state that the original file (including
## 我的看法) was not modified. - Next steps — remind the client of the basis for judging "whether this article is worth digging into"; in quick-read mode, remind them they can reply "deep read" to upgrade; when there are points marked "not specified in the original / needs verification", list them together and suggest the client verify them themselves or use
soia-pkm-distillto state their stance.