readme-writer — 人類面向 README 技能
為人類撰寫與改善 README 的技能。llms-txt-writer 負責 AI 專用的 surface,而此技能則負責人類 surface 的唯一正規入口。
另一個重要事實:README 是 grounding 路徑(將 repo URL 貼到 AI 搜尋 / 聊天時)中,LLM 唯一能確實當作前提的 surface。因此,README 必須在「面向人類:簡短、視覺化」與「確保 LLM 僅讀 README 就能還原專案的資訊基底」之間取得平衡——這是本技能的核⼼課題。
使用時機
- 建立或改善 README.md / README.ja.md
- 整理 repo / 專案的「人類最初著陸頁面」
- 修正現有 README「過於機械、對人類不友善」或「過於簡略、LLM 無法掌握」的問題
- 希望 README 簡短、視覺優先,但又不願犧牲資訊基底
不適用的場景:
llms.txt/llms-full.txt/ FAQ 等 AI 專用文件(請交給llms-txt-writer)- 文章、隨筆、部落格等長篇散文(請交給
writing-ecosystem) - graph.jsonld 的設計(請交給
jsonld-knowledge-graph)
主軸是「人類的注意力 × LLM 的資訊」
README 最佳化的真正對立軸,並非「人類向資訊 vs LLM 向資訊」,而是人類的注意力(簡短、易懂、可掃描)× LLM 的資訊(僅憑 README 就能還原)。兩者其實能透過同一套設計手法同時達成(詳見後文),並非取捨關係,而是設計上的雙贏。
README 是唯一肯定被讀取的 surface(但並非「唯一」)
- AI 搜尋 / 引用爬蟲實際上不會讀取 llms.txt(根據多份 2026 年的日誌調查,絕大多數請求為零,且主要搜尋廠商已正式聲明不支援)。
graph.jsonld在直接擷取時會被視為純文字,無法取代 README 中的事實(對照實驗結果)。- 因此,不該假設「機械層會補足」而讓 README 的資訊變薄。
不過需要正確校正:「LLM 只 讀 README」的說法太強烈。正確的說法是:「在一般的貼 URL / 搜尋 grounding 場景中,README 是唯一能確保被當作前提的 surface」。其他路徑(搜尋索引已快取其他檔案、從 README 追蹤連結、GitHub connector / API 暴露檔案樹、預訓練知識)仍可能存在。結論是:強度最高的場景是匿名 live web grounding 與直接落地擷取。反之,路由式 coding agent(Claude Code / Cursor 等)會按需讀取 llms.txt,因此 llms.txt 仍可作為 agentic 通道的保險——但它不是 AI 搜尋的入口。
為何將「結構 lint」與「整體 review」分開
README 品質包含兩種不同的屬性。根據 Code-LLM 分層(結構由程式 100% 精確擁有,語意由 LLM 擁有)劃分擁有者。判斷依據參考 when-code-when-llm:「同樣的字節序列是否會因上下文而產生不同意義?」
| 屬性 | 範例 | 類型 | 擁有者 |
|---|---|---|---|
| 結構性 | H1 數量 / 標題層級 / 替代文字是否存在 / 本地連結是否有效 / 點陣圖檔名 / badge 數量 / details 內的 DOI 等 / H1 後的 prose 行 | structural | 程式(readme_lint.py) |
| 語意性 | 引導是否吸引人 / 價值主張是否清晰 / 僅 README 能否讓 LLM 還原專案 / 故事流暢度 / badge 是否為虛榮 | semantic | LLM 的整體 review |
不為 README 建立基於研究值的數值評分。llms.txt 的區塊比例(ski-ramp 等)是經 LLM 引用研究驗證的決定性訊號,但 README「是否是一個好的入口」屬於語意判斷,缺乏同等的決定性依據。將 AI surface 的指標(如 entity density)套用在人類 README 上屬於 anti-pattern。
但「結構性 AI 可讀性」應積極採用(雙面規則)
「不引入 AI surface 指標」只對了一半。原則是:「想法如何傳達可以最佳化(強度無上限);想法是什麼則絕不能扭曲」。
- 採用(強度無限制):標題層級、資訊設計、entity anchoring(將作者名、ORCID、DOI、正規識別碼寫在 prose 中)、專有名詞 / 自創詞彙的 anchoring、answer-first 的引導、一目了然的表格。這些對人類與 grounding 路徑的 LLM 都有幫助,屬於收斂區域。
- 禁止:關鍵字堆砌、浮濫屬性、問題標題 farming、投放 glossary、為迎合檢索獎勵函數而扭曲主張。引用或 star 並非成功指標,因此扭曲本身沒有服務對象。
最小 LLM 讀取基底(小、不退讓、不膨脹)
規則:假設 LLM 只讀了 README 這一頁(不讀 llms.txt、也不讀 graph),僅憑文字就能還原專案。
基底元素(必須用 prose / markdown / Mermaid 呈現。僅圖中、僅 details 內、僅連結內 均不可接受):
- identity 語句(前 1-2 句,可獨立閱讀):「X 是 {為誰} 提供 {做什麼} 的 {類別}」
- 解決的問題 / 目標對象 / 差異化重點
- 正規事實:真實姓名、語言 / 技術棧 / 狀態。研究 / DOI repo 需包含 DOI 與引用方式(BibTeX / CITATION),以及支撐詞彙的 3-6 個核心概念定義
- 僅一個具體範例:若是程式碼,提供函式簽名 + 最小可執行片段(勿放完整實作——會導致膨脹與幻覺);若是研究,提供核心主張 + 2-3 個關鍵數值
- 深層文件的連結圖譜僅作為指標。勿將承載事實的重要資訊僅放在連結目標、llms.txt 或 graph 中
最重要的陷阱:基底是小的非退讓核心。若過度強調「不要刪減、重新組織」,可能導致資訊被保存在 Mermaid、details、基底段落中,使 README 偽裝成 llms-full.txt 而過度膨脹。人類的目標是簡短。基底以外的內容應毫不留情地刪除或 relocate(參見長度預算)。
若需要從 README 產生 graph.jsonld / llms.txt,不該以 README prose 作為結構來源。識別碼、圖形邊應從 CITATION.cff / .zenodo.json / frontmatter 的小型 manifest 推導(手寫並行副本會產生 drift)。
GitHub 的元資料面(repo description、topics、social-preview、CITATION 檔案、release、package metadata)也屬於 grounding 的基底部分。這些不在 README 本文中設定(由 gh repo edit / release-doi 處理),但應作為 checklist 確認是否齊全。
Visual-first(Mermaid 優先、點陣圖最後)
「簡短、視覺化」的正確解讀是 「將散文牆壓縮成可掃描的結構」,而非將散文轉換成圖片。而且 「Mermaid 優先」≠「什麼都用 Mermaid」——應先判斷是否真的需要圖。選擇在行動裝置(窄寬度)上不會潰爛、且 LLM 能讀取的格式。
格式選擇
| 內容 | 最佳格式 | 理由 |
|---|---|---|
| 3 步驟的線性或簡單列舉 | prose / list / 小表格 | 所有裝置(特別是行動裝置)都可讀。不值得做成圖 |
| 真正圖形狀(關係、多分支、矩陣) | Mermaid(TD 垂直方向) | 原始碼為文字,LLM 也能讀。垂直滾動在手機上自然,橫向(LR)會潰爛 |
| 較大 / 複雜的圖 | committed SVG(可放大 / 平移)/ 子系統拆分 | 巨型 Mermaid 在桌機也可能超過上限,在行動裝置上會潰爛 |
| 實際 UI / 執行結果 / 照片 | 點陣圖(PNG/JPG/WebP/GIF) | 只有 Mermaid 無法呈現的內容才用 |
每張圖都必須附加一句文字等價敘述(硬性規則)。這是確保「同時觸及人類與 LLM」的關鍵:圖在行動裝置上潰爛的使用者、將 mermaid code block 視為不透明程式碼而跳過的 LLM 萃取器、以及螢幕閱讀器,都能因此受惠。圖只是視覺上的加分項,不該成為資訊的唯一載體。
Mermaid 要點
- GitHub 會原生繪製成 theme-aware SVG。原始碼為文字(可 diff、約 10 token / edge),無法看 pixel 的文字型爬蟲也能讀取。將藏在散文 / graph 中的結構(概念矩陣、階段綁定、管線階段)轉為 Mermaid 可變得更短、資訊密度更高。
- 行動裝置優先,使用
TD(垂直)。橫向LR在窄寬度下容易崩潰。 - 繪製上限為字元數(
maxTextSize預設 50,000)與邊數,而非節點數(「50-100 節點是極限」為謠言)。若可能超過,則進行子系統拆分。特殊專案的 README 可能不會被繪製。 - 萃取器可能忽略 Mermaid,因此必須透過上述的文字等價另外確保語意。
點陣圖 / 其他
- 點陣圖不應承載重要資訊。替代文字為必要(硬性底線:文字路徑只會讀取替代文字 = 無替代文字的圖片對 LLM 不可見。這不只是無障礙問題)。
- 深色 / 淺色模式使用 `<source media=