Communitygithub.com

README 生成器

通過分析實際程式碼庫並提出有針對性的澄清問題,為內部/公司程式碼儲存庫生成精心打磨、全面的 README.md 檔案。

README 生成器 是什麼?

這項技能,即 README 生成器,旨在自動化建立高品質 README 檔案的程序,特別是針對內部或公司的程式碼儲存庫。它能顯著減少新團隊成員因缺乏完整文件而浪費在理解專案上的時間。該技能首先會對程式碼庫執行一個結構化的四階段分析,包括掃描專案中繼資料、架構、深度模組以及支援基礎設施,從而無需使用者手動描述即可提取大量上下文資訊。隨後,它會僅就無法從程式碼中推斷出的細節(例如專案目的、設定陷阱或部署方式)向使用者提出簡潔的澄清問題。最後,它會根據包含架構圖(如 Mermaid)、使用表格說明的環境變數、疑難排解章節以及聯絡資訊等部分的詳盡模板,生成完整的 README.md 檔案。此技能旨在與各種開發工具(如 Claude Code、Cursor、Codex 等)無縫整合,產出結構清晰、內容具體且可直接使用的文件,優先使用實際的命令、路徑和變數名稱,並要求包含數個 Mermaid 圖表以增強可理解性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/cdcoonce/Portfolio_Website/tree/HEAD/.claude/skills/readme-generator

在你喜歡的 AI 中提問

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

預覽

來自技能 README

語言

說明文件

README 生成器 是做什麼的?

通過分析實際程式碼庫並提出有針對性的澄清問題,為內部/公司的程式碼儲存庫創建精心打磨、全面的 README.md 檔案。

為何有此技能

一份良好的 README 是程式碼庫的門面。對於內部專案尤其如此,缺失或內容單薄的 README 意味著每個新團隊成員都要花費數小時來弄清楚專案的用途、如何運行以及從何處入手。此技能自動化處理了這項繁重的工作——它會讀取程式碼,推斷出它能理解的資訊,針對無法確定的內容進行提問,然後產出能讓開發者快速上手的 README。

工作流程

步驟 1:分析程式碼庫

在向使用者提問之前,先執行一個結構化的四階段分析,以盡可能多地收集上下文資訊。這能減輕使用者的負擔——他們只需要填補空白,而不是描述你已經能看到的內容。

為每個事實標記置信度級別:[confirmed](從原始碼中讀取)、[inferred-high](強證據)、[inferred-low](部分證據)或 [unknown]。低置信度和未知的發現將成為步驟 2 中的澄清問題。

請參閱 references/analysis-phases.md 以了解詳細的工具操作、grep 模式、提取檢查清單和記錄範本。

階段 1 — 專案中繼資料掃描: 使用 glob 查找套件管理器檔案(pyproject.toml、package.json 等)、環境變數範本、Dockerfile、CI/CD 配置以及工具鏈檔案。讀取每個檔案並提取:專案名稱/版本、語言、依賴項(按用途分類)、腳本/命令、環境變數(必需的與可選的)、CI 階段、授權條款。

階段 2 — 架構掃描: 使用 glob 查找所有原始碼檔案以繪製目錄結構。使用 grep 查找入口點標記(if __name__、main() 等)並讀取每個入口點。通過在所有原始碼檔案中使用 grep 查找導入語句來構建導入圖——將模組分類為核心(高入度)、葉節點或協調器。使用指標檢查清單識別架構模式(pipeline、MVC、layered、microservices、event-driven、CLI、monolith)。使用 grep 查找配置加載模式以找到運行時配置檔案。

階段 3 — 深度模組分析: 讀取每個重要的原始碼檔案(優先級:核心 → 入口點 → 最大 → 其餘)。對於每個檔案,提取:目的(一句話)、帶有簽名的主要匯出、設計說明(不明顯的決策、邊緣情況、慣例)以及內部依賴項。通過導入圖追踪主要工作流程的端到端流程,標記在模組之間流動的數據類型。對於包含 8 個或更多原始碼檔案的程式碼庫,按依賴叢集分派平行子代理。

階段 4 — 支援基礎設施掃描: 使用 glob 查找測試檔案和測試固定資料。讀取每個測試檔案的前 30-50 行,以建立測試到模組的映射。使用 grep 查找自訂異常類別和 raise 語句,以建立錯誤層級結構。掃描範本、資源檔案和現有文件。為疑難排解表格提取常見錯誤場景。

步驟 2:提出澄清問題

