Community生產力與協作github.com

README 撰寫工具

撰寫或改寫專案的 README,將訪客轉化為使用者和貢獻者——包含一句話介紹、徽章、60 秒快速入門、實際範例、功能、常見問題、貢獻指南和授權條款——並對其進行 lint 檢查,找出遺漏的章節、損毀的相對連結、目錄中不存在的標題錨點、遺漏的替代文字以及太晚出現的第一個程式碼區塊。當使用者要求撰寫、改善、審查或重組 README,表示沒人理解或沒人關注專案,或正在準備開源發佈時使用。

README 撰寫工具 是什麼?

這是一個專門用來撰寫、改寫和審查專案 README 檔案的 AI agent 技能。它的核心目標是讓訪客在 60 秒內從「這是什麼?」順利執行第一條指令,並進一步了解如何使用和貢獻。該技能支援 Claude Code、Cursor、Codex 等主流開發工具,透過結構化的流程確保 README 的品質與一致性。 它的工作流程包括:先從專案原始檔(如 pyproject.toml、package.json)收集事實,詢問使用者專案目標與受眾,對現有 README 進行 lint 檢查(包含章節完整性、連結有效性、替代文字等),並依照預定義的結構(如標題、徽章、一句話介紹、快速入門、功能、範例、常見問題、貢獻指南、授權條款)進行撰寫。lint 規則涵蓋錯誤與警告層級,例如缺少 H1 標題、沒有程式碼區塊、相對連結損毀等。 最終產出包括新的或更新的 README.md、最終 lint 結果,以及未驗證的事實與需要使用者補充的佔位符(如示範 GIF、截圖、基準測試數據)。這個技能特別適合在專案發佈前、或使用者抱怨專案缺乏關注時使用。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

README 撰寫工具 是做什麼的?

一份 README 只有一個任務:讓訪客在 60 秒內從「這是什麼?」順利執行第一條指令,然後展示如何更進一步以及如何貢獻。

使用時機

  • 為新專案撰寫 README,或改寫內容貧乏或雜亂的現有 README
  • 在專案發佈或 1.0 版本前審查 README
  • 使用者表示專案有流量但沒有星星、安裝數或貢獻者

不應使用的情況

  • API 參考文件(應從程式碼產生,並在 README 中提供連結)
  • 長篇教學或架構文件:應放在 docs/ 目錄,並在 README 中提供連結

工作流程

  1. 撰寫前先收集事實。 讀取專案清單檔(pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI --help 或主要進入點、現有文件以及授權條款。找出實際的安裝指令和一個真實範例。絕不憑空捏造旗標、輸出結果、基準測試或功能。

  2. 只詢問程式碼無法告訴你的事: 專案的目標對象、解決的單一問題,以及為何比明顯的替代方案更優秀。如果無法取得這些資訊,則根據程式碼撰寫中性的介紹,並標註為待審查。

  3. 對現有 README 進行 lint 檢查(如果有的話)。scripts/ 路徑相對於此技能:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. 根據 structure.md 中的結構進行撰寫,從範本開始。順序很重要:標題和徽章、介紹、(示範圖片)、快速入門、功能、使用方式/範例、設定、常見問題、路線圖、貢獻指南、授權條款。

  5. 套用撰寫規則:

    • 介紹:一句話,不超過 200 個字元,不使用誇大詞彙。模式:「<名稱> 是一個 <類別>,為 <目標對象> 提供 <功能>,<關鍵差異化優勢>。」
    • 第一個程式碼區塊應在 60 行以內。每個指令都必須是可複製貼上且真實可用的。
    • 在指令後顯示輸出結果(使用 # => ... 或獨立區塊)。
    • 使用表格呈現選項和比較,使用列表呈現功能(先寫優點)。
    • 提供連結,不直接貼上:長篇文件、變更日誌和 API 參考資料應放在其他地方。
    • 每張圖片都需有替代文字;建議使用 SVG 或展示主要流程的短 GIF。
  6. 徽章。 只使用真實且持續維護的徽章,順序如下:CI 狀態、最新版本(PyPI/npm/Packagist/release)、下載量(可選)、授權條款。範例請見 structure.md。

  7. 重新進行 lint 檢查,直到沒有任何錯誤。處理警告,或向使用者說明不處理的原因。

  8. 檢查 lint 工具無法檢查的連結: 絕對 URL 和錨點。實際點擊測試,或說明哪些連結未經驗證。

產出

  • 新的或更新的 README.md(對於改寫,顯示差異摘要)。
  • 最終 lint 結果。
  • 無法驗證的事實清單,以及使用者必須自行填寫的佔位符(示範 GIF、螢幕截圖、基準測試數據)。

Lint 規則

規則層級說明
titleerror/warning必須剛好有一個 H1
pitcherror/warning標題下方需有一段簡短的介紹
badgeswarning未找到徽章
installerror/warning需有安裝(或快速入門)章節,且包含程式碼區塊
quickstarterror/warning需有使用方式、快速入門或範例章節,且包含程式碼區塊
codeerror完全沒有任何程式碼區塊
scrollwarning第一個程式碼區塊出現在 --max-scroll 行之後(預設 60 行)
contributing, licensewarning缺少對應章節
faq, tocinfo建議新增
alt-textwarning圖片沒有替代文字
broken-linkerror相對連結指向不存在的檔案,或連結為空
broken-anchorerror#anchor 連結(目錄)未對應到任何標題或 HTML id/name,使用 GitHub 的 slug 規則
placeholderwarning文件中仍有 TODO、TBD 或 lorem ipsum

若有錯誤則退出並回傳 1(使用 --strict 時,警告也會導致退出)。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能