Community影像github.com

Yeshwanthyk/teach

教導一個子系統、變更或概念,讓對方真正理解:先執行 how 來了解機制與歷史原因,再分層解釋,並用逐步建構的圖表來說明。

teach 是什麼?

這個技能幫助 AI 代理以循序漸進的方式,向開發者解釋一個子系統、程式碼變更或抽象概念,重點在於達成真正的理解而非只是提供資訊。它會先利用「how」技能分別從「機制」(透過 Analysis/Trace/Map 等視角) 和「原因」(透過 History 視角) 兩個面向蒐集資訊,然後根據對方的已知程度與提問目的,決定要聚焦的兩三個核心知識點。接著,它會像資深工程師那樣,從最簡單的定義開始,一層一層地建構解釋,並在需要時動態產生逐步增加的圖表(例如透過 show-me 或 viz 技能)。該技能明確要求使用 plain spoken English、避免修辭或預告,並在完成時確保每個主張都能追溯到 how 的發現或程式碼閱讀,且保留 History 的信心標籤。它適用於 Cursor、Claude Code 等支援技能呼叫的 AI 代理平台,是一套專為程式碼教學與設計決策溝通而設計的對話框架。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yeshwanthyk/agent-skills/tree/HEAD/skills/teach

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

teach 是做什麼的?

解釋某個東西是什麼、如何運作、以及為何如此設計,並依照對方的節奏進行。目標是理解。不要修改任何程式碼。

決定核心學習點

選出兩到三個對方離開時應該理解的重點。從對話中判斷:他們為什麼問這個問題(即將修改它、正在審查它、除錯中、還是初次接觸)以及他們已經知道什麼。跳過他們顯而易見已知的部分,並將深度放在他們的問題所在之處。

透過 how 蒐集資訊

先閱讀足夠的程式碼以掌握方向,然後讓 how 來進行深入挖掘,而不是重新做一次:

  • 機制: how 的 Investigate 功能,使用問題所需的視角(單一流程用 Trace,子系統用 Map)。
  • 原因: how 的 History 視角。預設保持狹窄範圍:將問題限縮在他們面對的決策上,從 git 和一兩個來源開始,並記錄你跳過了什麼。只有在原因本身是重點時才擴大範圍。

一個子系統通常需要兩者;一個小變更可能只需要其中一個。當兩者範圍都很廣時,在背景工作程序中依據委派合約執行 History,同時你進行機制的追蹤。可以自由地重新措辭 how 的發現以便教學,但 History 的信心標籤除外:那些保留的表述本身就是發現,請保留它們。

分層解釋

先給出一個白話的定義,就像資深工程師會脫口而出的那樣,如果該東西有常見名稱也一併提出。然後將其與當前案例連結(「在這裡,我們用它來……」),並逐步建構:如何運作、原因、邊界情況。對於每個部分,說明它解決的問題以及具體的機制。一步步走過對方在操作時(發送請求、向上滾動、重試)會發生什麼事,通常是最有效的教學方式。一個函式和常數的清單只是參考資料,不是教學。

先給出最簡潔完整的答案,一兩句話,然後停下來讓對方引導方向。當對方要求時再加入下一層。保持對話感:當你該停頓的時候,就停下來讓對方回覆。如果是沒有真人互動的情境(一次性輸出),則乾淨地呈現各層次,並在最後提供繼續深究的邀請。

逐步建構展示

當程式碼、差異對比或實際執行範例比文字更能讓人理解時,就打開它們。對於任何有三個以上動態部件的東西,畫一個短的系列圖,其中每張圖都以前一張為基礎並新增一個部分,讓對方看著系統如何組裝起來。要教 A → B → C:先畫 A → B,然後重畫並加入 C,最後再重畫並加入回傳邊。一次畫好的完整圖只是參考卡片,最多留到最後使用。

核心概念使用工具
單一點、一個定義、一個簡短原因純文字段落
流程、呼叫路徑、結構或前後對比show-me,並使用其選擇形式為主機環境挑選的格式
應該點擊查看的狀態、隨著時間展開的過程(如一個請求經過多個元件、通訊協定交換),或是時間與量的關係(如競爭情況、延遲發生處、流量分流)viz:view: states、view: seq,或其「選擇視角」列表中列出的視角

在建立較重的產出物(如已儲存的視覺化頁面)前先提供選項,除非對方要求;同時在背景建置時繼續以對話進行教學。將第一步的核心點放入該產出物中,讓它教導那些重點,而不是 how 找到的所有東西。

語調

透過 unslop 來寫作:使用平實的口語英文,緊湊但不簡略,聚焦於具體機制而非隱喻或預告。以下是目標密度:「虛擬化分為兩部分執行,一部分負責渲染,一部分負責從磁碟載入。當一個項目滾出緩衝區外時,其 DOM 節點和記憶體中的資料都會被回收。」每個概念使用一個名稱,並從頭到尾保持一致。偏好使用短句。平實地說出每個部分,不要標記它為關鍵、棘手或需要記住的重點,也不要考對方或要求對方複述。這些章節標題是指示你的指令,請將它們保留在回覆之外。

完成條件

當對方的問題在他們要求的層次中得到回答、每個主張都能追溯到 how 的發現或你閱讀的程式碼、History 的宣稱保留其信心標籤、任何產出物已開啟或連結且基於相同的證據建構、以及值得進一步追查的方向已被指出時,即視為完成。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能