versioning-skills

技能版本管理

在技能开发过程中使用 git 跟踪更改。创建技能后初始化仓库，每次逻辑更改后提交，并使用 git 命令比较版本或撤销错误。

创建新技能时

运行 init_skill.sh 后，立即初始化 git：

cd /home/claude/skill-name
git init
git add .
git commit -m "Initial commit: skill structure"

编辑技能时

每次逻辑更改后（添加章节、修复示例、重构），都要提交：

cd /home/claude/skill-name
git add .
git commit -m "Add: validation workflow pattern"

提交消息格式：

• "Add [feature]: description" - 新增功能
• "Fix [issue]: description" - 修复错误
• "Update [section]: description" - 内容更改
• "Refactor [component]: description" - 结构更改
• "Remove [feature]: description" - 删除内容

用户询问“有哪些更改？”时

绝不直接显示差异，而是引导用户查看文件并提供链接（见下文）。 只有当用户明确要求（“有哪些更改？”、“显示差异”）时，才创建差异文件或变更日志。

不要主动创建：

• CHANGELOG.md 文件
• 更改文档
• “以下是我的修改”摘要

原因： 更新后的代码/文档本身就是文档。创建单独的变更日志会浪费令牌并重复信息。

用户询问时，显示提交历史：

cd /home/claude/skill-name
git log --oneline

将差异保存到文件（避免浪费令牌）：

cd /home/claude/skill-name
git diff <commit-hash-1> <commit-hash-2> > /mnt/user-data/outputs/changes.diff

然后提供：[查看更改](computer:///mnt/user-data/outputs/changes.diff)

对于多个差异：

# Changed files list
git diff --name-only <commit-1> <commit-2> > /mnt/user-data/outputs/changed-files.txt

# Full diff
git diff <commit-1> <commit-2> > /mnt/user-data/outputs/full-diff.diff

# Summary stats
git diff --stat <commit-1> <commit-2> > /mnt/user-data/outputs/diff-stats.txt

错误： git diff <commit-1> <commit-2>（在 stdout 中显示，浪费令牌） 正确： git diff <commit-1> <commit-2> > /mnt/user-data/outputs/diff.txt（保存为文件并提供链接）

撤销提交或丢弃工作

撤销上次提交（保留未提交的更改）：

cd /home/claude/skill-name
git reset --soft HEAD~1

撤销上次提交（丢弃所有更改）：

git reset --hard HEAD~1

撤销指定提交（创建新提交，保留历史记录）：

git revert <commit-hash>

丢弃未提交的编辑（还原到上次提交）：

git restore .

优先使用 git revert，而不是 git reset --hard，以保留历史记录。

测试实验性更改时

进行有风险的修改前，先创建分支：

cd /home/claude/skill-name

# Create and switch to experiment branch
git checkout -b experiment-new-approach

# Make changes, test
# ... edit files ...
git add .
git commit -m "Experiment: alternative validation"

# If successful, merge back
git checkout main
git merge experiment-new-approach
git branch -d experiment-new-approach

# If failed, abandon and return to main
git checkout main
git branch -D experiment-new-approach

比较两个技能版本时

如果用户上传或提供了两个版本：

cd /home/claude
mkdir -p compare

# Extract both versions
unzip /mnt/user-data/uploads/skill-v1.zip -d compare/v1
unzip /mnt/user-data/uploads/skill-v2.zip -d compare/v2

# Initialize git in each
cd compare/v1 && git init && git add . && git commit -m "Version 1"
cd ../v2 && git init && git add . && git commit -m "Version 2"

# Compare
cd ../v1
git diff --no-index . ../v2

或者直接使用 diff，无需 git：

diff -ur compare/v1 compare/v2

打包技能时

压缩前，确认工作区状态干净：

cd /home/claude/skill-name
git status  # Should show no uncommitted changes
git log --oneline  # Review history

# Package (excludes .git automatically with -x)
cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/ -x "*.git*"

工作流集成

创建技能期间：

1. 运行 init_skill.sh
2. 立即执行：git init && git add . && git commit -m "Initial structure"
3. 编辑 SKILL.md
4. 提交：git add . && git commit -m "Add: core documentation"
5. 继续编辑 → 每次重大更改后提交

编辑技能期间：

1. 使用 str_replace 或 bash 进行更改
2. 按需测试
3. 提交：git add <file> && git commit -m "Fix: corrected example"
4. 重复上述步骤

交付前：

1. 查看历史记录：git log --oneline
2. 确认工作区干净：git status
3. 使用 -x 打包以排除 .git

配置

每个会话设置一次 git 身份信息，避免出现提示：

git config --global user.name "Claude"
git config --global user.email "[email protected]"

常见问题

“not a git repository” → 先运行 git init

“nothing to commit”
→ 没有更改，或忘记运行 git add

打开了提交消息编辑器 → 始终使用 -m "message" 提交

最佳实践

每次逻辑更改后提交，而不是每敲几个字符就提交。使用描述清晰、采用现在时的提交消息。为实验性更改创建分支。经常使用 git log --oneline 跟踪进度。

限制

/home/claude 中的 Git 仓库会在会话之间重置。版本控制仅在单个开发会话内有效。网络限制使得无法向远程仓库推送或拉取。