SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-pkm-interpret-article-analysis

soia-pkm-interpret-article-analysis

Office & productivity

View repository

Updated 10-16 09:23

About this skill

soia-pkm-interpret-article-analysis

Belongs to the SOIA personal knowledge management domain (soia-pkm-*) "interpretation" stage: for long articles/papers clipped into the vault, AI directly provides a structured interpretation, helping you judge whether this piece is worth investing in before digging deep (distill).

Customer-readable explanation

What this skill can do

For long articles/papers clipped into the vault, AI directly provides an interpretation: a five-part structure of content overview / key 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 separate <原文件名>-AI解读.md, placed in the same directory as the original file and double-linked back to the original text, never touching the original, never writing into the original's ## 我的看法 section.

Customer wants Skill will do Customer can see
Quickly judge whether a long article/paper is worth reading closely Quick read: five-part AI interpretation with 2-3 sentences per section <原文件名>-AI解读.md, double-linked back to the original text
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 a list (filenames + topics), wait for confirmation of scope List to be interpreted → interpretation file per article + summary receipt
Wants to refine this into their own views, rather than see what AI thinks Indicates this is not this skill's responsibility, points to soia-pkm-distill-article-opinion Boundary explanation, will not be mistaken for your views

How customers use it

  1. Provide the article to be interpreted: say "this one" (= the article involved in the current conversation) or give a filename/title, and the Agent locates it under <vault-articles-dir>/ .
  2. Single article: the Agent executes directly, no extra confirmation needed. Batch (when the same request involves more than 3 articles): the Agent first lists them (filenames + approximate topics), waits for the customer to confirm the interpretation scope (all / pick a few / pause), then executes one by one.
  3. Depth defaultQuick read(five-part structure, 2-3 sentences per section); when the customer says "close read" "deep interpretation" "section-by-section verification", upgrade toClose read(section-by-section expansion + argument chain verification, see Two depth levels）。
  4. Interpretation alwaysSave to disk first, report after: output <原文件名>-AI解读.md is placed in the same directory as the original file, the body double-links back to the original text, never modifying or overwriting the original file (including the ## 我的看法 section).
  5. The final reply must give the customer a complete receipt: depth, number of articles, output file paths, how many places were marked "not clear in the original / needs verification", remaining risks.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-interpret-article-analysis -y
Dependency Type Install / configure What to do if missing
Obsidian vault (any structure) Method reference, 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; only when vault frontmatter and the double-link filing convention are involved should the vault context be referenced
soia-pkm-clip-* series Upstream source, not a hard dependency Installation is not required unless the client needs to archive first and then interpret These are merely common input sources; this skill does not call or modify any files of these skills
soia-pkm-distill-article-opinion Downstream/parallel skill, not a dependency Installation not required This skill does not write ## 我的看法; when the client wants "my opinion", prompt them to switch to that instead, and do not execute it on their behalf

Configuration convention:

~/.config/soia-skills/soia-open-skills/soia-pkm/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, carries no scripts, and usually does not require config.yml; if the client wants to fix preferences such as "default depth" or "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 keys, cookies, sessions, or account credentials—this skill only reads text files provided by the client.

Logging and completion receipt

Every execution must let the client see the entire process of the decision, depth, batch confirmation, and output. Minimum receipt format:

完成：<一句话说明本次解读了什么文件、什么深度>。

日志摘要：
- 定位：<文件路径，如何找到的（客户直接给的 / 在 vault 内搜到的）>
- 深度：<快读 / 精读，以及判定依据（客户是否明确要求精读）>
- 批量确认：<单篇写"不适用"；批量则写是否先报清单、客户确认了什么范围>
- 待核对：<解读中标注"原文未明确/需核对"的条数，简述位置>

文件变化：
- 新建：<绝对路径，`<原文件名>-AI解读.md`>
- 未改动：<原文件路径，确认未被覆盖，`## 我的看法` 段未被触碰>

问题与下一步：
- <值不值得深挖的判断 / 建议客户回复"精读"升级 / 建议客户对这篇跑 soia-pkm-distill-article-opinion；没有则写"无，可直接使用产出">

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 Read through the full text and give a judgment UserSpeaks orally; AI only helps ask questions and helps put the words down
Interaction mode Generate a five-part interpretation in one go, not question by question and answer by answer Socratic, throwing only one question at a time and waiting for the user to answer
Output content AI's overview / key points / insights / critique / extensions The user's own position, experience, and judgment
Placement location Standalone file <原文件名>-AI解读.md Within the original file, the ## 我的看法 section
When to use Just archived it and have not finished reading it yet, and want to first judge whether it is worth digging into deeply Have already decided to take a stance on this piece and to refine an opinion
Red line Never write into the original text's ## 我的看法 section—that is exclusively for 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 see 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.
  • The output of interpret isdecision support: it helps 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 close reading is not explicitly requested Five-paragraph format, 2-3 sentences per paragraph, covering the full text without expanding section by section
Close reading "Close reading", "in-depth interpretation", "section-by-section verification" On the basis of the five-paragraph format, expand section by section + verify the argument chain (see below)

Close reading mode: argument chain verification

During close reading, before the "critical perspective" paragraph, first perform a section-by-section argument chain verification, confirming each argument one by one:

  1. What is the core argument of this section?
  2. What is the evidence/data/citation supporting this argument, and which paragraph of the original text does it come from?
  3. 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?
  4. For premises/definitions/boundary conditions that the original text does not clarify, mark "not specified in the original text/needs verification"; do not fill them in on the original text's behalf.

The verification results serve as the basis for the "critical perspective" paragraph, rather than being listed in a separate paragraph; avoid the close reading output becoming two disconnected parts: "overview + verification checklist".

Five-paragraph 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，用双链标出}

- ……
  • Always explicitly mark uncertain content as "not specified in the original text/needs verification"; never fabricate data, experiments, or conclusions that the original text does not contain.
  • When quoting the original text, give the source paragraph (section title, "introduction"/"paragraph X", etc.) so the client can check against the original text.

Locate the article

  1. When the client says "this one" = the article involved in the current conversation; otherwise use the filename/title under <vault-articles-dir>/ to locate it with Glob/Grep.
  2. 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 tell the client "this time it 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.
  3. 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 links 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, 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 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 "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 which articles will be processed before starting.

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, the five-paragraph format is complete, and there is at least one critical perspective), and only then send the completion receipt to the client. It is not allowed to first describe it as "completed" and then write 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 by speaking in the first person.
  • Does not fabricate: Any information not provided in the original text is always marked "not specified in the original text / needs verification"; it does not invent data, experiments, citations, or conclusions.
  • Does not perform external retrieval for verification: The interpretation is based on the original text itself; if a critical perspective depends on external fact-checking, it only reminds the client that "this point needs to be verified by the client themselves" and does not fabricate verification results on its own.
  • Does not perform translation/conversion: Foreign-language articles should first be understood via soia-pkm-translate-article-zh or by the client themselves before interpretation; this skill does not cover soia-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-article-moc The article library organized by clip is the main input source; it is also possible to interpret a single article that was just clipped in 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-distill-article-opinion to refine their own viewpoint;soia-pkm-interpret-article-analysis 's output is not a required input for distill or compose , it is only a decision reference.

Relationship with third-party skills

Third-party skill Relationship to soia-pkm-interpret-article-analysis Relationship to
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 these skills' files
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 A translation prerequisite for foreign-language articles, not a dependency; this skill does not perform translation

Receipt after completion

After execution,mustoutput to the user (do not finish silently):

  1. What was done — a one-sentence summary of which file was interpreted this time, at what depth, and whether it was batch processing.
  2. File changes — the full path of the newly created interpretation file; explicitly state that the original file (including ## 我的看法) was not modified.
  3. Next steps — prompt the client with 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 text / needs verification", list them as well, and suggest the client verify them themselves or use soia-pkm-distill-article-opinion to express their stance.