Communitygithub.com

cdcoonce/Portfolio_Website

为代码仓库生成全面、高质量的 README.md 文件。当用户要求创建、编写、生成、更新或改进任何项目或仓库的 README 时,请使用此技能。

Portfolio_Website 是什么?

该技能旨在自动化生成内部/企业代码仓库的专业 README.md 文件。其核心价值在于,通过深入分析实际代码库并仅就少数关键信息向用户提问,大幅降低新团队成员上手项目的时间。它支持任何本地或可通过文件系统访问的代码仓库,能够自动识别项目元数据、架构模式、关键模块和测试覆盖情况。工作流程分为三步:首先执行四个阶段的结构化代码分析(项目元数据、架构、深层模块、支持基础设施),标记每项发现的置信度;然后,仅针对无法从代码中推断的低置信度区域发起精简的澄清提问;最后,根据预设模板生成包含清晰结构、Mermaid 图表、徽章和详尽故障排查表的 README.md 文件。该技能无需特定平台或 API,直接操作本地文件,因此适用于 Claude Code、Codex 等能访问用户工作目录的 AI 代理。

兼容平台~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 步中的澄清问题。

有关详细的工具操作、grep 模式、提取清单和记录模板,请参见 references/analysis-phases.md。

阶段 1 — 项目元数据扫描: 全局搜索包管理器文件(pyproject.toml、package.json 等)、环境模板、Dockerfile、CI/CD 配置和工具链文件。读取每个文件并提取:项目名称/版本、语言、依赖项(分类并注明用途)、脚本/命令、环境变量(必需与可选)、CI 阶段、许可证。

阶段 2 — 架构扫描: 全局搜索所有源文件以映射目录结构。使用 grep 搜索入口点标记(if __name__、main() 等)并读取每个入口点。通过在所有源文件中使用 grep 搜索 import 语句来构建导入图——将模块分类为核心(高入度)、叶节点或编排器。使用指标清单识别架构模式(管道、MVC、分层、微服务、事件驱动、CLI、单体)。使用 grep 搜索配置加载模式以查找运行时配置文件。

阶段 3 — 深度模块分析: 读取每个重要的源文件(优先级:核心 → 入口点 → 最大 → 其余)。对每个文件,提取:用途(一句话)、关键导出及其签名、设计说明(非显而易见的决策、边界情况、约定)以及内部依赖项。通过导入图端到端追踪主要工作流,标记模块之间流动的数据类型。对于包含 8 个以上源文件的代码库,按依赖集群分发并行子代理。

阶段 4 — 支持基础设施扫描: 全局搜索测试文件和 fixture。读取每个测试文件的前 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 尤其重要——TOC 既是导航工具也是整个文档的大纲。

预期的深度示例:

- [概述](#概述)
- [架构](#架构)
  - [高层架构](#高层架构)
  - [目录结构](#目录结构)
  - [模块依赖图](#模块依赖图)
- [入门指南](#入门指南)
  - [先决条件](#先决条件)
  - [安装](#安装)
  - [运行测试](#运行测试)
- [环境变量](#环境变量)
- [使用方法](#使用方法)
  - [示例:主要用例](#示例主要用例)
  - [示例:次要用例](#示例次要用例)
- [API 参考](#api-参考)
  - [资源 A](#资源-a)
  - [资源 B](#资源-b)
- [故障排查](#故障排查)
- [联系方式](#联系方式)
- [许可证](#许可证)

文档中的每个 ### 标题都应在父 ## 标题下作为缩进条目出现。不要跳过子部分——详尽 TOC 的要点在于读者可以直接跳转到文档的任何部分。

---

## 概述

扩展描述。使用粗体标记关键术语。对于多步骤流程使用编号列表。

---

## 架构

### 高层架构

```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,请在覆盖前与用户确认——他们可能希望保留部分内容。

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.

相关技能