project-setup-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Setup Guide Skill

项目设置指南Skill

Generate professional, comprehensive README.md files for any project type requiring setup documentation.

为任何需要设置文档的项目类型生成专业、全面的README.md文件。

Supported Project Types

支持的项目类型

Type	Examples	Key Sections
Dotfiles	Shell configs, vim, tmux, git	Tool configs, aliases, keybindings
CLI Tools	Scripts, utilities, automation	Installation, usage, options
Libraries	npm packages, Python modules	API reference, examples
Applications	Web apps, mobile apps, services	Environment setup, deployment
Frameworks	Starter kits, boilerplates	Configuration, extending
Dev Environments	Docker setups, Nix configs	Prerequisites, bootstrapping

类型	示例	核心章节
Dotfiles	Shell配置、vim、tmux、git	工具配置、别名、快捷键
CLI工具	脚本、实用程序、自动化工具	安装、使用、选项
库	npm包、Python模块	API参考、示例
应用程序	Web应用、移动应用、服务	环境设置、部署
框架	启动模板、脚手架	配置、扩展
开发环境	Docker配置、Nix配置	前置要求、引导设置

6-Step Workflow

六步工作流程

Follow these steps sequentially to create a complete setup guide:

按顺序遵循以下步骤，创建完整的设置指南：

Step 1: Audit the Project

步骤1：项目审查

Goal: Understand what exists before documenting.

Actions:
1. List all configuration files and their purposes
2. Identify dependencies (package.json, requirements.txt, Brewfile, etc.)
3. Find existing documentation (README, docs/, wiki)
4. Note installation scripts or makefiles
5. Check for environment variables or secrets

Questions to answer:

What does this project do?
Who is the target audience?
What are the prerequisites?
Are there automated setup options?

目标： 在记录前了解项目现有内容。

Actions:
1. 列出所有配置文件及其用途
2. 识别依赖项（package.json、requirements.txt、Brewfile等）
3. 查找现有文档（README、docs/、wiki）
4. 记录安装脚本或makefile
5. 检查环境变量或密钥

需要回答的问题：

这个项目的功能是什么？
目标受众是谁？
前置要求有哪些？
是否有自动化设置选项？

Step 2: Determine Structure

步骤2：确定结构

Goal: Choose sections based on project type.

Universal sections (all projects):

Title with badges
One-line description
Features overview
Table of Contents
Installation
Basic usage

Conditional sections (by type):

If Project Has...	Include Section
Multiple tools/configs	Repository Structure
CLI commands	Command Reference
Configuration options	Configuration Guide
Shell customizations	Aliases & Functions
Keyboard shortcuts	Keybindings
API surface	API Reference
Visual components	Screenshots
Breaking changes	Migration Guide
Community	Contributing Guide

目标： 根据项目类型选择章节。

通用章节（所有项目）：

带徽章的标题
一句话描述
功能概述
目录
安装
基础使用

条件章节（按类型）：

如果项目包含...	包含章节
多个工具/配置	仓库结构
CLI命令	命令参考
配置选项	配置指南
Shell自定义	别名与函数
键盘快捷键	快捷键
API接口	API参考
可视化组件	截图
破坏性变更	迁移指南
社区	贡献指南

Step 3: Document Core Information

步骤3：记录核心信息

Goal: Write the essential sections every README needs.

目标： 编写每个README都需要的核心章节。

Title Block Pattern

标题块模板

markdown

undefined

markdown

undefined

Project Name

项目名称

One-line description of what this project does

undefined

一句话描述项目功能

undefined

Features Section Pattern

功能章节模板

Use a table for scannable feature lists:

markdown

undefined

使用表格呈现便于扫描的功能列表：

markdown

undefined

Features at a Glance

功能概览

Category	Features
Shell	Zsh with Powerlevel10k, syntax highlighting, autosuggestions
Editor	Neovim with LSP, Telescope, Treesitter
Terminal	Tmux with custom keybindings, Alacritty config

undefined

类别	功能
Shell	Zsh + Powerlevel10k、语法高亮、自动建议
编辑器	Neovim + LSP、Telescope、Treesitter
终端	Tmux + 自定义快捷键、Alacritty配置

undefined

Repository Structure Pattern

仓库结构模板

markdown

undefined

markdown

undefined

Repository Structure

仓库结构

``` project-root/ ├── config/ # Application configurations │ ├── app.config.ts │ └── database.ts ├── src/ # Source code │ ├── components/ │ └── utils/ ├── scripts/ # Automation scripts │ └── setup.sh └── README.md ```

undefined

``` project-root/ ├── config/ # 应用配置 │ ├── app.config.ts │ └── database.ts ├── src/ # 源代码 │ ├── components/ │ └── utils/ ├── scripts/ # 自动化脚本 │ └── setup.sh └── README.md ```

