登录
【笔记】xxx 技术分享文档模板
2026年3月12日 18:56
纯模板，下次需要直接贴给 AI 然后替换内容就行
skills 技术分享文档
一、项目概述
1.1 项目定位
skills 是团队为 Claude Code 打造的通用技能工具集，通过 npm 包的形式进行分发和管理，旨在提升团队开发效率和代码质量。
-
包名:
skills - 仓库: gitlab.example.com/team/skills
- Registry: npm.example.com/
- 当前版本: 1.0.1
1.2 核心价值
- 知识共享: 将团队最佳实践封装为可复用的技能
- 效率提升: 自动化重复性工作流程
- 规范统一: 确保团队操作流程一致性
- 降低门槛: 新成员快速上手团队工作方式
二、技术架构
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 - 创意设计助手
使用场景: 在进行任何创造性工作之前（创建功能、构建组件、修改行为）
工作流程:
- 理解上下文: 检查项目状态（文件、文档、最近提交）
- 逐步提问: 每次只问一个问题，避免信息过载
- 方案探索: 提出 2-3 种方案并说明权衡
- 分段展示: 每段 200-300 字，逐步验证设计
-
文档输出: 将确认的设计写入
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 - 合并到开发环境
触发方式:
- 由
merge-to-test成功后自动触发 - 用户主动请求："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
信息收集流程:
- 需求名称（可直接从项目管理系统复制）
- 简要描述（做什么、预期什么结果）
- 技术变更点
- 影响范围（文件或模块）
- 接口信息（如有）
- 出入参（如有）
格式化输出:
/openspec:proposal 这里有个新需求需要创建提案：【<需求名称>】
简单描述：<做什么，要什么结果>
具体需求：<技术变更点>
影响范围：<文件或模块路径>
接口：<如果有则填写，没有则用占位符>
出入参：<如果有则填写，没有则用 {} 占位>
五、核心命令详解
5.1 create-branch - AI 辅助分支创建
功能: 从项目管理系统 Story 创建功能分支，AI 自动翻译分支名
分支命名规范: feat/<username>/<concise-english-name>-<storyID>
核心功能:
- 信息提取: 从项目管理系统 URL 提取 storyID
- AI 翻译: 将中文标题翻译为简洁的英文分支名（3-4 词）
-
用户名获取: 从
git config user.name自动获取 - 创建模式选择: 支持普通分支和 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 安全机制
- 分支保护: 所有涉及代码修改的技能都会检查当前分支
- 用户确认: 关键操作前都需要用户确认
- 错误处理: 提供清晰的错误信息和恢复指导
- 状态回滚: 合并失败时自动切换回原分支
七、最佳实践
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:
- 创建
skills/<skill-name>/SKILL.md或Skill.md - 编写 frontmatter 元数据
- 编写技能逻辑文档
- 更新版本号并发布
新增 Command:
- 创建
commands/<command-name>.md - 编写命令说明文档
- 更新版本号并发布
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: 大多数技能都有内置的错误处理和状态恢复机制，会自动切换回原分支。
九、未来规划
- 更多技能: 持续添加团队常用的开发技能
- 配置化: 支持团队自定义配置（如分支命名规则）
- 测试覆盖: 为 CLI 工具添加自动化测试
- 文档完善: 提供更详细的使用示例和视频教程
- 性能优化: 优化安装和更新速度
十、总结
skills 通过以下方式提升开发效率：
- 标准化流程: 将团队最佳实践封装为可复用的技能
- 自动化操作: 减少重复性手工操作
- 智能辅助: AI 翻译、需求整理等智能功能
- 安全保护: 分支保护检查等安全机制
- 易于扩展: 清晰的架构便于添加新技能
通过这套工具集，新成员可以快速融入团队工作方式，老成员可以专注于核心业务逻辑，从而整体提升团队的开发效率和代码质量。
版权声明：
本文版权属于作者 林小帅，未经授权不得转载及二次修改。
转载或合作请在下方留言及联系方式。
