Skill Learning

setup-pre-commit

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 17 处。

# Setup

## What This Sets Up

- **Husky** pre-commit hook - **lint-staged** - **Prettier** config (if missing) - **typecheck** and **test** scripts in the pre-commit hook

## Steps

### 1. Detect package manager

Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. .

### 2. Install dependencies

``` husky lint-staged prettier ```

### 3.

```bash npx husky init ```

This creates `.husky/` dir and adds `prepare: "husky"` to package.json.

### 4. Create `.husky/pre-commit`

Write this file ( for Husky v9+):

``` npx lint-staged npm run typecheck npm run test ```

**Adapt**: Replace `npm` with . If repo has no `typecheck` or `test` script in package.json, and tell the user.

### 5. Create `.lintstagedrc`

```json { "*": "prettier --ignore-unknown --write" } ```

### 6. Create `.prettierrc` (if missing)

. Use these defaults:

```json { "useTabs": false, "tabWidth": 2, "printWidth": 80, "singleQuote": false, "trailingComma": "es5", "semi": true, "arrowParens": "always" } ```

### 7. Verify

- [ ] `.husky/pre-commit` - [ ] `.lintstagedrc` exists - [ ] `prepare` script in package.json is `"husky"` - [ ] `prettier` config exists - [ ] Run `npx lint-staged` to verify it works

### 8. Commit

Stage all changed/created files and commit with message: `Add (husky + lint-staged + prettier)`

This will : that everything works.

## Notes

- Husky v9+ doesn't need shebangs in hook files - `prettier --ignore-unknown` (images, etc.) - The pre-commit runs lint-staged first (fast, ), then full typecheck and tests

Source metadata

--- name: setup-pre-commit description: Set up Husky with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add , set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing. ---

# 设置提交前钩子

## 本技能会设置什么

- **Husky** pre-commit hook - **lint-staged**：对所有已暂存文件运行 Prettier - **Prettier** 配置（如果缺失） - pre-commit hook 中的 **typecheck** 和 **test** 脚本

## 步骤

### 1. 检测包管理器

检查 `package-lock.json`（npm）、`pnpm-lock.yaml`（pnpm）、`yarn.lock`（yarn）、`bun.lockb`（bun）。使用存在的那一种。如果无法确定，默认使用 npm。

### 2. 安装依赖

将以下包安装为 devDependencies：

``` husky lint-staged prettier ```

### 3. 初始化 Husky

```bash npx husky init ```

这会创建 `.husky/` 目录，并向 package.json 添加 `prepare: "husky"`。

### 4. 创建 `.husky/pre-commit`

写入以下文件（Husky v9+ 不需要 shebang）：

``` npx lint-staged npm run typecheck npm run test ```

**按仓库调整**：把 `npm` 替换为检测到的包管理器。如果仓库的 package.json 中没有 `typecheck` 或 `test` 脚本，就省略对应行并告知用户。

### 5. 创建 `.lintstagedrc`

```json { "*": "prettier --ignore-unknown --write" } ```

### 6. 创建 `.prettierrc`（如果缺失）

仅在不存在 Prettier 配置时创建。使用以下默认值：

```json { "useTabs": false, "tabWidth": 2, "printWidth": 80, "singleQuote": false, "trailingComma": "es5", "semi": true, "arrowParens": "always" } ```

### 7. 验证

- [ ] `.husky/pre-commit` 存在且可执行 - [ ] `.lintstagedrc` 存在 - [ ] package.json 中的 `prepare` 脚本为 `"husky"` - [ ] `prettier` 配置存在 - [ ] 运行 `npx lint-staged` 验证它可以工作

### 8. 提交

暂存所有已更改或新建的文件，并使用以下消息提交：`Add pre-commit hooks (husky + lint-staged + prettier)`

这次提交会经过新建的 pre-commit hooks，是检验一切是否工作的良好冒烟测试。

## 备注

- Husky v9+ 的 hook 文件不需要 shebang - `prettier --ignore-unknown` 会跳过 Prettier 无法解析的文件（图像等） - pre-commit 先运行 lint-staged（速度快，仅处理已暂存文件），再运行完整的类型检查和测试

Source metadata

--- name: setup-pre-commit description: 在当前仓库中设置 Husky pre-commit hooks，配合 lint-staged（Prettier）、类型检查和测试。当用户希望添加 pre-commit hooks、设置 Husky、配置 lint-staged，或增加提交时的格式化、类型检查与测试时使用。 ---

Entry SHA-256: c9819d7f1e3b198064edc1faa3154224ed67395e9f07f5d3cea4b67cf0a11a98

2. Why This Skill Is Clever

一句话核心机制

它先读取仓库已有的包管理器、脚本和格式化配置，再只补齐缺失的提交前质量链路，最后用一次真实提交把配置本身当作验收对象。