undefined

Step 4: Write Setup Instructions

步骤4：编写设置说明

Goal: Provide clear, tested installation steps.

目标： 提供清晰、经过测试的安装步骤。

The Dual Setup Pattern

双重设置模板

Always offer both automated AND manual options when possible:

markdown

undefined

尽可能同时提供自动化和手动两种选项：

markdown

undefined

Installation

安装

Quick Start (Recommended)

快速开始（推荐）

```bash

One-line installation

一键安装

curl -fsSL https://example.com/install.sh | bash ```

Manual Installation

手动安装

<details> <summary>Click to expand manual steps</summary>

Clone the repository: ```bash git clone https://github.com/user/project.git cd project ```
Install dependencies: ```bash npm install ```
Configure environment: ```bash cp .env.example .env

Edit .env with your values

```

</details> ```

<details> <summary>点击展开手动步骤</summary>

克隆仓库： ```bash git clone https://github.com/user/project.git cd project ```
安装依赖： ```bash npm install ```
配置环境： ```bash cp .env.example .env

编辑.env文件填入你的值

```

</details> ```

Prerequisites Pattern

前置要求模板

markdown

undefined

markdown

undefined

Prerequisites

前置要求

Requirement	Version	Check Command
Node.js	≥18.0	`node --version`
npm	≥9.0	`npm --version`
Git	≥2.0	`git --version`

undefined

要求	版本	检查命令
Node.js	≥18.0	`node --version`
npm	≥9.0	`npm --version`
Git	≥2.0	`git --version`

undefined

Environment Variables Pattern

环境变量模板

markdown

undefined

markdown

undefined

Environment Variables

环境变量

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`API_KEY`	Yes	-	External service API key
`DEBUG`	No	`false`	Enable debug logging

undefined

变量	是否必填	默认值	描述
`DATABASE_URL`	是	-	PostgreSQL连接字符串
`API_KEY`	是	-	外部服务API密钥
`DEBUG`	否	`false`	启用调试日志

undefined

Step 5: Document Commands & Usage

步骤5：记录命令与使用方法

Goal: Show users how to actually use the project.

目标： 向用户展示如何实际使用项目。

Command Reference Pattern

命令参考模板

markdown

undefined

markdown

undefined

Commands

命令

Command	Description
`npm start`	Start development server
`npm test`	Run test suite
`npm run build`	Build for production
`npm run lint`	Check code style

undefined

命令	描述
`npm start`	启动开发服务器
`npm test`	运行测试套件
`npm run build`	构建生产版本
`npm run lint`	检查代码风格

undefined

Usage Examples Pattern

使用示例模板

markdown

undefined

markdown

undefined

Usage

使用方法

Basic Example

基础示例

```typescript import { something } from 'project';

const result = something({ option: 'value' }); ```

```typescript import { something } from 'project';

const result = something({ option: 'value' }); ```

Advanced Example

进阶示例

```typescript // More complex usage with all options import { something, configure } from 'project';

configure({ debug: true, timeout: 5000 });

const result = await something({ option: 'value', callback: (data) => console.log(data) }); ```

undefined

```typescript // 包含所有选项的复杂用法 import { something, configure } from 'project';

configure({ debug: true, timeout: 5000 });

const result = await something({ option: 'value', callback: (data) => console.log(data) }); ```

undefined

Step 6: Add Supporting Sections

步骤6：添加辅助章节

Goal: Complete the README with helpful extras.

目标： 用实用的补充内容完善README。

Configuration Pattern

配置模板

markdown

undefined

markdown

undefined

Configuration

配置

Configuration file:

config.json

```json { "setting1": "value", "setting2": true, "nested": { "option": "value" } } ```

Option	Type	Default	Description
`setting1`	string	`"default"`	Description of setting1
`setting2`	boolean	`false`	Description of setting2

undefined

配置文件：

config.json

```json { "setting1": "value", "setting2": true, "nested": { "option": "value" } } ```

选项	类型	默认值	描述
`setting1`	string	`"default"`	setting1的描述
`setting2`	boolean	`false`	setting2的描述

undefined

Troubleshooting Pattern

故障排除模板

markdown

undefined

markdown

undefined

Troubleshooting

故障排除

<details> <summary>Error: Module not found</summary>

Cause: Dependencies not installed properly.

Solution: ```bash rm -rf node_modules npm install ```

</details> <details> <summary>Permission denied</summary>

Cause: Script lacks execute permission.

Solution: ```bash chmod +x scripts/setup.sh ```

</details> ```

<details> <summary>错误：模块未找到</summary>

原因： 依赖项未正确安装。

