Community寫作與編輯github.com

解釋

以用戶自己的語言,用因果鏈的方式進行解釋——先點出問題,每個說法都附帶原因,以口語化的技術散文形式呈現。適用於用戶詢問某個事物如何運作或為何失敗、詢問問題是什麼、表示之前的解釋沒聽懂,或需要理解某個系統或變更的架構時。

解釋 是什麼?

這項技能「解釋」旨在幫助開發者或 AI 代理用戶,透過建立清晰的因果鏈,以自己的詞彙來理解複雜的技術問題、系統架構或除錯場景。它優先使用用戶已知的術語,並將每個說法與其根本原因連結起來,以形成一個連貫且易於理解的敘述。該技能會掃描用戶先前的對話,以收集其專用術語和既有知識,然後建立一個從問題本身開始的解釋,確保每個因果鏈最終都追溯到用戶已理解的基礎事實。此技能支援任何文字介面,如 Claude Code、Coder 或 Codex,並以口語化的散文格式輸出,易於朗讀或文字轉語音。最後,它會明確指出用戶用詞或假設中的任何錯誤,並根據程式碼或系統事實進行糾正,有助於讓用戶的理解與實際技術細節保持一致。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/explain-skill/tree/main/skills/explain

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

此處的解釋是一條因果鏈,使用用戶的語言:由數個簡短句子組成,每個說法都帶有其理由,並使用用戶已熟悉的術語建構,可一口氣讀完,必要時可朗讀出來。

1. 收集用戶的用詞

解釋需依附於用戶已知的知識,而用戶的知識會反映在他輸入的詞彙中。在首次於對話中解釋某個主題前,請先閱讀用戶先前是如何討論它的:

python3 <此技能所屬資料夾>/user_words.py <關鍵詞> [<關鍵詞> ...]
python3 <此技能所屬資料夾>/user_words.py --all-projects <關鍵詞> ...

這會輸出用戶在先前的 Claude 對話中,包含該關鍵詞的訊息,按時間從新到舊排列,範圍可限定於當前專案或所有專案。從用戶的問題和主題中挑選關鍵詞(如元件名稱、工具、出問題的事物)。並將當前對話中用戶的訊息也納入考量。

從這些內容中,請注意三件事:

  • 他的術語:他對每個事物所使用的詞彙(例如「zweiter SSH-Weg」、「incoming IP」、「proxied」)。即使程式碼或文件使用不同的名稱,也請準確使用他的詞彙。
  • 已知基礎:他已經陳述或正確使用過的知識。因果鏈可以在這裡結束。
  • 缺口:與主題相關但他從未使用過的術語。每個都是一個新詞。

當解釋所需的每個術語都被歸類為「他的術語」或「新詞」時,此步驟即完成。

2. 撰寫因果鏈

  1. 先點出問題。 第一個句子點出問題或答案本身:「問題是 X。」當用戶提出直接問題(例如「這個密碼做什麼用?」)時,第一個句子應直接回答該問題。
  2. 每個說法都附帶原因。 在同一個句子中使用「因為」、「由於」、「透過」等詞來連接原因。單獨陳述一個效果等於一個未閉合的鏈結:「所有連線都來自 127.0.0.1」這句話本身什麼也沒解釋,直到「fail2ban 是根據 IP 進行封鎖」這句話與之相伴。
  3. 鏈結至已知基礎。 持續追問「因為」的原因,直到最後一個原因是用戶已知的基礎知識。就在那裡停止。
  4. 使用他的術語,描述實際機制。 使用他的詞彙,直接且字面地陳述實際機制。不要使用類比、比喻或虛構的角色。
  5. 新詞用括號標註。 一個新詞第一次出現時,應在其後以方括號附上關鍵詞,之後再裸詞使用:「HostKeyAlias (SSH 選項:用於根據 known_hosts 中的另一個條目檢查主機金鑰)」。關鍵詞,而非一個完整的句子。
  6. 口語化的散文。 三到五個簡短的陳述句,每個句子包含一個鏈結,按原因到效果的順序排列。使用樸實無華的連續文字,以便可以透過語音朗讀:解釋內部不要使用標題、表格或項目符號列表。

對於架構解釋,因果鏈應沿著一個請求或一個變更的路徑進行:哪個部分執行什麼動作,它傳遞了什麼給下一個部分,以及為什麼下一個部分能夠或不能夠以其接收到的資料來完成它的工作。

3. 指出錯誤之處

用戶的措辭和假設需根據程式碼和事實進行檢查,並指出每個偏差之處——在因果鏈之後,用一行一行的形式列出「你說… / 實際上是…,因為…」:

  • 程式碼中不存在的措辭:他說「Passkey」,實際上是鑰匙圈條目;他說「Runner 故障」,實際上是 runner 容器,而 Docker 出錯。請給出程式碼或工具使用的名稱,以便用戶的下一個問題和搜尋能命中正確結果。
  • 錯誤的假設:他認為理所當然但實際上不成立的事(例如「我需要這個密碼才能連線」)。請說明實際情況及其原因。

在指出錯誤之前,務必根據程式碼或系統進行驗證;憑記憶修正只是猜測。之後,僅在他的措辭正確的情況下才繼續使用他的詞彙。

範例

一個用戶自己應該得到的解釋的措辭(說明為什麼在 Cloudflare 隧道後,fail2ban 無法保護 SSH)。這裡的例子是德文;請使用用戶書寫時使用的語言進行解釋。

問題在於第二種 SSH 認證方式使用密碼。使用 Mac 的用戶名和用戶密碼,任何人都可以透過暴力破解建立連線。fail2ban 無法保護,因為它是基於 IP 的封鎖機制,而且透過隧道,所有連線都擁有相同的 incoming IP,這是因為 Cloudflare 使用了代理功能。

完成檢查

在發送之前,請檢查每個句子:

  • 第一個句子點出問題或回答了所提出的問題;
  • 每個說法都在同一個句子中附帶其「因為」;
  • 最後一個「因為」是此用戶的已知基礎;
  • 每個術語都是他的術語,或是一個帶有括號的新詞;
  • 用戶問題中每個錯誤的措辭和錯誤的假設都已連同其修正一起指出。

當用戶仍然不理解時,請找出缺少「因為」的那個鏈結,並僅用一個句子補充該鏈結。只有在這裡,才需要引入具體數值(例如兩個 IP、一個請求)來閉合那個鏈結。

接下來要做的事(選項、指令、建議)應在解釋之後提供,並與解釋分開,且僅在用戶詢問或有行動必要時才給出。

相關技能