branch-naming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Branch Naming Skill

分支命名Skill

Operator Context

运行上下文

This skill operates as an operator for Git branch naming workflows, configuring Claude's behavior for deterministic branch name generation and validation with conventional commit integration.

本Skill作为Git分支命名工作流的操作器，配置Claude的行为以实现确定性分支名称生成和验证，并集成规范提交（conventional commit）机制。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Deterministic Naming: Type-to-prefix mapping, kebab-case sanitization, 50-char limit
Character Whitelist: Only a-z, 0-9, hyphens in subject; forward slash only in prefix
Over-Engineering Prevention: Only generate/validate names. No branch creation, deletion, or management
Reproduce-First Validation: Always validate generated names before presenting to user
No Speculative Features: No branch templates, cleanup tools, or management beyond naming

CLAUDE.md合规性：执行前请阅读并遵循仓库中的CLAUDE.md
确定性命名：类型到前缀的映射、kebab-case格式清理、50字符长度限制
字符白名单：主题部分仅允许a-z、0-9、连字符；前缀中仅允许使用正斜杠
避免过度设计：仅生成/验证分支名称，不涉及分支创建、删除或管理操作
先验证再输出：生成名称后必须先验证，再呈现给用户
无推测性功能：不提供分支模板、清理工具或命名之外的管理功能

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Interactive Confirmation: Show generated name and ask for confirmation before use
Conventional Commit Inference: Detect commit type from message and map to prefix
Duplicate Detection: Check if proposed name already exists locally or remotely
Suggestion Alternatives: If name exists, suggest alternatives (-v2, -alt, timestamp)
Sanitization Pipeline: Lowercase, hyphenate, strip special chars, collapse hyphens
Intelligent Truncation: Remove filler words and abbreviate to fit length limit

交互式确认：显示生成的名称并在使用前请求用户确认
规范提交推断：从提交信息中检测类型并映射到对应前缀
重复检测：检查提议的名称是否已在本地或远程仓库存在
备选名称建议：如果名称已存在，提供备选方案（如-v2、-alt、时间戳）
清理流水线：转换为小写、替换为连字符、移除特殊字符、合并连续连字符
智能截断：移除填充词并缩写以符合长度限制

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Auto-Accept: Skip confirmation for automated/scripted workflows
Custom Prefix Rules: Override default type-to-prefix mapping via .branch-naming.json
Allow Long Names: Bypass 50-char limit for exceptional cases

自动确认：在自动化/脚本化工作流中跳过确认步骤
自定义前缀规则：通过.branch-naming.json文件覆盖默认的类型到前缀映射
允许长名称：特殊场景下绕过50字符长度限制

What This Skill CAN Do

本Skill可实现的功能

Parse conventional commit messages to extract type and subject
Map commit types to branch prefixes (feat -> feature/, fix -> fix/, etc.)
Sanitize text to kebab-case following the 7-step pipeline
Validate branch name format (prefix, length, characters, duplicates)
Generate alternative names when duplicates exist

解析规范提交信息以提取类型和主题
将提交类型映射到分支前缀（如feat -> feature/、fix -> fix/等）
按照7步流水线将文本清理为kebab-case格式
验证分支名称格式（前缀、长度、字符、重复项）
当存在重复名称时生成备选名称

What This Skill CANNOT Do

本Skill不可实现的功能

Create, delete, or manage Git branches (use git directly)
Enforce GitHub branch protection rules (GitHub settings)
Resolve naming conflicts between competing conventions (human judgment)
Auto-rename existing branches (risks breaking active work)

创建、删除或管理Git分支（请直接使用Git命令）
强制执行GitHub分支保护规则（需在GitHub设置中配置）
解决不同命名规范之间的冲突（需人工判断）
自动重命名现有分支（可能破坏正在进行的工作）

Instructions

操作步骤

Phase 1: ANALYZE

阶段1：分析

Goal: Parse input and determine commit type and subject.

Step 1: Parse input