解决方案： ```bash rm -rf node_modules npm install ```

</details> <details> <summary>权限被拒绝</summary>

原因： 脚本缺少执行权限。

解决方案： ```bash chmod +x scripts/setup.sh ```

</details> ```

Updating Pattern

更新模板

markdown

undefined

markdown

undefined

Updating

更新

```bash

Pull latest changes

拉取最新变更

git pull origin main

Update dependencies

更新依赖

npm install

Run migrations (if applicable)

运行迁移（如适用）

npm run migrate ```

undefined

npm run migrate ```

undefined

Uninstall Pattern

卸载模板

markdown

undefined

markdown

undefined

Uninstallation

卸载

```bash

Remove installed files

移除已安装文件

npm uninstall -g project-name

Clean up configuration (optional)

清理配置（可选）

rm -rf ~/.config/project-name ```

---

rm -rf ~/.config/project-name ```

---

Project-Specific Guidance

项目特定指南

For Dotfiles Projects

针对Dotfiles项目

Must include:

Tool-by-tool breakdown with features
Aliases and abbreviations table
Custom functions documentation
Keybindings reference (especially for tmux/vim)
Backup instructions before installation
Symlink strategy explanation

Example structure:

markdown

undefined

必须包含：

按工具拆分的功能说明
别名与缩写表格
自定义函数文档
快捷键参考（尤其是tmux/vim）
安装前的备份说明
符号链接策略解释

示例结构：

markdown

undefined

Tools Included

包含的工具

Zsh

Theme: Powerlevel10k
Plugins: syntax-highlighting, autosuggestions, fzf
Custom aliases: see below

主题：Powerlevel10k
插件：语法高亮、自动建议、fzf
自定义别名：见下方

Neovim

Plugin manager: lazy.nvim
LSP servers: typescript, lua, python
Keybindings: see below

插件管理器：lazy.nvim
LSP服务器：typescript、lua、python
快捷键：见下方

Shell Aliases

Shell别名

Alias	Expansion	Description
`ll`	`ls -la`	Long list with hidden
`..`	`cd ..`	Go up one directory
`g`	`git`	Git shorthand

别名	展开内容	描述
`ll`	`ls -la`	显示长列表及隐藏文件
`..`	`cd ..`	返回上一级目录
`g`	`git`	Git简写

Keybindings

快捷键

Tmux

Key	Action
`Ctrl-a`	Prefix key
`Prefix + \|`	Vertical split
`Prefix + -`	Horizontal split

undefined

按键	操作
`Ctrl-a`	前缀键
`Prefix + \|`	垂直拆分
`Prefix + -`	水平拆分

undefined

For Libraries/Packages

针对库/包

Must include:

Installation via package manager
Import/require examples
API reference with types
Multiple usage examples (basic → advanced)
TypeScript types documentation (if applicable)

Example structure:

markdown

undefined

必须包含：

通过包管理器安装
导入/引用示例
带类型的API参考
多个使用示例（基础→进阶）
TypeScript类型文档（如适用）

示例结构：

markdown

undefined

Installation

安装

```bash npm install package-name

or

或

yarn add package-name

or

或

pnpm add package-name ```

Quick Start

快速开始

```typescript import { mainFunction } from 'package-name';

const result = mainFunction('input'); ```

```typescript import { mainFunction } from 'package-name';

const result = mainFunction('input'); ```

API Reference

API参考

mainFunction(input, options?)

mainFunction(input, options?)

Parameter	Type	Required	Description
`input`	`string`	Yes	The input to process
`options`	`Options`	No	Configuration options

Returns:

Result

Example: ```typescript const result = mainFunction('hello', { uppercase: true }); // => 'HELLO' ```

undefined

参数	类型	是否必填	描述
`input`	`string`	是	要处理的输入
`options`	`Options`	否	配置选项

返回：

Result

示例： ```typescript const result = mainFunction('hello', { uppercase: true }); // => 'HELLO' ```

undefined

For Applications

针对应用程序

Must include:

System requirements
Environment setup (env vars, config files)
Development vs production instructions
Database setup (if applicable)
Deployment guide

Example structure:

markdown

undefined

必须包含：

系统要求
环境设置（环境变量、配置文件）
开发与生产环境说明
数据库设置（如适用）
部署指南

示例结构：

markdown

undefined

Getting Started

快速开始

Prerequisites

前置要求

Node.js 18+
PostgreSQL 14+
Redis (optional, for caching)

Node.js 18+
PostgreSQL 14+
Redis（可选，用于缓存）

Development Setup

开发环境设置

