Belongs to the SOIA personal knowledge management domain (
soia-pkm-*)'s "interpretation" step: for long-form articles/papers clipped into the vault, the AI directly provides a structured interpretation, helping you judge whether this article is worth investing in before digging deep (distill).
Client-readable description
What this skill can do
For long-form articles/papers clipped into the vault, the AI directly provides an interpretation: a five-part format of content overview / core points / key inspirations / 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 an independent <原文件名>-AI解读.md, placed in the same directory as the original file and double-linked back to the original, never touching the original text, never writing into the original's ## 我的看法 section.
| What the client wants | What the skill will do | What the client can see |
|---|---|---|
| Quickly judge whether a long-form article/paper is worth a close read | Quick read: a five-part AI interpretation with 2-3 sentences per section | <原文件名>-AI解读.md, double-linked back to the original |
| Closely read an important article and verify the argument section by section | Close read: section-by-section expansion + argument-chain verification, marking places the original does not make explicit | A more detailed interpretation file, with at least one critical perspective |
| Interpret the same batch of articles in bulk (more than 3) | First report a list (file names + topics) and wait for scope confirmation | List to be interpreted → interpretation file per article + summary receipt |
| Wants to refine this article into their own views, rather than see what the AI thinks | Indicate that this is not this skill's responsibility, and point to soia-pkm-distill-article-opinion |
Boundary explanation, will not be mistaken for your views |
How the client uses it
- Provide the article to interpret: say "this one" (= the article involved in the current conversation) or give a file name/title, and the Agent locates it under
<vault-articles-dir>/. - Single article: the Agent executes directly, no extra confirmation needed. Bulk (a single request involving more than 3 articles): the Agent first lists them (file names + rough topics), waits for the client to confirm the interpretation scope (all / select a few / pause), then executes one by one.
- Depth defaultQuick read(five-part format, 2-3 sentences per section); when the client says "close read," "deep interpretation," or "section-by-section verification," it upgrades toClose read(section-by-section expansion + argument-chain verification, see Two depth levels）。
- Interpretation alwayswrites to disk first, reports after: the output
<原文件名>-AI解读.mdis placed in the same directory as the original file, the body is double-linked back to the original, and the original file is never modified or overwritten (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 explicit in the original / needs verification," and remaining risks.
Dependencies and installation
Installation (recommended: install the entire domain plugin, installing all skills in this repository at once):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
When you only want this one skill, you can use the npx route. Note that the skill will be placed into the shared true source ~/.agents/skills; if the plugin is also installed, the same skill will have two indexes and each will drift, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-interpret-article-analysis -y
| Dependencies | Type | Installation / configuration | What to do when missing |
|---|---|---|---|
| Obsidian vault (any structure) | Reference method, not a hard dependency | No separate installation required | This skill can interpret any Markdown/plain-text article and does not require the file to be inside a vault; it only refers to vault context when vault frontmatter and double-link filing conventions are involved |
soia-pkm-clip-* series |
Upstream source, not a hard dependency | No installation required, unless the client needs to archive first and then interpret | It is merely a common input source; this skill does not call or modify any files of these skills |
soia-pkm-distill-article-opinion |
Downstream/parallel skill, not a dependency | No installation required | This skill does not write to ## 我的看法; when the client wants "my viewpoint", prompt them to use that instead, and do not execute it on their behalf |
Configuration conventions:
~/.config/soia-skills/soia-pkm-interpret-article-analysis/config.yml
SOIA_PKM_INTERPRET_ARTICLE_ANALYSIS_CONFIG_FILE=<custom-config-path>
- This skill is a pure document / pure prompt skill, has no scripts, and usually does not need
config.yml; if the client wants to fix preferences such as the "default depth" or the "batch confirmation threshold", they can create this file, 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.
WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it; it needs to be installed separately, see docs/install/workbuddy.md。
Logging and completion receipt
Every execution must let the client see the full process of the judgment, depth, batch confirmation, and output. The minimum receipt format:
完成：<一句话说明本次解读了什么文件、什么深度>。
日志摘要：
- 定位：<文件路径，如何找到的（客户直接给的 / 在 vault 内搜到的）>
- 深度：<快读 / 精读，以及判定依据（客户是否明确要求精读）>
- 批量确认：<单篇写"不适用"；批量则写是否先报清单、客户确认了什么范围>
- 待核对：<解读中标注"原文未明确/需核对"的条数，简述位置>
文件变化：
- 新建：<绝对路径，`<原文件名>-AI解读.md`>
- 未改动：<原文件路径，确认未被覆盖，`## 我的看法` 段未被触碰>
问题与下一步：
- <值不值得深挖的判断 / 建议客户回复"精读"升级 / 建议客户对这篇跑 soia-pkm-distill-article-opinion；没有则写"无，可直接使用产出">
The boundary with soia-pkm-distill-article-opinion (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-article-analysis (this skill) | soia-pkm-distill-article-opinion |
|---|---|---|
| Interpretation subject | AI reads through the full text and gives a judgment | Userspeaks orally, and the AI only helps ask questions and helps put the words down |
| Interaction mode | Generate the five-part interpretation in one pass, without question-by-question answers | Socratic style, throwing only one question at a time and waiting for the user to answer |
| Output content | The AI's overview / key points / insights / critique / extensions | The user's own stance, experience, and judgment |
| Placement location | Standalone file <原文件名>-AI解读.md |
within the original file ## 我的看法 section |
| When to use | Just archived and not yet finished reading, and want to first judge whether it is worth digging into | Have already decided to take a stance on this piece and to distill a viewpoint |
| Red line | Never write into the original text's ## 我的看法 section—that is exclusively for the user |
Never take a stance on behalf of the user—the content must come from the user's answers |
- If during interpretation the client says "what do I think of this piece", "help me distill the viewpoint", "my view on this piece is...", always prompt "this is the responsibility of
soia-pkm-distill-article-opinion; do you want to switch over?", and do not answer or write on their behalf within this skill. - Interpret's output isdecision support: helping the client judge "whether this piece is worth going into distill for deep digging"; it is not the viewpoint itself, and should not be mistaken for the client's viewpoint.
Two depth levels
| Depth | Trigger words | Output format |
|---|---|---|
| Quick read(default) | When intensive reading is not explicitly requested | Five-paragraph structure, 2-3 sentences per paragraph, covering the full text without expanding section by section |
| Intensive read | "intensive read", "in-depth interpretation", "section-by-section verification" | Based on the five-paragraph structure, expand section by section + argument chain verification (see below) |
Intensive read mode: argument chain verification
During intensive reading, before the "critical perspective" paragraph, first conduct a section-by-section argument chain verification, confirming each argument one by one:
- 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 specified in the original/needs verification"; do not fill them in on behalf of the original text.
Use the verification results as the basis for the "critical perspective" paragraph rather than listing them in a separate paragraph; avoid the intensive reading output becoming two disconnected parts: "overview + verification checklist".
Five-paragraph interpretation structure (output template)
Output file <原文件名>-AI解读.md The main text 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 specified in the original/needs verification"; never fabricate data, experiments, or conclusions that the original text does not contain.
- When citing the original text, provide the source paragraph (section title, "introduction"/"paragraph X", etc.) so the client can check 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 it with Glob/Grep. - Read the article's
## 原文paragraph (the clip family uses a unified main text structure:## 摘要 / 原文 / 我的看法 / 关联); when only the abstract is available and not the full text, before interpreting, first inform the client that "this time is based on the abstract rather than the full text, so the confidence of the conclusions is lower", 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: in the 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>
- Use
[[<原文件名>]]double links back to the original text in the main body for convenient bidirectional navigation. - 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, which must be confirmed first).
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 the articles (filename + one-sentence guess of the topic), 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 "write to disk first, report afterward", and after all are completed, provide a combined receipt (see Log and completion receipt）。
- 2-3 articles: treat as a small batch and execute directly, but still report in one sentence before starting which articles will be processed.
Delivery order
Write to disk first, report afterward: the output file must first be written to disk and pass content verification (the file actually exists, all five sections are present, and there is at least one critical perspective), and only then may a completion receipt be sent to the client. It is not allowed to first describe it as "completed" and then fill in the file afterward.
Boundaries and Limitations
- Does not replace
soia-pkm-distill-article-opinion: This skill never writes into the original file's## 我的看法section, nor does it impersonate the client's position in the first person. - Does not fabricate: Any information not provided in the original text is always marked "not specified in the original / needs verification"; no data, experiments, citations, or conclusions are invented.
- Does not perform external retrieval verification: The interpretation is based on the original text itself; if a critical perspective depends on external fact-checking, only remind the client that "this point needs to be verified by the client themselves," and do not arbitrarily fabricate verification results.
- Does not perform translation/conversion: Foreign-language articles should first go through
soia-pkm-translate-article-zhor be understood by the client themselves before interpretation; this skill does not coversoia-pkm-transform's responsibility for product conversion (PPT/mind maps, etc.). - 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-article-moc's organized article library is the main input source; it 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 one is worth digging into," they move to
soia-pkm-distill-article-opinionto refine their own viewpoint;soia-pkm-interpret-article-analysis's output is not a required input fordistillorcompose, but only a decision reference.
Relationship with Third-Party Skills
| Third-Party Skill | Relationship to soia-pkm-interpret-article-analysis relationship with |
|---|---|
soia-pkm-distill-article-opinion |
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 the files of these skills |
soia-pkm-organize-article-moc |
Common upstream, not a dependency; this skill does not require the article to have been organized by organize |
soia-pkm-translate-article-zh |
Translation prerequisite for foreign-language articles, not a dependency; this skill does not perform translation |
Completion Receipt
The receipt includes:
- 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 step — prompt the client with the basis for judging "whether this one is worth digging into"; in quick-read mode, remind them that they can reply "close read" to upgrade; when there are points marked "not specified in the original / needs verification," list them as well, and suggest the client verify them themselves or use
soia-pkm-distill-article-opinionto state their position.