【笔记】xxx 技术分享文档模板

纯模板，下次需要直接贴给 AI 然后替换内容就行

skills 技术分享文档

一、项目概述

1.1 项目定位

skills 是团队为 Claude Code 打造的通用技能工具集，通过 npm 包的形式进行分发和管理，旨在提升团队开发效率和代码质量。

• 包名 : skills
• 仓库 : gitlab.example.com/team/skills
• Registry : npm.example.com/
• 当前版本: 1.0.1

1.2 核心价值

1. 知识共享: 将团队最佳实践封装为可复用的技能
2. 效率提升: 自动化重复性工作流程
3. 规范统一: 确保团队操作流程一致性
4. 降低门槛: 新成员快速上手团队工作方式

---

二、技术架构

2.1 整体架构

skills
├── bin/
│   └── cli.js          # CLI 工具入口
├── skills/             # 技能定义（自动触发或 /调用）
│   ├── brainstorming/
│   ├── merge-to-test/
│   ├── merge-to-develop/
│   └── requirement-to-spec/
├── commands/           # 命令定义（/调用）
│   └── create-branch.md
├── agents/             # 自定义 Agent 定义
└── rules/              # 全局规则约束

2.2 Claude Code 资源类型映射

类型	安装路径	触发方式	文件扩展	是否嵌套
skills	~/.claude/skills/	自动或 /skill-name	无	是
commands	~/.claude/commands/	/command-name	.md	否
agents	~/.claude/agents/	Agent 定义	.md	否
rules	~/.claude/rules/	全局应用	.md	否

---

三、CLI 工具设计

3.1 核心功能

CLI 工具提供了完整的资源生命周期管理：

# 查看可用资源
skills list
skills list skills

# 查看已安装资源
skills installed
skills installed commands

# 安装资源
skills install --all                    # 安装所有
skills install skills brainstorming    # 安装单个

# 更新资源
skills update --all
skills update commands create-branch

# 卸载资源
skills remove skills brainstorming

3.2 技术实现要点

1. 路径解析

const CLAUDE_HOME = path.join(os.homedir(), '.claude')
const TYPES = {
  skills:   { src: 'skills',   dest: path.join(CLAUDE_HOME, 'skills'),   nested: true,  ext: '' },
  commands: { src: 'commands', dest: path.join(CLAUDE_HOME, 'commands'), nested: false, ext: '.md' },
  agents:   { src: 'agents',   dest: path.join(CLAUDE_HOME, 'agents'),   nested: false, ext: '.md' },
  rules:    { src: 'rules',    dest: path.join(CLAUDE_HOME, 'rules'),    nested: false, ext: '.md' },
}

2. 嵌套目录处理 Skills 需要递归复制整个目录，而其他类型仅需复制单个文件：

if (TYPES[type].nested) {
  fs.cpSync(src, dest, { recursive: true, force: true })
} else {
  fs.copyFileSync(src, dest)
}

3. 更新策略 更新时仅更新已安装的资源，跳过不存在的资源并给出警告：

const installed = listInstalled(type)
const available = new Set(listAvailable(type))
installed.forEach(name => {
  if (available.has(name)) { installOne(type, name); count++ }
  else console.warn(`  ! [${type}] "${name}" 不在包中，跳过`)
})

---

四、核心技能详解

4.1 brainstorming - 创意设计助手

使用场景: 在进行任何创造性工作之前（创建功能、构建组件、修改行为）

工作流程:

1. 理解上下文: 检查项目状态（文件、文档、最近提交）
2. 逐步提问: 每次只问一个问题，避免信息过载
3. 方案探索: 提出 2-3 种方案并说明权衡
4. 分段展示: 每段 200-300 字，逐步验证设计
5. 文档输出 : 将确认的设计写入 docs/plans/YYYY-MM-DD-<topic>-design.md

关键原则:

• 一次只问一个问题
• 优先使用多选题而非开放题
• YAGNI 原则：移除不必要的功能
• 始终提供多种方案

4.2 merge-to-test - 自动合并到测试环境

触发条件: 用户说"推送代码"、"可以推送"、"push"时

保护分支检测:

const protectedBranches = ['master', 'test', 'develop', 'release/*']
// 如果当前分支是保护分支，则不触发

合并流程:

branch=$(git rev-parse --abbrev-ref HEAD) && \
git checkout test && \
git pull && \
git merge $branch && \
git push && \
git checkout $branch

级联触发 : 成功合并到 test 后，自动触发 merge-to-develop 询问是否部署到开发环境

4.3 merge-to-develop - 合并到开发环境

触发方式:

1. 由 merge-to-test 成功后自动触发
2. 用户主动请求："Merge to develop environment"、"Deploy to develop"

工作流程 : 与 merge-to-test 类似，目标分支为 develop

部署完成摘要:

部署完成：
✅ 测试环境 (test)
✅ 开发环境 (develop)

4.4 requirement-to-spec - 需求转技术规格

核心功能 : 通过自然对话收集需求信息，然后调用 /openspec:proposal 生成详细技术规格

分支保护检查 (关键安全机制):

// Step 0: 检查当前分支
branch=$(git branch --show-current)
if [[ "$branch" == "master" || "$branch" == "test" || "$branch" == "develop" ]]; then
  // 显示警告并询问是否切换分支