分析完成後,針對你無法自信推斷出的資訊向使用者提問。保持問題的針對性——不要問你已經知道的事情。常見的空白包括:

  • 專案目的:解決什麼問題?誰在使用它?(如果從程式碼中無法明顯看出)
  • 設定陷阱:是否存在不明顯的先決條件、VPN 需求、內部套件註冊表或資料庫設定步驟?
  • 關鍵工作流程:開發者對此專案最常做的 2-3 件事是什麼?
  • 部署:是如何/在哪裡部署的?(如果從 CI/CD 配置中不清楚)
  • 團隊慣例:是否有任何命名慣例、分支策略或需要說明的模式?
  • 聯絡資訊:誰擁有/維護此專案?(聯絡人部分的姓名 + 電子郵件)

簡潔地呈現你的問題。如果程式碼庫很直接且你對分析有信心,你可能只需要 1-2 個問題——甚或不需要。請自行判斷。

步驟 3:生成 README.md

使用下面的結構和指南來撰寫 README。

README 結構

以此作為你的範本。包含所有部分,但根據項目的複雜度調整深度。在每個主要部分之間使用 --- 水平線,以營造視覺上的呼吸空間。

# 專案名稱

![語言](https://img.shields.io/badge/...) ![框架](https://img.shields.io/badge/...) ![工具](https://img.shields.io/badge/...)

簡短、清晰的描述。使用 **粗體** 強調關鍵技術或產品類型。

---

## 目錄

生成一個詳盡的、嵌套的目錄,其中包含所有 ## 和 ### 標題。將子部分在其父部分下縮排,以便讀者能一目了然地看到完整結構。這對於較長的 README 尤其重要——目錄既是導航工具,也是整份文件的概要。

預期深度的示例:

- [概述](#overview)
- [架構](#architecture)
  - [高層次架構](#high-level-architecture)
  - [資料夾結構](#folder-structure)
  - [模組依賴圖](#module-dependency-graph)
- [入門指南](#getting-started)
  - [先決條件](#prerequisites)
  - [安裝](#installation)
  - [執行測試](#running-tests)
- [環境變數](#environment-variables)
- [使用方式](#usage)
  - [示例:主要使用案例](#example-primary-use-case)
  - [示例:次要使用案例](#example-secondary-use-case)
- [API 參考](#api-reference)
  - [資源 A](#resource-a)
  - [資源 B](#resource-b)
- [疑難排解](#troubleshooting)
- [聯絡資訊](#contact)
- [授權條款](#license)

文件中的每個 ### 標題都應作為在其父 ## 標題下的縮排條目出現。不要跳過子部分——詳盡目錄的重點在於讀者可以直接跳轉到文件的任何部分。

---

## 概述

擴展描述。使用**粗體**標記關鍵術語。對多步驟流程使用編號列表。

---

## 架構

### 高層次架構

```mermaid
graph TD
    ...
```

資料夾結構

project-root/
├── src/           # 簡短註解
├── tests/         # 簡短註解
└── ...

[數據流 / 管道 / 模組依賴 — 額外圖表]

...

入門指南

先決條件

安裝

執行測試


環境變數

變數必需描述
DB_URL是PostgreSQL 連線字串

使用方式

針對 2-3 個最常見操作的實際程式碼範例。


API 參考


疑難排解

症狀可能原因修復方式
錯誤訊息問題何在如何修復

聯絡資訊

如有疑問或支援需求,請聯絡:


授權條款

僅限內部使用 – 公司名稱 專有軟體。© [年份] [公司]。版權所有。


## Shields.io 徽章

總是在 `# 標題` 標題之後直接包含 shields.io 徽章(3-6 個徽章,涵蓋語言、框架、關鍵函式庫、套件管理器、資料庫、基礎設施)。請參閱 [references/badge-reference.md](references/badge-reference.md) 以了解各類別的格式、示例和顏色建議。

## Mermaid 圖表指南

大方地使用 mermaid 圖表——它們能讓架構、數據流和流程立即變得易於理解。一個典型的 README 應該有 **3-6 個圖表**;複雜的專案(數據管線、多服務系統)可能會有 **6-10 個以上**。請參閱 [references/mermaid-guidelines.md](references/mermaid-guidelines.md) 以了解何時使用每種圖表類型、最佳實踐以及專案類型特定的建議。

## 寫作指南

- **具體優於籠統。**「執行 `npm run dev`」勝過「啟動開發伺服器。」請包含實際的命令、檔案路徑和變數名稱。
- **為新團隊成員而寫。** 假設他們具備一般工程技能,但對專案上下文一無所知。
- **在首次提及和概述中,使用粗體標記關鍵術語和產品名稱。** 這有助於讀者掃讀。
- **對順序流程使用編號列表。**「1. **提取**來自 X 的數據。2. **轉換**它。3. **載入**到 Y。」——對動詞使用粗體。
- **程式碼範例應可執行。** 儘可能從實際程式碼庫中複製。
- **環境變數表格是必不可少的。** 列出每一個。
- **表格格式的疑難排解**(症狀 | 可能原因 | 修復方式)——易於掃讀且一致。
- **資料夾結構註解應簡潔。** 每個目錄一個短語。
- **務必包含聯絡資訊部分。** 詢問使用者誰維護此專案。格式:`**姓名** — [email protected]`。
- **在所有主要部分之間使用 `---` 水平線**,以營造視覺結構。

## 輸出

將 README 儲存為儲存庫根目錄下的 `README.md`(如果無法識別儲存庫根目錄,則儲存為當前工作目錄下的 `README.md`)。如果 `README.md` 已存在,請在使用者確認後再進行覆寫——他們可能希望保留部分內容。

Individual skills in this repo

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

cdcoonce/Portfolio_Website

Git commit workflow with enforced conventional commit style. Use when Claude needs to stage and commit changes, craft commit messages, or the user asks to commit, make a commit, or save their work. Ensures consistent commit message format, proper scoping, and atomic commits across the project.

cdcoonce/Portfolio_Website

AI-powered code quality analysis for Python, Markdown, and Mermaid diagrams. Use this skill when: (1) reviewing code for quality issues, (2) checking Python files for PEP8 violations, unused code, missing type hints, docstring problems, complexity issues, or potential runtime errors, (3) validating Markdown documentation for broken links, heading structure, or formatting issues, (4) validating Mermaid diagram syntax, (5) the user asks for a "code review" or "quality check", (6) analyzing code snippets pasted in conversation, or (7) suggesting and applying fixes for code quality issues.

cdcoonce/Portfolio_Website

Deploy the portfolio chat agent Lambda function to AWS. Use when the user asks to deploy, redeploy, push to Lambda, update the chat agent, or after updating context files or lambda_function.py. Rebuilds the knowledge base, packages dependencies, and deploys to AWS Lambda.

cdcoonce/Portfolio_Website

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

cdcoonce/Portfolio_Website

Orchestrate the full GitHub-issues-driven development lifecycle. 7-phase pipeline from brainstorm through PR with state tracking and cross-conversation resume. Use when user says "dev cycle", "development workflow", "full development pipeline", or invokes /dev-cycle.

cdcoonce/Portfolio_Website

Production Python coding standards with automatic version detection (3.10-3.13). Use when writing, reviewing, or refactoring Python to ensure adherence to modern type syntax, LBYL exception handling, pathlib operations, ABC-based interfaces, and production-tested patterns. Not Dagster-specific - applies to any Python project.

cdcoonce/Portfolio_Website

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

cdcoonce/Portfolio_Website

GitHub CLI (gh) integration for managing issues, pull requests, branches,

cdcoonce/Portfolio_Website

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

cdcoonce/Portfolio_Website

Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.

cdcoonce/Portfolio_Website

CEO/founder-mode plan review. Rethink the problem, find the 10-star product, challenge premises, expand scope when it creates a better product. Three modes: SCOPE EXPANSION (dream big), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). Use when the user asks for a plan review, CEO review, mega review, or wants a plan challenged/stress-tested before implementation.

cdcoonce/Portfolio_Website

Break a PRD into independently-grabbable GitHub issues using tracer-bullet vertical slices. Use when user wants to convert a PRD to issues, create implementation tickets, or break down a PRD into work items.

cdcoonce/Portfolio_Website

Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in docs/plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".

cdcoonce/Portfolio_Website

Generate or update the `.claude/docs/project.md` file that gives Claude project-specific context. Use this skill when the user asks to create, update, regenerate, or refresh project context, or says things like "update project.md", "generate project context", "this repo needs a project.md", or "Claude doesn't know about this project". Also trigger when onboarding Claude to a new repository for the first time.

cdcoonce/Portfolio_Website

Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.

cdcoonce/Portfolio_Website

Set up pre-commit hooks for the current repo. Use when user wants to add pre-commit hooks, configure commit-time linting, formatting, type checking, or testing. Triggers on "pre-commit", "git hooks", "linting hooks", or /setup-pre-commit.

cdcoonce/Portfolio_Website

Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.

cdcoonce/Portfolio_Website

Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem.

cdcoonce/Portfolio_Website

Rewrites the prose sections of wiki pages in-place. Reads source files to understand current context, then updates only the content inside <!-- claude:prose --> ... <!-- claude:prose:end --> markers. Never touches <!-- generated:start --> ... <!-- generated:end --> blocks. Supports targeting a single page with /update-wiki {PageName}.

cdcoonce/Portfolio_Website

Create a PRD through user interview, codebase exploration, and module design, then submit as a GitHub issue. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.

相關技能