Codex Skill Lab

一个面向 Codex Skills 的开源版本管理起步仓库：用 Git 提交记录每次修改，用 标签与 Release发布稳定版本，并用带 SHA-256 清单的本地快照作为额外保险。

GitHub 项目主页

GitHub 能“记住版本”，但前提是你把修改 commit 后再 push 到 GitHub。只修改本地文件、没有提交或没有推送，GitHub 都不会保存那次状态。

这个仓库提供什么

• 一个符合 Codex Skill 目录约定的示例：skills/manage-skill-versions/
• 零第三方依赖的 Skill 元数据校验器
• 可验证的 ZIP 快照、完整性检查与安全恢复工具
• PowerShell 入口，适合 Windows/Codex Desktop
• GitHub Actions：在 Windows 与 Linux 自动验证
• 开源项目需要的 MIT 许可证、贡献、安全与行为准则

推荐的仓库分工

仓库	可见性	放什么
codex-skill-lab	Public	通用 Skill、文档、无敏感信息的脚本
codex-skill-vault	Private	个人 Skill、私有参考资料、尚未公开的实验

不要把密码、Token、Cookie、私钥、真实账号配置或 .env 提交到任何仓库。即使后来删除，秘密也可能仍留在 Git 历史中；一旦误提交，应立即轮换凭据。

5 分钟开始

1. 本地验证

PowerShell：

Set-Location <仓库目录>
.\scripts\validate.ps1

跨平台 Python：

python scripts/validate_skills.py --root .
python -m unittest discover -s tests -v

成功时会看到 Skill validation passed 和测试 OK。

2. 新建一个 Skill

复制示例后修改文件夹名、SKILL.md 中的 name 与 description：

Copy-Item -Recurse `
  .\skills\manage-skill-versions `
  .\skills\my-new-skill

命名规则：

• 只使用小写字母、数字与连字符；
• 文件夹名必须与 SKILL.md 的 name 完全一致；
• SKILL.md YAML 前置区只放 name 与 description；
• 使用 scripts/、references/、assets/ 承载可复用内容，不要把所有内容塞进 SKILL.md。

3. 在修改前做本地快照

.\scripts\snapshot.ps1

脚本会在 artifacts/snapshots/ 生成 ZIP，内部包含逐文件 SHA-256 清单。敏感文件名、符号链接或超大文件会让创建操作直接失败，而不是悄悄打包。

验证已有快照：

python .\scripts\skill_snapshot.py verify `
  --archive .\artifacts\snapshots\<快照文件>.zip

4. 先恢复到暂存目录

先预演：

.\scripts\restore.ps1 `
  -Archive .\artifacts\snapshots\<快照文件>.zip `
  -DryRun

再恢复到默认的 restored/skills：

.\scripts\restore.ps1 `
  -Archive .\artifacts\snapshots\<快照文件>.zip

默认不会覆盖非空目录。确实需要替换时显式传入 -Force；工具会先创建并校验备份 ZIP，再原子替换目标。恢复脚本拒绝覆盖含 .git 的目录。

用 GitHub 回溯每次修改

第一次发布

先在 GitHub 创建一个空仓库，然后在本目录运行：

git init
git add .
git commit -m "chore: initialize skill lab"
git branch -M main
git remote add origin https://github.com/<你的用户名>/codex-skill-lab.git
git push -u origin main

也可以使用 GitHub CLI 一步创建并推送：

gh repo create codex-skill-lab --public --source . --remote origin --push

日常修改

git switch -c feat/improve-my-skill
# 修改文件
pwsh -NoProfile -File scripts/validate.ps1
git diff
git add skills/my-skill
git commit -m "feat(my-skill): improve validation flow"
git push -u origin feat/improve-my-skill

随后在 GitHub 建 Pull Request，检查 Actions 通过后合并。

标记稳定版本

本项目使用语义化版本：

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

然后在 GitHub 的 Releases → Draft a new release 选择该标签，填写 CHANGELOG.md 中的变更说明。

回看与恢复

查看历史：

git log --oneline --decorate --graph --all
git diff v0.1.0..main -- skills/

只恢复某个 Skill 到旧版本，并把恢复动作作为一个新提交保存：

git restore --source v0.1.0 -- skills/my-skill
git add skills/my-skill
git commit -m "revert(my-skill): restore v0.1.0"
git push

撤销一个已经推送的提交，优先使用：

git revert <commit-id>
git push

git revert 会新增一个可审计的反向提交，比改写公共分支历史更稳妥。

把示例 Skill 安装到 Codex

验证通过后复制到本机 Skills 目录：

$target = Join-Path $env:USERPROFILE '.codex\skills\manage-skill-versions'
Copy-Item -Recurse -Force .\skills\manage-skill-versions $target

重新启动对应的 Codex 会话后，使用类似请求触发它：

使用 $manage-skill-versions 检查我的 Skill 修改，先创建快照，再准备提交说明。

项目结构

.
├── .github/workflows/validate.yml
├── skills/manage-skill-versions/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   └── references/versioning-playbook.md
├── scripts/
│   ├── validate_skills.py
│   ├── skill_snapshot.py
│   ├── validate.ps1
│   ├── snapshot.ps1
│   └── restore.ps1
├── tests/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

安全边界

• Git 历史是版本记录，不等于唯一备份；重要内容仍应保留异地副本。
• 快照工具默认拒绝常见秘密文件名，但它不是完整的 DLP 或秘密扫描服务。
• Pull Request 合并前应查看完整 diff，并确认 GitHub Actions 通过。
• 公共仓库只放你愿意永久公开的内容。

参与贡献

先阅读 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md。安全问题请按 SECURITY.md 私下报告。

许可证

MIT