触发与边界

直接来源： frontmatter 把触发范围收紧到“add pre-commit hooks”“set up Husky”“configure lint-staged”以及提交时格式化、类型检查、测试。它是面向现有 JavaScript/TypeScript 仓库的设置流程，而不是通用 Git hook 教程。

支持背景： skills/misc/README.md 明确把它归为 misc，也就是作者保留但很少使用、未随插件发布的非 promoted 工具。agents/openai.yaml 只提供显示名和短描述，没有增加执行规则。

解释： 该技能假设仓库有 package.json、Node 包管理器和可运行的 npx。对非 Node 仓库、没有 Git 工作树的目录，或不允许自动提交的环境，需要改写流程，而不是机械执行。

信息架构 / 执行顺序

探测环境：通过锁文件确定 npm、pnpm、yarn 或 bun，证据不清楚时才回退 npm。
安装与初始化：先安装 Husky、lint-staged、Prettier，再运行 npx husky init 建立基础钩子结构。
按现状适配：生成 hook 时复用检测出的包管理器；缺少 typecheck 或 test 脚本就省略，不虚构命令。
保护已有配置：只有完全没有 Prettier 配置时才写 .prettierrc。
逐项验证并真实提交：先核对文件、权限和脚本，再让新钩子处理这次配置提交，完成端到端 smoke test。

最巧妙的设计点

1. 探测先于生成

“Use whichever is present. Default to npm if unclear.”

直接来源： 锁文件是包管理器选择的证据，npm 只是信息不足时的回退。这样避免在 pnpm、yarn 或 bun 仓库里混入错误命令和额外锁文件。

2. 缺失能力不伪装成存在

“If repo has no typecheck or test script ... omit those lines and tell the user.”

直接来源： 技能把“省略不可运行命令”和“告知用户”绑定起来。前者保证 hook 可执行，后者保留质量覆盖缺口的可见性，既不让提交全部失败，也不假装已经做过类型检查或测试。

3. 默认值服从仓库已有约定

“Only create if no Prettier config exists.”

直接来源： 默认 .prettierrc 是补缺机制，不是覆盖机制。这条限制把仓库本地约定置于技能作者偏好之上，降低侵入性。

4. 快检查和慢检查按成本排序

“lint-staged first (fast, staged-only), then full typecheck and tests”

直接来源： 最便宜、最局部的格式化先执行，失败时可以快速返回；更昂贵的全量类型检查和测试随后运行。这是典型的 fail-fast 排序。

5. 用真实提交验证提交钩子

“a good smoke test that everything works.”

直接来源： 最后一步不是只检查配置文本，而是让配置变更本身穿过刚建立的 hook。它验证了安装、权限、脚本解析和执行顺序的整体链路。

防失败机制与 trade-off

明确不变量： hook 文件必须存在且可执行；prepare 必须指向 Husky；Prettier 配置必须存在；npx lint-staged 必须实际运行。已有 Prettier 配置不能被默认配置覆盖，缺失的 package scripts 不能被编造。

权衡与风险： 每次提交都跑全量 typecheck 与 tests 能提高本地质量门槛，但大型仓库会显著变慢，开发者也可能因此绕过 hooks。"*" 交给 prettier --ignore-unknown --write 很简单，却可能暂存格式化后的额外改动，需要确认 lint-staged 的再暂存行为。npx husky init、Husky v9 无 shebang 的假设和 npm 风格命令都依赖具体工具版本；在不同版本或 CI harness 中必须重新核对。

可迁移原则

先从锁文件、清单和已有配置中读取事实，再生成命令。
默认值只用于填补空白，不覆盖项目已经作出的选择。
对不存在的能力明确降级并披露，不生成注定失败的占位步骤。
按“便宜且局部 → 昂贵且全量”排序质量检查，以便快速失败。
用最接近真实用户动作的 smoke test 验证自动化链路，而不只验证文件存在。

今日实践题

如果一个 pnpm 仓库已有 Prettier 配置，但没有 test 脚本，这个技能生成的 .husky/pre-commit 应保留哪两条命令，又必须明确告诉用户哪个质量门缺失？

Evidence note

包管理器探测、Husky 初始化、条件化脚本、配置保护、验证清单与提交 smoke test 都来自所选 SKILL.md。misc 身份来自同仓库的 skills/misc/README.md，显示元数据来自 agents/openai.yaml；它们只作为支持背景。关于 fail-fast、侵入性、性能和可移植性的判断属于设计解释。

Source & provenance

Repository path: skills/misc/setup-pre-commit/SKILL.md
Generated: 2026-08-28 13:48 Asia/Shanghai
Upstream commit: 6654f6b60cd9d5be8b54c6fafe44346dabeb3b76
Source: View on GitHub