Communitygithub.com

shimo4228/readme-writer

Claude Code 技能:撰寫並改善給人類閱讀的 README——唯一的人類、搜尋引擎與 AI 總覽規範入口。與 llms-txt-writer 相對的人類面向作品。採用決定性結構 lint 加無分數整體 LLM 審查(AKC ADR-0008 Code-LLM 分層)。

readme-writer 是什麼?

readme-writer 是一個專注於撰寫與改善人類面向 README 的 AI 技能,主要支援 Claude Code 平台。其核心任務是在保持 README 簡潔、視覺優先的同時,確保 LLM 僅憑 README 文字就能還原專案全貌,達成「人類注意力 × LLM 資訊恢復」的雙贏。該技能將 README 品質檢查拆分為兩層:結構性問題由程式(readme_lint.py)以決定性規則處理(如單一 H1、圖片替代文字、本地連結有效性),語意性評估則由 LLM 進行無分數的整體審查(如引導是否抓住人心、資訊恢復完整性)。設計上避免使用數值評分,而是輸出具體可改進的差異建議。此外,它明確區分與其他技能的邊界(如 llms-txt-writer 負責 AI 專用文件),並建議將深度資訊移至 ADR 或 docs 目錄,防止 README 膨脹成偽 llms-full.txt。圖片方面優先採用 Mermaid 圖表及文字等價敘述,確保所有裝置與文字型爬蟲都能存取。

相容平台✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

在你喜歡的 AI 中提問

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

說明文件

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 是否為虛榮semanticLLM 的整體 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 內、僅連結內 均不可接受):

  1. identity 語句(前 1-2 句,可獨立閱讀):「X 是 {為誰} 提供 {做什麼} 的 {類別}」
  2. 解決的問題 / 目標對象 / 差異化重點
  3. 正規事實:真實姓名、語言 / 技術棧 / 狀態。研究 / DOI repo 需包含 DOI 與引用方式(BibTeX / CITATION),以及支撐詞彙的 3-6 個核心概念定義
  4. 僅一個具體範例:若是程式碼,提供函式簽名 + 最小可執行片段(勿放完整實作——會導致膨脹與幻覺);若是研究,提供核心主張 + 2-3 個關鍵數值
  5. 深層文件的連結圖譜僅作為指標。勿將承載事實的重要資訊僅放在連結目標、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=

相關技能