SuperAPI AI Directory

soia-pkm-interpret

General & other

View repository

Updated 10-16 09:31

About this skill

soia-pkm-interpret

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

  1. 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>/ .
  2. 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.
  3. 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)。
  4. Interpretation alwayswrites to disk first, reports after: the produced <原文件名>-AI解读.md is 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).
  5. 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:

  1. What is the core argument of this section?
  2. What is the evidence/data/citation supporting this argument, and from which paragraph of the original text does it come?
  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 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

  1. 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.
  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 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.
  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-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-translate 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 's organized article library is the main input source; you can also directly interpret a single article that has just been clip 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 to refine their own viewpoint;soia-pkm-interpret 's output is not a required input for distill or compose , 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):

  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; clearly state that the original file (including ## 我的看法) was not modified.
  3. 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-distill to state their stance.