fi

信息收集流程:

1. 需求名称（可直接从项目管理系统复制）
2. 简要描述（做什么、预期什么结果）
3. 技术变更点
4. 影响范围（文件或模块）
5. 接口信息（如有）
6. 出入参（如有）

格式化输出:

/openspec:proposal 这里有个新需求需要创建提案：【<需求名称>】

简单描述：<做什么，要什么结果>

具体需求：<技术变更点>

影响范围：<文件或模块路径>

接口：<如果有则填写，没有则用占位符>

出入参：<如果有则填写，没有则用 {} 占位>

---

五、核心命令详解

5.1 create-branch - AI 辅助分支创建

功能: 从项目管理系统 Story 创建功能分支，AI 自动翻译分支名

分支命名规范 : feat/<username>/<concise-english-name>-<storyID>

核心功能:

1. 信息提取: 从项目管理系统 URL 提取 storyID
2. AI 翻译: 将中文标题翻译为简洁的英文分支名（3-4 词）
3. 用户名获取 : 从 git config user.name 自动获取
4. 创建模式选择: 支持普通分支和 Worktree 两种模式

Worktree 模式特殊处理:

• 路径格式: <main-branch-parent>/<project>.worktrees/<branch-type>/<username>/<branch-name>
• 共享 node_modules: 通过符号链接避免重复安装依赖
• Windows 符号链接: powershell -Command "cmd /c 'mklink /D <target> <source>'"
• 可选复制 route-dev.js 文件

AI 翻译规则:

• 使用小写连字符格式（如 scrm-auto-tag）
• 移除冗余词汇（"功能"、"优化"等）
• 保留重要缩写（SCRM、CRM等）
• 保持简洁，聚焦核心功能

执行流程:

# 1. 更新 master（必须）
git checkout master
git pull origin master

# 2. 创建分支
git checkout -b feat/<username>/<english-name>-<storyID>

# 3. Worktree 模式额外操作
git worktree add <worktree-path> -b <branch-name>
# 创建 node_modules 符号链接
# 可选复制 route-dev.js

---

六、集成与协作

6.1 技能间的协作

/create-branch
    ↓
/requirement-to-spec (分支保护检查)
    ↓
/openspec:proposal (生成技术规格)
    ↓
[开发实现]
    ↓
git push
    ↓
merge-to-test (自动触发)
    ↓ (成功后)
merge-to-develop (自动触发)

6.2 安全机制

1. 分支保护: 所有涉及代码修改的技能都会检查当前分支
2. 用户确认: 关键操作前都需要用户确认
3. 错误处理: 提供清晰的错误信息和恢复指导
4. 状态回滚: 合并失败时自动切换回原分支

---

七、最佳实践

7.1 发布流程

# 1. 更新版本号
npm version patch/minor/major

# 2. 发布到内部 npm
npm publish --registry http://npm.example.com/

# 3. 用户更新
npx --registry http://npm.example.com/ @company/skills update --all

7.2 本地开发

# 链接到全局
npm link

# 测试命令
skills list
skills install --all
skills installed

7.3 扩展开发指南

新增 Skill:

1. 创建 skills/<skill-name>/SKILL.md 或 Skill.md
2. 编写 frontmatter 元数据
3. 编写技能逻辑文档
4. 更新版本号并发布

新增 Command:

1. 创建 commands/<command-name>.md
2. 编写命令说明文档
3. 更新版本号并发布

Skill Frontmatter 模板:

---
name: skill-name
description: 简短描述
category: 分类（可选）
tags: [tag1, tag2]（可选）
---

---

八、常见问题

Q1: 如何调试技能执行过程？

A: Claude Code 会在执行过程中显示详细的日志输出，包括每个步骤的执行情况和结果。

Q2: Worktree 模式下符号链接创建失败？

A: Windows 需要管理员权限或开启开发者模式才能创建符号链接。可以：

• 以管理员身份运行终端
• 或启用 Windows 开发者模式

Q3: 如何自定义分支命名规则？

A: 修改 commands/create-branch.md 中的分支格式定义，然后更新发布。

Q4: 技能执行失败如何回滚？

A: 大多数技能都有内置的错误处理和状态恢复机制，会自动切换回原分支。

---

九、未来规划

1. 更多技能: 持续添加团队常用的开发技能
2. 配置化: 支持团队自定义配置（如分支命名规则）
3. 测试覆盖: 为 CLI 工具添加自动化测试
4. 文档完善: 提供更详细的使用示例和视频教程
5. 性能优化: 优化安装和更新速度

---

十、总结

skills 通过以下方式提升开发效率：

1. 标准化流程: 将团队最佳实践封装为可复用的技能
2. 自动化操作: 减少重复性手工操作
3. 智能辅助: AI 翻译、需求整理等智能功能
4. 安全保护: 分支保护检查等安全机制
5. 易于扩展: 清晰的架构便于添加新技能

通过这套工具集，新成员可以快速融入团队工作方式，老成员可以专注于核心业务逻辑，从而整体提升团队的开发效率和代码质量。

版权声明：

本文版权属于作者 林小帅，未经授权不得转载及二次修改。

转载或合作请在下方留言及联系方式。