If conventional commit message provided (e.g.,

feat: add user auth

Extract type, optional scope, and subject
Pattern:
```
<type>[optional scope]: <description>
```

If plain description provided (e.g.,

add user authentication

Infer type from keywords (see
```
references/type-mapping.md
```
for full mapping)
Keywords: add/implement/create -> feat, fix/resolve/correct -> fix, document/readme -> docs, refactor/restructure -> refactor, test/spec -> test, remove/delete/update -> chore
Default if no keywords match: feat

Step 2: Validate input content

Strip banned characters (emojis, special chars)
If input is too vague to determine type, prompt user for specifics

Gate: Commit type identified and subject extracted. If FAIL, prompt user for clarification.

目标：解析输入内容，确定提交类型和主题。

步骤1：解析输入

如果提供规范提交信息（例如：

feat: add user auth

）：

提取类型、可选范围和主题
格式：
```
<type>[可选范围]: <描述>
```

如果提供普通描述（例如：

add user authentication

）：

根据关键词推断类型（完整映射请参考
```
references/type-mapping.md
```
）
关键词映射：add/implement/create -> feat，fix/resolve/correct -> fix，document/readme -> docs，refactor/restructure -> refactor，test/spec -> test，remove/delete/update -> chore
无匹配关键词时默认类型：feat

步骤2：验证输入内容

移除禁用字符（表情符号、特殊字符）
如果输入过于模糊无法确定类型，提示用户补充信息

校验门：已识别提交类型并提取主题。若失败，提示用户澄清。

Phase 2: GENERATE

阶段2：生成

Goal: Produce a valid branch name from analyzed input.

Step 1: Map type to prefix

Standard mapping (see

references/type-mapping.md

for details):

Type	Prefix
feat	feature/
fix	fix/
docs	docs/
refactor	refactor/
test	test/
chore	chore/
style	style/
perf	perf/
build	build/
ci	ci/
revert	revert/

Check for

.branch-naming.json

in repository root for custom overrides.

Step 2: Sanitize subject to kebab-case

Apply the 7-step sanitization pipeline (see

references/sanitization-rules.md

Lowercase
Strip leading/trailing whitespace
Replace spaces with hyphens
Replace underscores with hyphens
Remove special characters (keep only a-z, 0-9, hyphens)
Collapse multiple consecutive hyphens
Remove leading/trailing hyphens

Step 3: Apply length limits

Total branch name (prefix + subject) must be 50 characters or fewer. If exceeded:

Remove filler words (the, a, with, and, for, etc.)
Apply common abbreviations (authentication -> auth, configuration -> config)
Truncate at word boundaries (never cut mid-word)

Step 4: Combine prefix + sanitized subject

Example:

feat: add user authentication

feature/add-user-authentication

Gate: Valid branch name generated (correct prefix, kebab-case, within length limit, allowed characters only).

目标：根据分析后的输入生成有效的分支名称。

步骤1：类型到前缀的映射

标准映射（详细内容请参考

references/type-mapping.md

）：

类型	前缀
feat	feature/
fix	fix/
docs	docs/
refactor	refactor/
test	test/
chore	chore/
style	style/
perf	perf/
build	build/
ci	ci/
revert	revert/

检查仓库根目录下的

.branch-naming.json

文件是否存在自定义覆盖规则。

步骤2：将主题清理为kebab-case格式

应用7步清理流水线（请参考

references/sanitization-rules.md

）：

转换为小写
移除首尾空格
将空格替换为连字符
将下划线替换为连字符
移除特殊字符（仅保留a-z、0-9、连字符）
合并连续的多个连字符
移除首尾的连字符

步骤3：应用长度限制

分支名称总长度（前缀+主题）必须不超过50字符。如果超出限制：

移除填充词（如the、a、with、and、for等）
使用常见缩写（如authentication -> auth、configuration -> config）
在单词边界处截断（绝不从单词中间截断）

步骤4：合并前缀+清理后的主题

示例：

feat: add user authentication

feature/add-user-authentication

校验门：已生成有效的分支名称（正确前缀、kebab-case格式、符合长度限制、仅包含允许的字符）。

Phase 3: VALIDATE

阶段3：验证

Goal: Confirm generated name meets all requirements.

Step 1: Format validation

Has valid prefix from allowed list
Subject is kebab-case
Only allowed characters (a-z, 0-9, hyphens, one forward slash)
No leading/trailing hyphens in subject
No consecutive hyphens

Step 2: Length check

Total length is 50 characters or fewer

Step 3: Duplicate detection

bash

undefined

目标：确认生成的名称符合所有要求。

步骤1：格式验证

包含允许列表中的有效前缀
主题为kebab-case格式
仅包含允许的字符（a-z、0-9、连字符、一个正斜杠）
主题部分无首尾连字符
无连续连字符

步骤2：长度检查

总长度不超过50字符

步骤3：重复检测

bash

undefined

Check local

检查本地分支

git branch --list "<branch-name>"

Check remote

检查远程分支

git ls-remote --heads origin "<branch-name>"


If duplicate found, generate alternatives:
1. Append `-v2`, `-v3` for versioning
2. Append date `-YYYYMMDD` for uniqueness
3. Ask user for custom suffix

**Step 4: Repository convention compliance**

Check `.branch-naming.json` if present for custom prefix restrictions.

**Gate**: All validation checks pass. If FAIL, regenerate with adjustments or present alternatives.

git ls-remote --heads origin "<branch-name>"


如果发现重复名称，生成备选方案：
1. 添加版本后缀（如-v2、-v3）
2. 添加日期后缀（如-YYYYMMDD）以确保唯一性
3. 提示用户提供自定义后缀

**步骤4：仓库规范合规性检查**

如果存在`.branch-naming.json`文件，检查是否符合自定义前缀限制。

**校验门**：所有验证检查通过。若失败，调整后重新生成或提供备选名称。

Phase 4: CONFIRM

阶段4：确认

Goal: Present validated name and get user approval.

Step 1: Display result

Generated Branch Name: feature/add-user-authentication
  Type: feat (feature)
  Length: 31 characters
  Format: Valid
  Duplicates: None found

Use this branch name? [Y/n]

Step 2: Handle response

Yes: Output final name with git checkout command
No: Return to Phase 1 with new input
Customize: User provides custom name, run through Phase 3 validation

Gate: User approved name. Workflow complete.

目标：呈现验证后的名称并获取用户批准。

步骤1：显示结果

生成的分支名称：feature/add-user-authentication
  类型：feat（feature）
  长度：31字符
  格式：有效
  重复项：未找到

是否使用此分支名称？[Y/n]

步骤2：处理用户响应

是：输出最终名称及git checkout命令
否：返回阶段1，接收新的输入
自定义：用户提供自定义名称，进入阶段3进行验证

校验门：用户已批准名称。工作流完成。

Examples

示例

Example 1: From Conventional Commit

示例1：基于规范提交生成

Input:

feat: add user authentication

Actions:

Parse: type=feat, subject="add user authentication" (ANALYZE)
Map feat -> feature/, sanitize -> "add-user-authentication" (GENERATE)
Validate format, length (31 chars), no duplicates (VALIDATE)
Present and confirm (CONFIRM) Result:
```
feature/add-user-authentication
```

输入：

feat: add user authentication

操作：

解析：类型=feat，主题="add user authentication"（分析阶段）
映射feat -> feature/，清理主题为"add-user-authentication"（生成阶段）
验证格式、长度（31字符）、无重复项（验证阶段）
呈现并确认（确认阶段）结果：
```
feature/add-user-authentication
```

Example 2: From Plain Description with Truncation

示例2：基于普通描述生成并截断

Input:

add comprehensive user authentication system with OAuth2 and JWT

Actions:

Infer type=feat from "add" keyword (ANALYZE)
Sanitize, remove fillers, abbreviate auth -> 32 chars (GENERATE)
Validate all checks pass (VALIDATE)
Present and confirm (CONFIRM) Result:
```
feature/add-user-auth-oauth2-jwt
```

输入：

add comprehensive user authentication system with OAuth2 and JWT

操作：

根据关键词"add"推断类型=feat（分析阶段）
清理主题、移除填充词、缩写为auth，最终长度32字符（生成阶段）
所有验证检查通过（验证阶段）
呈现并确认（确认阶段）结果：
```
feature/add-user-auth-oauth2-jwt
```

Example 3: Validation of Existing Branch

示例3：验证现有分支名称

Input:

feature/User_Authentication

Actions:

Detect uppercase letters and underscores (VALIDATE)
Report issues with corrections Result: Suggest
```
feature/user-authentication
```

输入：

feature/User_Authentication

操作：

检测到大写字母和下划线（验证阶段）
报告问题并提供修正建议结果：建议使用
```
feature/user-authentication
```

Error Handling

错误处理

Error: "Cannot Infer Commit Type"

错误："无法推断提交类型"

Cause: Description too vague (e.g., "stuff", "things") to determine type Solution:

Prompt user to start with action verb (add, fix, update, remove)
Suggest using
```
--type
```
flag to specify explicitly
Provide examples of descriptive input

原因：描述过于模糊（如"stuff"、"things"），无法确定类型解决方案：

提示用户以动作动词开头（如add、fix、update、remove）
建议使用
```
--type
```
参数明确指定类型
提供描述性输入的示例

Error: "Name Exceeds Length Limit"

错误："名称超出长度限制"

Cause: Description too long even after truncation Solution:

Remove filler words and apply abbreviations
Suggest shorter focused description
Move detail to commit message body instead of branch name

原因：即使截断后描述仍然过长解决方案：

移除填充词并应用缩写
建议使用更简短的聚焦式描述
将详细信息移至提交信息正文而非分支名称

Error: "Duplicate Branch Detected"

错误："检测到重复分支"

Cause: Branch name already exists locally or remotely Solution:

Suggest alternatives with -v2 or date suffix
Offer to check out existing branch instead
Prompt for custom differentiating suffix

原因：分支名称已在本地或远程仓库存在解决方案：

提供带版本后缀（如-v2）或日期后缀的备选名称
提供检出现有分支的选项
提示用户提供自定义区分后缀

Anti-Patterns

反模式

Anti-Pattern 1: Underscores Instead of Hyphens

反模式1：使用下划线而非连字符

What it looks like:

feature/add_user_auth

Why wrong: Violates kebab-case convention, inconsistent with conventional commits Do instead: Use hyphens:

feature/add-user-auth

示例：

feature/add_user_auth

问题：违反kebab-case规范，与规范提交不一致 正确做法：使用连字符：

feature/add-user-auth

Anti-Pattern 2: Vague Branch Names

反模式2：模糊的分支名称

What it looks like:

feature/updates

fix/stuff

feature/branch-1

Why wrong: Impossible to understand purpose, hard to track, likely duplicates Do instead: Be specific:

feature/add-oauth2-login

fix/login-timeout-30s

示例：

feature/updates

、

fix/stuff

、

feature/branch-1

问题：无法理解用途，难以追踪，容易出现重复 正确做法：使用具体名称：

feature/add-oauth2-login

、

fix/login-timeout-30s

Anti-Pattern 3: Missing Branch Prefix

反模式3：缺少分支前缀

What it looks like:

add-user-authentication

(no prefix) Why wrong: No type indication, breaks CI/CD automation, inconsistent filtering Do instead: Always include conventional commit prefix:

feature/add-user-authentication

示例：

add-user-authentication

（无前缀）问题：无类型标识，破坏CI/CD自动化，过滤不一致 正确做法：始终包含规范提交前缀：

feature/add-user-authentication

Anti-Pattern 4: Overly Long Names

反模式4：过长的分支名称

What it looks like:

feature/add-comprehensive-user-authentication-system-with-oauth2-jwt-and-session-management

(95 chars) Why wrong: Exceeds 50-char limit, hard to read, indicates scope too large Do instead: Abbreviate and move details to commit body:

feature/add-user-auth-oauth2-jwt

示例：

feature/add-comprehensive-user-authentication-system-with-oauth2-jwt-and-session-management

（95字符）问题：超出50字符限制，难以阅读，表明范围过大 正确做法：缩写并将详细信息移至提交正文：

feature/add-user-auth-oauth2-jwt

Anti-Pattern 5: Mixing Naming Conventions

反模式5：混合命名规范

What it looks like: Repository has

feat/

feature/

bugfix/

fix/

Feature/

branches Why wrong: No standard, hard to filter, CI/CD rules only match some patterns Do instead: Enforce one convention via

.branch-naming.json

and this skill

示例：仓库中同时存在

feat/

、

feature/

、

bugfix/

、

fix/

、

Feature/

分支问题：无统一标准，难以过滤，CI/CD规则仅匹配部分模式 正确做法：通过

.branch-naming.json

和本Skill强制执行单一规范

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本Skill使用以下共享模式：

Anti-Rationalization - 防止捷径式合理化
Verification Checklist - 完成前检查

Domain-Specific Anti-Rationalization

领域特定的反合理化

Rationalization	Why It's Wrong	Required Action
"Any name is fine"	Inconsistent names break automation and readability	Use skill to generate compliant name
"I'll fix the name later"	Branch renames disrupt active work and PRs	Name correctly from the start
"50 chars is too restrictive"	Long names indicate scope creep	Abbreviate; move detail to commit body

合理化借口	问题所在	要求操作
"任何名称都可以"	不一致的名称会破坏自动化和可读性	使用本Skill生成合规名称
"我之后再改名称"	分支重命名会中断正在进行的工作和PR	从一开始就使用正确的名称
"50字符限制太严格"	长名称表明范围蔓延	缩写并将详细信息移至提交正文

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/type-mapping.md
```
: Conventional commit type to branch prefix mapping

${CLAUDE_SKILL_DIR}/references/naming-conventions.md

: Branch format rules, character whitelist, examples

```
${CLAUDE_SKILL_DIR}/references/sanitization-rules.md
```
: 7-step text sanitization pipeline and truncation strategies
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Good/bad examples with corrections and integration patterns

${CLAUDE_SKILL_DIR}/references/type-mapping.md

：规范提交类型到分支前缀的映射

${CLAUDE_SKILL_DIR}/references/naming-conventions.md

：分支格式规则、字符白名单、示例

${CLAUDE_SKILL_DIR}/references/sanitization-rules.md

：7步文本清理流水线和截断策略

```
${CLAUDE_SKILL_DIR}/references/examples.md
```
：正确/错误示例及修正、集成模式