Clone and install: ```bash git clone https://github.com/user/app.git cd app npm install ```
Set up database: ```bash createdb myapp_dev npm run db:migrate npm run db:seed ```
Configure environment: ```bash cp .env.example .env ```
Start development server: ```bash npm run dev ```

克隆并安装： ```bash git clone https://github.com/user/app.git cd app npm install ```
设置数据库： ```bash createdb myapp_dev npm run db:migrate npm run db:seed ```
配置环境： ```bash cp .env.example .env ```
启动开发服务器： ```bash npm run dev ```

Production Deployment

生产部署

See Deployment Guide

---

查看部署指南

---

Formatting Standards

格式标准

Tables

表格

Use tables for: features, commands, env vars, options, keybindings
Always include header row
Align columns for readability in raw markdown

使用表格展示：功能、命令、环境变量、选项、快捷键
始终包含表头行
在原始Markdown中对齐列以提高可读性

Code Blocks

代码块

Always specify language for syntax highlighting
Use
```
bash
```
for shell commands
Use
```
typescript
```
over
```
javascript
```
when types are shown
Keep examples concise but complete

始终指定语言以启用语法高亮
Shell命令使用
```
bash
```
显示类型时使用
```
typescript
```
而非
```
javascript
```
示例保持简洁但完整

Collapsible Sections

可折叠章节

Use

<details>

for:

Long installation steps
Troubleshooting items
Optional/advanced content
Manual alternatives to automated steps

markdown

<details>
<summary>Click to expand</summary>

Content here...

</details>

使用

<details>

标签展示：

冗长的安装步骤
故障排除项
可选/进阶内容
自动化步骤的手动替代方案

markdown

<details>
<summary>Click to expand</summary>

Content here...

</details>

Badges

徽章

Place at top of README, common badges:

License
Version/Release
Build status
npm/PyPI downloads
Code coverage

markdown

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![npm version](https://badge.fury.io/js/package.svg)](https://npmjs.com/package/package)

放置在README顶部，常见徽章：

许可证
版本/发布
构建状态
npm/PyPI下载量
代码覆盖率

markdown

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![npm version](https://badge.fury.io/js/package.svg)](https://npmjs.com/package/package)

Section Templates Reference

章节模板参考

For detailed, copy-paste-ready templates for each project type, see: references/section-templates.md

如需各项目类型的详细可复制模板，请查看： references/section-templates.md

Quality Checklist

质量检查清单

Example Workflow

示例工作流程

User: "Create a setup guide for my dotfiles repo"

Claude's approach:

Read the repository structure to understand what's included
Identify all configuration files and tools
Check for existing install scripts
Ask clarifying questions if needed (target OS, experience level)
Generate README using dotfiles-specific sections
Include tool breakdown, aliases, keybindings tables
Provide both automated and manual install options

用户： "为我的dotfiles仓库创建设置指南"

Claude的处理方式：

读取仓库结构以了解包含的内容
识别所有配置文件和工具
检查现有安装脚本
如有需要，提出澄清问题（目标操作系统、经验水平）
使用Dotfiles特定章节生成README
包含工具分解、别名、快捷键表格
提供自动化和手动两种安装选项

project-setup-guide

Original

Translation

Project Setup Guide Skill

项目设置指南Skill

Supported Project Types

支持的项目类型

6-Step Workflow

六步工作流程

Step 1: Audit the Project

步骤1：项目审查

Step 2: Determine Structure

步骤2：确定结构

Step 3: Document Core Information

步骤3：记录核心信息

Title Block Pattern

标题块模板

Project Name

项目名称

Features Section Pattern

功能章节模板

Features at a Glance

功能概览

Repository Structure Pattern

仓库结构模板

Repository Structure

仓库结构

Step 4: Write Setup Instructions

步骤4：编写设置说明

The Dual Setup Pattern

双重设置模板

Installation

安装

Quick Start (Recommended)

快速开始（推荐）

One-line installation

一键安装

Manual Installation

手动安装

Edit .env with your values

编辑.env文件填入你的值

Prerequisites Pattern

前置要求模板

Prerequisites

前置要求

Environment Variables Pattern

环境变量模板

Environment Variables

环境变量

Step 5: Document Commands & Usage

步骤5：记录命令与使用方法

Command Reference Pattern

命令参考模板

Commands

命令

Usage Examples Pattern

使用示例模板

Usage

使用方法

Basic Example

基础示例

Advanced Example

进阶示例

Step 6: Add Supporting Sections

步骤6：添加辅助章节

Configuration Pattern

配置模板

Configuration

配置

Troubleshooting Pattern

故障排除模板

Troubleshooting

故障排除

Updating Pattern

更新模板

Updating

更新

Pull latest changes

拉取最新变更

Update dependencies

`mainFunction(input, options?)`

`mainFunction(input, options?)`