knowledge-vault/discussions/technology/Codex/4.Skills/0.构建自动化skill-vault.md

1058 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 1
我之前打造的Skill有Codex做的有Claud code做的散落在不同的项目/文件夹里。
我今天与你交流后你推荐:
```md
方案 B一个 `skills-vault` monorepo 管所有 skill
优点:我最推荐。集中管理、统一索引、统一测试、统一发布,适合你将来很多 skill 的情况。
缺点:需要养成“先进入 skills-vault 再提交”的习惯,或者写同步脚本。
```
我准备把这些散落的Skill 收集到这个项目下。
同时我已经建立了远程仓库:`https://git.wantsong.life/wantsong/skills-vault.git`
我还有一个CCPE System`C:\Users\wangq\Documents\Codex\ccpe-system`,也是打造技能和智能体的,
下面是之前与你讨论你与CCPE的本质区别
```md
> 你的这些 Skill 的“定义权”应该在 CCPE System
你说的,我没太懂。
我怎么把`fix-title`的定义放在CCPE里什么叫定义权
我之前的理解:
1. 我需要建立`skills-vault`作为自动化skill集中地。
2. `fix-title`这样的自动化skill源码部分我放在`skills-vault`中
3. 在codex或者cluade code下都需要指定工作路径/项目,我指定`skills-vault`中的位置。这些skill我甚至可以一键安装在其他机器上。
4. 对于专家智能体或者委员会多专家智能体协同的我在CCPE中打造。这些智能体可能会需要一些自动化的skill这些skill安装在`.agents/skills`,源码在`skills-vault`库中。专家智能体你可以了解下张辽,`C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\zhang-liao.prompt.md`
不知道,我理解的对不
---
你的理解基本是对的。前面我说“定义权在 CCPE System”容易误导我换一个更准确的说法
**`fix-title` 这种自动化 Skill 的源码主仓库,就应该是 `skills-vault`。**
不是必须放到 `ccpe-system` 里。
我说的“定义权”,不是指代码、脚本、`SKILL.md` 必须放在 CCPE。它指的是当一个能力变得足够重要需要进入你的 Agentic 系统架构时CCPE 可以记录它的**能力分类、边界、被哪些 Agent/Runtime 调用、权限和评估规则**。
但这可以是“登记/建模”,不是“源码归属”。
你现在的理解可以整理成这个结构:
```txt
skills-vault
fix-title/
SKILL.md
scripts/
tests/
other-automation-skill/
SKILL.md
scripts/
tests/
C:\Users\wangq\.agents\skills
fix-title/
other-automation-skill/
# 本机安装面,从 skills-vault 同步/安装
ccpe-system
agents/lite/zhang-liao.prompt.md
agents/agent-specs/
agents/committees/
runtimes/
model-cards/
skills/
tool/
workflow/
cognitive/
evaluation/
# 专家智能体、委员会、Runtime、模型资产、以及重要 skill 的能力登记/规格
knowledge-vault
diary/
discussions/
prompts/
rules/
# 素材、讨论、知识归档、运行记录
```
以张辽为例,你的理解是准确的。`zhang-liao.prompt.md` 是一个专家智能体,当前是 `CCPE-Lite`,它的定位是深度批判/审稿型专家,不是自动化工具。它可以将来调用一些自动化 Skill比如
```txt
fix-title
markdown-normalizer
source-splitter
citation-checker
report-exporter
```
这些自动化 Skill 的**源码**放在 `skills-vault`**安装版**放在 `.agents/skills`,而张辽这类专家智能体仍然放在 `ccpe-system/agents/lite/` 或之后升级到 `agents/agent-specs/`、`committees/`。
所以更准确的建议是:
1. `skills-vault`:自动化 Skill 的源码主仓库。
2. `.agents/skills`:本机运行安装目录。
3. `ccpe-system`专家智能体、委员会、Runtime、模型卡以及必要时对自动化 Skill 做“架构登记”。
4. `knowledge-vault`:素材、讨论稿、历史记录,不作为长期 Skill 源码库。
什么时候需要在 CCPE 里登记 `fix-title`
只有当它开始被纳入更大的系统时,比如:
```txt
写作工作流 Runtime 需要调用 fix-title
观点讨论整理 Runtime 需要调用 fix-title
某个 Agent Spec 明确依赖 fix-title
委员会运行前需要统一清洗 Markdown 标题
```
那时可以在 CCPE 里建一个轻量文件,例如:
```txt
ccpe-system/skills/tool/fix-title.skill.md
```
它不需要复制全部源码,只记录:
```txt
canonical implementation: skills-vault/fix-title
installed path: C:\Users\wangq\.agents\skills\fix-title
skill type: tool-skill / transformation-skill
used by: ...
authority: may rewrite user-specified markdown file only
validation: heading shift tests pass
```
但如果它只是一个普通自动化小工具,暂时只放 `skills-vault` 就够了。
所以你的 4 点我会这样判定:
1.`skills-vault` 作为自动化 Skill 集中地:对。
2. `fix-title` 源码放 `skills-vault`:对。
3. Codex/Claude Code 工作时指定或安装 `skills-vault` 中的 Skill可迁移到其他机器对。
4. 专家智能体/委员会在 CCPE 打造,自动化 Skill 安装在 `.agents/skills`,源码在 `skills-vault`:对,而且这是我现在更推荐的主结构。
我前面那句可以修正为:
**自动化 Skill 的源码权在 `skills-vault`;系统架构关系和高级 Agentic 资产的定义权在 `ccpe-system`。**
```
---
了解以上内容后,接下来做:
1. 先做这个项目的初始化工作尤其是你与CCPE的区别。
2. 初始化完成后配合我做具体skill的迁移工作。
我已检查到两点:
`C:\Users\wangq\Documents\Codex\skills-vault` 目前基本是空目录,且还不是 git 仓库。
`ccpe-system` 的定位很清楚:它是 Agent / Runtime / Model / Skill 规格与系统架构登记中心,不应该承接自动化 Skill 的源码主仓库职责。
我建议 `skills-vault` 初始化采用这个设计:
**推荐方案:轻量源码主仓库**
目录结构:
```txt
skills-vault/
README.md
AGENTS.md
docs/
architecture.md
migration-guide.md
ccpe-relationship.md
skills/
README.md
templates/
skill/
SKILL.md
README.md
tests/
scripts/
README.md
registry/
skills-index.md
```
职责边界:
```txt
skills-vault
= 自动化 Skill 的源码、脚本、测试、迁移清单、安装说明
C:\Users\wangq\.agents\skills
= 本机运行安装面,从 skills-vault 同步或复制过去
ccpe-system
= 专家智能体、委员会、Runtime、模型卡以及重要自动化 Skill 的架构登记
knowledge-vault
= 素材、讨论、提示词历史、知识归档,不作为 Skill 源码主仓库
```
我会先初始化这些文件,并写清楚:
1. `skills-vault``ccpe-system` 的区别。
2. 什么 Skill 应该迁入 `skills-vault`
3. 什么情况下才需要在 CCPE 中登记。
4. 后续迁移 `fix-title` 这类 Skill 时的标准流程。
5. 远程仓库 `https://git.wantsong.life/wantsong/skills-vault.git` 的 git 初始化配置。
我不会把 CCPE 的 Agent、Runtime、Model Card 复制进来,只会在文档里建立边界和引用关系。
请确认这个初始化设计是否按这个方案执行。确认后我会直接创建文件、初始化 git、配置 remote并给你下一步迁移 Skill 的操作入口。
# 2
**现在和将来都不需要迁移CCPE的任何已有内容。将来迁移的都是CCPE外的自动化skill。**
现在按照你的方案执行进行初始化完成后做第一次远程push。
这些完成后,环境具备,我们再考虑做迁移的工作。
初始化完成,并已完成第一次远程 push。
关键结果:
- 已创建 `skills-vault` 仓库骨架和文档。
- 已明确写入边界:**现在和将来都不迁移 CCPE 既有内容;这里只迁移 CCPE 外部的自动化 Skill**。
- 已初始化 git分支为 `main`
- 已配置远程:`https://git.wantsong.life/wantsong/skills-vault.git`
- 已提交并推送首个 commit`ef50a19 chore: initialize skills vault`
- 验证结果:`main` 已跟踪 `origin/main`,当前工作区干净。
主要入口文件:
- [README.md](C:/Users/wangq/Documents/Codex/skills-vault/README.md)
- [AGENTS.md](C:/Users/wangq/Documents/Codex/skills-vault/AGENTS.md)
- [docs/ccpe-relationship.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/ccpe-relationship.md)
- [docs/migration-guide.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/migration-guide.md)
- [registry/skills-index.md](C:/Users/wangq/Documents/Codex/skills-vault/registry/skills-index.md)
- [templates/skill/SKILL.md](C:/Users/wangq/Documents/Codex/skills-vault/templates/skill/SKILL.md)
有一个环境细节我也处理了Git 因 Windows 用户 SID 差异触发了 `dubious ownership` 检查,我已把当前仓库路径加入 Git `safe.directory`,否则后续 commit/push 会被拦住。
# 3
自动化的skill需要Agentic都能调用安装位置在`C:\Users\wangq\.agents\skills\`其他各Agentic工具的私有skills里都只是个超链接。
刚刚打造了一个`fix-title`的skill位置`C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title\`
这个是我们要移植的第一个。
我觉得有几个:
1. 复制文件夹、代码
2. 修复`.agents\skills\`的引用
3. 测试验证
4. 删除原目录,这个可能有风险,我自己做
你执行完第二步后建立一个test或者相应的文件夹我在里面放一个用于测试的原始文件。
这个只是我的设想,具体需要你进行计划。
我建议这样执行,先不删原目录:
**迁移计划**
1. **迁移源码到 vault**
-`C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title\`
- 复制到 `C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title\`
- 保留现有结构:`SKILL.md`、`agents/openai.yaml`、`ref/`、`scripts/`、`tests/`
- 新增一个简短迁移说明文件,例如 `MIGRATION.md`,记录原路径、迁移日期、删除原目录由你手动处理。
2. **修复 `.agents\skills\fix-title` 引用**
- 当前 `C:\Users\wangq\.agents\skills\fix-title` 是普通目录,不是链接。
- 我建议把它替换为指向:
`C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title`
的 Windows junction / symlink。
- 为避免丢失,我不会删除现有目录,而是先重命名备份为类似:
`C:\Users\wangq\.agents\skills\fix-title.backup-20260613`
- 然后创建链接:
`.agents\skills\fix-title -> skills-vault\skills\fix-title`
3. **建立人工测试入口**
- 在 vault 中创建:
`C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title\manual-test\`
- 放一个说明文件:
`manual-test\README.md`
- 你后续把原始测试 Markdown 文件放进去,我再用 `fix-title` 跑真实验证。
4. **自动化测试验证**
- 运行现有测试:
`python -m unittest discover -s skills/fix-title/tests -v`
- 再验证 `.agents\skills\fix-title` 链接后的路径也能运行同一套测试。
5. **更新 vault registry**
- 更新 `registry/skills-index.md`,登记 `fix-title`
- 来源:`knowledge-vault\skills\fix-title`
- 状态:`migrated`
- 安装路径:`.agents\skills\fix-title`
- CCPE 登记:无
6. **提交并 push**
- 提交迁移结果。
- push 到 `origin/main`
- 原目录 `knowledge-vault\skills\fix-title` 保留,等你确认后自己删除。
需要你确认一个点:第 2 步里,我是否按“备份原 `.agents\skills\fix-title` 普通目录,然后创建 junction 指向 vault”的方式执行
# 4
> **修复 `.agents\skills\fix-title` 引用**
这个我和你的理解不一样,我们有几个路径:
1. `.agents\skills`本地公共Skill的安装路径需要实装
2. `.claude\skills`Claude的Skill用的是超链接我这台机器没有OpenClaw其他机器有`.openclaw/skills`,也是指向了`.agents\skills`
3. Codex的Skills我没搞清楚用哪个直接用`.agents\skills`么?
4. `C:\Users\wangq\Documents\Codex\skills-vault`,源码库路径
**开发、安装过程:**
1. `skills-vault`开发测试skill提交到远程
2. 安装voice-generation skill的脚本示例
```md
git clone https://git.wantsong.life/wantsong/skills-vault/xxx.git
cd voice-generation
# 1. Create the dedicated Conda env from the manifest
conda env create -f environment.yml
# 2. Activate it (do this in every fresh shell)
conda activate voice-gen
# 3. Install the voice-gen package in editable mode
pip install -e .
# 4. (Optional) Install the Claude Code skill globally
bash install-skill.sh # Git Bash on Windows / Linux / macOS
# or
powershell -ExecutionPolicy Bypass -File .\install-skill.ps1 # PowerShell on Windows
```
---
将实装的`.agents\skills` 和 开发分离有个好处是我的skill开发过程中不影响本地已安装的skill技能的使用可以用不同的版本。
---
不知道我说的对不,你怎么看
你说得对,我刚才把“安装面”理解成了“指向源码库的链接”,这不符合你想要的版本隔离。
更合理的结构应是:
```txt
skills-vault
= 源码开发仓库可测试、提交、push
C:\Users\wangq\.agents\skills
= 本机公共 Skill 安装路径,放实装版本
C:\Users\wangq\.claude\skills
= Claude 私有入口,里面用 junction/symlink 指向 .agents\skills
其他机器的 .openclaw\skills
= 同理,指向 .agents\skills
C:\Users\wangq\.codex\skills
= Codex 私有/系统 Skill 目录,不作为这批跨 Agentic Skill 的主安装面
```
我本机核对到:当前 Codex 会看到 `.agents\skills` 里的技能,例如 `fix-title` 已经在本轮可用技能列表中出现;同时 Codex 也有自己的 `C:\Users\wangq\.codex\skills`,里面现在主要是 `.system`、`pdf`、`playwright` 这类 Codex 私有/内置技能。所以对你的目标来说,`.agents\skills` 做公共实装面是合理的,`.codex\skills` 不需要作为这批自动化 Skill 的主路径。
因此 `fix-title` 的迁移计划应改成:
1. 复制源码到 `skills-vault\skills\fix-title`,作为开发主仓库。
2.`skills-vault` 中测试、提交、push。
3. 将稳定版本实装到 `C:\Users\wangq\.agents\skills\fix-title`,这一步是复制/安装,不是链接到源码库。
4. Claude 的 `C:\Users\wangq\.claude\skills\fix-title` 再用 junction 指向 `.agents\skills\fix-title`
5. Codex 暂时不用动 `.codex\skills`,因为当前环境已经能从 `.agents\skills` 发现 `fix-title`
6. 原始目录 `knowledge-vault\skills\fix-title` 保留,最后由你手动删除。
这样开发版和已安装版分离,确实更稳:你可以在 `skills-vault` 里改坏、重构、跑实验,不会影响本机 Agentic 工具正在使用的稳定版。
下一步我会按这个修正版计划执行:先迁移源码到 vault建立 `manual-test` 文件夹让你放测试原始文件,然后跑现有测试;安装面 `.agents\skills\fix-title` 先不替换,等 vault 版测试通过后再做“稳定安装更新”。
已执行到需要你放人工测试文件的位置。
完成内容:
- 已把 `fix-title`
`C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title`
复制到
`C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title`
- 已新增迁移记录:
[MIGRATION.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/fix-title/MIGRATION.md)
- 已创建人工测试入口:
[manual-test](C:/Users/wangq/Documents/Codex/skills-vault/skills/fix-title/manual-test)
- 已更新 registry
[skills-index.md](C:/Users/wangq/Documents/Codex/skills-vault/registry/skills-index.md)
- 已跑 vault 版自动化测试:`4 tests OK`
当前还没有提交和 push因为人工测试还没跑完。
请把一个原始 Markdown 测试文件放到:
```text
C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title\manual-test\
```
建议文件名:
```text
raw-reply.md
```
你放好后告诉我,我会用 `--output` 生成修复结果文件,不覆盖原始文件。
# 5
`C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title\manual-test\raw-reply.md`
我已经放进去了,生成一个新的修复结果文件。
已生成修复结果文件,原始文件未覆盖:
[fixed-reply.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/fix-title/manual-test/fixed-reply.md)
使用命令等价于:
```powershell
python .\skills\fix-title\scripts\fix_markdown_titles.py .\skills\fix-title\manual-test\raw-reply.md --levels 2 --output .\skills\fix-title\manual-test\fixed-reply.md
```
快速检查结果:外层 `# 一、总体评价` 已变成 `### 一、总体评价`。代码块里的 Markdown 标题保持不变,这是脚本的预期行为。
# 6
我看到了结果结果OK。
现在需要补充这个技能的安装脚本。类似于之前的,用户可以根据这个直接进行安装。
```md
git clone https://git.wantsong.life/wantsong/skills-vault/xxx.git
cd voice-generation
# 1. Create the dedicated Conda env from the manifest
conda env create -f environment.yml
# 2. Activate it (do this in every fresh shell)
conda activate voice-gen
# 3. Install the voice-gen package in editable mode
pip install -e .
# 4. (Optional) Install the Claude Code skill globally
bash install-skill.sh # Git Bash on Windows / Linux / macOS
# or
powershell -ExecutionPolicy Bypass -File .\install-skill.ps1 # PowerShell on Windows
```
现在的问题是:
1. 你跑的python是假设我本机有python环境。
2. 实际上我本机及其他机器上都有conda环境我建议我们使用一个统一的conda环境比如`skills-vault`在conda中跑这个脚本。
3. 后续的其他技能也使用`skills-vault`conda环境除非缺失依赖有冲突我们再搞一个新的conda。
4. 我们后续要移植的技能需要conda
所以,简言之:
1. 要不要一个统一的conda
2. 需要为这个fix-skill做一个安装说明和配套的安装脚本。
3. 以便能在新机器上快速安装。
之前有这个`voice-generation`skill是我们后续要迁移的
* 其本地路径在,`D:\AI\ClaudeCode\voice-ge`(名字不太对,迁移后名字应该叫`voice-gen`或者其他正确的)
* 远程仓库将来迁移后,会作废,这里就不提了。
先不执行处理,你对这个的理解和计划?
我的理解是:你现在要的不是“把 `fix-title` 复制进 vault 就完事”,而是把 `skills-vault` 变成可在新机器上复现安装的自动化 Skill 仓库。
我建议采用这个策略。
**1. 要一个统一 Conda 环境**
要。建议仓库级统一环境叫:
```text
skills-vault
```
原因很直接:
- `fix-title` 现在只需要 Python 标准库,但仍然应该走统一入口,避免依赖“系统 Python 是否存在”。
- 后续迁移的 Skill 大概率需要 Python 包、CLI、测试工具。
- 一个统一环境能让安装说明稳定:先装 `skills-vault` 环境,再安装/同步具体 Skill。
- 只有当某个 Skill 依赖冲突明显,比如 CUDA、TTS、特定 Python 版本、重型音频栈,再拆独立环境,例如 `voice-gen`
所以仓库层应该有:
```text
environment.yml
```
初版可以很轻:
```yaml
name: skills-vault
channels:
- conda-forge
dependencies:
- python=3.11
- pip
```
后续按 Skill 增加通用依赖。
**2. `fix-title` 不需要独立 Conda 环境**
`fix-title` 本身不应有自己的 `environment.yml`。它使用仓库级 `skills-vault` 环境即可。
这会形成规则:
```text
默认:使用仓库级 skills-vault conda 环境
例外:依赖冲突或重型运行时才建 Skill 专属环境
```
`voice-gen` 很可能属于例外,因为它可能有 TTS、音频、MiniMax CLI、包安装、环境变量等独立依赖。迁移后再判断名字用 `voice-gen` 还是其他。
**3. 安装模型应该分两层**
仓库级安装:
```powershell
git clone https://git.wantsong.life/wantsong/skills-vault.git
cd skills-vault
conda env create -f environment.yml
conda activate skills-vault
python -m unittest discover -s skills/fix-title/tests -v
```
Skill 安装:
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill fix-title
```
或 Git Bash / Linux / macOS
```bash
bash scripts/install-skill.sh fix-title
```
安装脚本做的事应该是:
1. 检查 `skills/<skill-name>/SKILL.md` 是否存在。
2. 检查目标安装目录,默认:
`C:\Users\wangq\.agents\skills`
3. 如果目标已有同名 Skill
- 默认拒绝覆盖。
- 提供 `-Force``--force` 时,先备份旧目录,再复制新版。
4. 复制 `skills/fix-title``.agents/skills/fix-title`
5. 可选创建 Claude 链接:
`.claude/skills/fix-title -> .agents/skills/fix-title`
6. 不碰 `.codex/skills`,除非未来确认 Codex 需要私有入口。
7. 不删除旧来源目录。
**4. `fix-title` 应该补的文件**
我建议补这些:
```text
environment.yml
scripts/
install-skill.ps1
install-skill.sh
docs/
installation.md
skills/fix-title/
INSTALL.md
```
其中:
- `environment.yml`:仓库级统一 Conda 环境。
- `scripts/install-skill.ps1`Windows 主安装脚本。
- `scripts/install-skill.sh`Git Bash / Linux / macOS 兼容安装脚本。
- `docs/installation.md`:总安装说明。
- `skills/fix-title/INSTALL.md``fix-title` 单 Skill 快速安装说明。
虽然 `skill-creator` 建议 Skill 目录里不要放太多文档,但你这里是“源码仓库 + 可迁移安装资产”,不是最终安装面本身。我认为 `INSTALL.md` 放在 vault 里合理;安装到 `.agents/skills` 时,脚本可以选择复制全部,或后续排除开发文档。初期复制全部也没问题。
**5. 本轮后续执行计划**
如果你确认,我下一步会:
1. 添加仓库级 `environment.yml`
2. 添加 `docs/installation.md`
3. 添加 `scripts/install-skill.ps1``scripts/install-skill.sh`
4. 添加 `skills/fix-title/INSTALL.md`
5.`conda` 检查或创建 `skills-vault` 环境。
6. 用该环境跑 `fix-title` 自动化测试。
7. 执行安装脚本,把 vault 版 `fix-title` 安装到 `.agents\skills\fix-title`,旧版先备份。
8. 如果 `.claude\skills\fix-title` 不存在,则创建 junction 指向 `.agents\skills\fix-title`
9. 再跑安装面测试。
10. 提交并 push。
这里唯一需要你确认的是:安装脚本在目标 `.agents\skills\fix-title` 已存在时,是否默认采用“备份旧目录后覆盖安装”?我建议默认不覆盖,显式传 `-Force` 才备份并覆盖。
# 7
你的建议和计划我都同意,只是补充一点:
将来用户可以默认全部库下的skill安装也可以单独进行某个skill的安装。
有些skill是有条件的条件达不到或者用不上用户可以只安装自己需要的。
根据这个修正,你看计划是否需要调整。
需要小幅调整,而且这个补充很关键。
安装策略应从“安装某个 Skill”升级为“双模式安装”
```text
单 Skill 安装:
scripts/install-skill.ps1 -Skill fix-title
scripts/install-skill.sh fix-title
全部安装:
scripts/install-skill.ps1 -All
scripts/install-skill.sh --all
```
我建议规则这样定:
1. **默认不全量安装**
- 用户不带参数时,脚本显示帮助,不自动安装全部。
- 避免把用户不需要、依赖不满足、还没稳定的 Skill 装进去。
2. **支持显式全量安装**
- `-All` / `--all` 扫描 `skills/*/SKILL.md`
- 只安装 registry 中状态允许安装的 Skill比如 `tested`、`installable`、`installed`。
- 跳过 `candidate`、`deprecated`、`archived`。
3. **registry 增加安装策略字段**
当前 registry 可以扩展为:
```text
install_policy:
- default
- optional
- conditional
- disabled
```
含义:
- `default`:全量安装时默认安装。
- `optional`:只在用户指定时安装。
- `conditional`:需要条件检查通过才安装,比如外部 CLI、API key、独立 conda env。
- `disabled`:不安装。
4. **每个 Skill 可以有可选 manifest**
后续可加:
```text
skills/fix-title/skill.vault.json
```
初期也可以先不做 JSON直接用 registry 表格。等 Skill 多了再结构化。
5. **条件型 Skill 的处理**
比如未来 `voice-gen`
- 可能需要独立 conda env。
- 可能需要 `mmx` CLI。
- 可能需要 API key。
- 全量安装时可以提示 “条件不足,已跳过”。
- 用户单独安装时给出明确缺失项和安装命令。
所以修正后的执行计划是:
1. 建仓库级 `environment.yml`,默认环境 `skills-vault`
2.`docs/installation.md`,说明单装、全装、条件型 Skill。
3.`scripts/install-skill.ps1`
- `-Skill <name>`
- `-All`
- `-Force`
- `-InstallClaudeLink`
4.`scripts/install-skill.sh`
- `<skill-name>`
- `--all`
- `--force`
- `--install-claude-link`
5. 更新 `registry/skills-index.md`,给 `fix-title` 标记为:
- status: `tested`
- install_policy: `default`
6.`fix-title``INSTALL.md`
7.`skills-vault` conda 环境跑测试。
8. 再执行单 Skill 安装验证:`fix-title`。
9. 提交并 push。
这个结构后续扩展更稳:普通 Skill 可以一键全装,复杂 Skill 可以按需单装,条件不满足的不会把整个安装流程拖死。
# 8
同意这个规划。现在按这个计划执行就可以。
只是今天可能没法做新机器的测试验证,我们将来验证。
已按修正版计划完成,并已 push。
完成内容:
- 新增仓库级 Conda 环境文件:[environment.yml](C:/Users/wangq/Documents/Codex/skills-vault/environment.yml)
- 新增总安装说明:[docs/installation.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/installation.md)
- 新增安装脚本:
- [install-skill.ps1](C:/Users/wangq/Documents/Codex/skills-vault/scripts/install-skill.ps1)
- [install-skill.sh](C:/Users/wangq/Documents/Codex/skills-vault/scripts/install-skill.sh)
- `fix-title` 已迁入并补充安装说明:[skills/fix-title/INSTALL.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/fix-title/INSTALL.md)
- registry 已更新为 `fix-title``installed` + `default`
- `.agents\skills\fix-title` 已更新为 vault 版,旧版备份在:
`C:\Users\wangq\.agents\skills\fix-title.backup-20260613235817`
- 已创建 Claude 链接:
`C:\Users\wangq\.claude\skills\fix-title -> C:\Users\wangq\.agents\skills\fix-title`
验证结果:
- vault 源码测试:`4 tests OK`
- `.agents` 安装面测试:`4 tests OK`
- PowerShell 安装脚本帮助路径可运行
- Bash 脚本语法检查通过
- 单 Skill 安装和 `--all` 全量默认安装都用临时目录验证过
- 你的 `raw-reply.md` / `fixed-reply.md` 已被 `.gitignore` 忽略,没有提交
远程已推送:
```text
fa61d46 feat: migrate fix-title skill
```
唯一未完成的是 Conda 环境实际创建:`conda env create -f environment.yml` 在当前 Codex 执行环境里因为 Conda 进度条/solver 输出问题和超时没有创建成功。我保留了 `environment.yml` 和安装说明;新机器验证时我们再专门跑这一步。
# 9
> 当前 Codex 执行环境里因为 Conda 进度条/solver 输出问题和超时没有创建成功
这个是你的权限问题么?
之前在Claude Code Cli下是可以成功的我也需要用管理员模式进入Codex cli么
我其实期望在Conda下把fix-title重新跑一下测试这样环境、路径全部通了。
看这个怎么解决?
不是需要管理员模式。根因更具体:
- Conda base/root 不是 writable不适合写到 `C:\Users\wangq\miniconda3\envs`
- 第一次失败主要是 Conda 在 Codex 这种非交互输出环境里,进度条/tqdm 输出触发了 `OSError: [Errno 22] Invalid argument`
- `--no-plugins` 又禁用了 libmamba但你的 Conda 配置默认 solver 是 `libmamba`,所以第二次也不合适。
我已经用这个方式解决了:
```powershell
C:\Users\wangq\miniconda3\Scripts\conda.exe create -p C:\Users\wangq\.conda\envs\skills-vault python=3.11 pip -y --json --solver classic
```
结果:
- `skills-vault` Conda 环境已成功创建在
`C:\Users\wangq\.conda\envs\skills-vault`
- Python 版本:`Python 3.11.15`
- 用这个 Conda Python 跑 vault 源码测试:`4 tests OK`
- 用这个 Conda Python 跑 `.agents\skills\fix-title` 安装面测试:`4 tests OK`
所以环境、路径、安装面都已经通了。
我也把这个 fallback 命令补进了 [docs/installation.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/installation.md),并已提交推送:
```text
deed276 docs: add conda fallback install command
```
以后在 Codex 里不必管理员启动;如果普通 `conda env create -f environment.yml` 抽风,就用这个显式 `-p ~/.conda/envs/skills-vault --json --solver classic` 的命令。
# 10
我放了一份新的ChatGPT的回复
`C:\Users\wangq\Documents\Codex\skills-vault\skills\fix-title\manual-test\raw-reply2.md`
与之前的`raw-reply.md`的区别是本次只需要深入一层这次ChatGPT的回复已经是两个"##"那么你调用fix-title为每节标题增加一个"#"。结果放在同目录下。
注意,应该是:
1. 实装了`.agent/skills`,用这个公共技能,而不是本地源码
2. 用Conda环境来跑
# 11
很好,本地测试完成,可以提交并同步远程,这样我们环境构建完毕,并移植了第一个技能。
远程已同步确认:`git push` 返回 `Everything up-to-date`
当前仓库状态:
- `main``origin/main` 一致。
- 最新提交是 `deed276 docs: add conda fallback install command`
- 本地测试文件 `raw-reply*.md` / `fixed-reply*.md` 都被 `.gitignore` 忽略,没有进入仓库。
到这里,`skills-vault` 环境构建完成,`fix-title` 作为第一个 Skill 已迁移、安装、Conda 测试、本地实装验证、远程同步完成。
# 12
`D:\AI\ClaudeCode\voice-ge` 是第二个Skill的本地路径我需要你
1. 迁移到skill-vault下重命名为`voice-generation`
2. 检查相应的代码、说明等
3. 调整`.agent/skills/`的实装部分
4. 到测试前暂停
已按要求停在测试前,没有运行 pytest、没有调用 `voice-gen`、没有调用 `mmx`
已完成:
- 已从 `D:\AI\ClaudeCode\voice-ge` 迁移到:
[skills/voice-generation](C:/Users/wangq/Documents/Codex/skills-vault/skills/voice-generation)
- vault 名称改为 `voice-generation`
- Python 包名、模块名、命令保留为 `voice-gen` / `voice_gen`,避免破坏 CLI。
- 已清理不适合迁移的内容:
- `.git/`
- `.pytest_cache/`
- `output/`
- `plan.md`
- `.claude/settings.local.json`
- 旧的独立仓库安装脚本
- 旧 handoff 文档
- 已新增/调整:
- [SKILL.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/voice-generation/SKILL.md)
- [README.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/voice-generation/README.md)
- [INSTALL.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/voice-generation/INSTALL.md)
- [MIGRATION.md](C:/Users/wangq/Documents/Codex/skills-vault/skills/voice-generation/MIGRATION.md)
- 已更新 registry
- `voice-generation`
- status: `migrated`
- install policy: `conditional`
- installed path: `C:\Users\wangq\.agents\skills\voice-generation`
安装面已调整:
-`.agents\skills\voice-gen` 已备份到:
`C:\Users\wangq\.agents\skills\voice-gen.backup-20260615054951`
-`.claude\skills\voice-gen` 已备份到:
`C:\Users\wangq\.claude\skills\voice-gen.backup-20260615054951`
- 新公共安装面:
`C:\Users\wangq\.agents\skills\voice-generation`
- 新 Claude 链接:
`C:\Users\wangq\.claude\skills\voice-generation -> C:\Users\wangq\.agents\skills\voice-generation`
当前 Git 状态还有未提交内容:
```text
M registry/skills-index.md
?? skills/voice-generation/
```
下一步测试建议从这里开始:
```powershell
conda activate voice-gen
pip install -e .\skills\voice-generation
python -m pytest .\skills\voice-generation\tests
```
Smoke 测试会触发真实 MiniMax/mmx 调用和额度消耗,暂时不跑。
# 13
按照之前的讨论skills-vault 将会使用统一的conda除非确实存在依赖冲突再开新环境。
现在conda依然使用旧的环境新环境没有安装依赖相应的脚本没有调整对吧
下一步测试需要用统一的conda。
对,你指出的问题成立。刚才迁移后确实还残留了旧项目的独立 `voice-gen` Conda 环境方案;这和我们定的策略不一致。
我已经修正到统一环境方案,仍然停在测试前:
-`environment.yml` 已加入 `pytest>=7.0`
- 删除了 `skills/voice-generation/environment.yml`,避免继续引导使用独立 `voice-gen` 环境。
- `voice-generation``README.md`、`INSTALL.md`、`MIGRATION.md` 已改为使用统一 `skills-vault` Conda 环境。
- 已在统一环境 `C:\Users\wangq\.conda\envs\skills-vault` 中安装:
- `pytest 9.0.3`
- `voice-gen 0.1.0`editable 指向 `C:\Users\wangq\Documents\Codex\skills-vault\skills\voice-generation`
- `.agents\skills\voice-generation` 安装面已同步新的说明和迁移记录,并删除了旧的 per-skill `environment.yml`
下一步测试应使用:
```powershell
C:\Users\wangq\.conda\envs\skills-vault\python.exe -m pytest .\skills\voice-generation\tests
```
或先激活:
```powershell
conda activate skills-vault
python -m pytest .\skills\voice-generation\tests
```
我还没有运行测试,也没有调用 `voice-gen``mmx`。当前仍停在测试前。
# 14
你的测试是指单元测试么?那单元测试,你先跑一下吧。
我的测试,是在真实环境下跑一个生成语音文件。
单元测试做完,我们开始真实环境的测试。
单元测试已跑完,结果通过:
```text
37 passed, 1 skipped
```
使用的是统一 Conda 环境:
```text
C:\Users\wangq\.conda\envs\skills-vault\python.exe
```
实际命令是:
```powershell
C:\Users\wangq\.conda\envs\skills-vault\python.exe -m pytest .\skills\voice-generation\tests --basetemp .\tmp\pytest-voice-generation
```
第一次失败不是代码问题,是 pytest 默认临时目录 `C:\Users\wangq\AppData\Local\Temp\pytest-of-wangq` 权限拒绝;改用仓库内 `--basetemp` 后全部通过。`test_smoke` 被跳过,因为没有加 `--run-smoke`,所以没有真实调用 MiniMax也没有消耗额度。
真实环境测试目前卡在 `mmx` 认证:
```text
cmd /c mmx auth status
authenticated: false
hint: Run: mmx auth login
```
另外 PowerShell 直接跑 `mmx` 会命中 `mmx.ps1` 并被执行策略拦截,所以后续真实测试建议用:
```powershell
cmd /c mmx auth login
```
你先完成 `mmx auth login`,然后我继续跑真实语音生成测试。当前我已把 `INSTALL.md``MIGRATION.md` 更新为单元测试通过、smoke 测试因未认证阻塞,并同步到了 `.agents\skills\voice-generation`
# 15
这个`mmx auth login` 之前已经登录过的之前在Claude code中打造技能时完整测试过了。
当时的测试路径:`D:\Mine\口播2`
已经有一个可用的音色`BroTsong-Saying`在`voices.json``scripts/`下也有一个测试用的md文件`hello.md`
因为Minimax的音色生成没有删除功能上传一次其库里就会多一份语音文件。当时测试已经生成了好几个删不掉的文件了。
我们这次直接跑生成语音就行,按照规则生成语音应该放在`D:\Mine\口播2\output`下
这样不知道OK不
可以跑,但这次真实生成没有通过,失败点已经定位清楚了。
我执行了:
```powershell
C:\Users\wangq\.conda\envs\skills-vault\Scripts\voice-gen.exe gen --voice BroTsong-Saying scripts --out output --format mp3
```
工作目录是:
```text
D:\Mine\口播2
```
结果失败:
```text
done: 0 ok, 1 failed
hello.md: API error: voice id not exist
```
我进一步确认了服务器上确实有这个上传文件:
```json
{
"file_id": 407449867293232,
"filename": "BroTsong-Saying.m4a",
"purpose": "voice_clone"
}
```
但无论用友好名:
```text
--voice BroTsong-Saying
```
还是直接用 file_id
```text
--voice 407449867293232
```
MiniMax 都返回:
```text
voice id not exist
```
结论:当前账号下有 `voice_clone` 源文件,但它没有成功注册成可用于合成的 `voice_id`。这不是 Conda、路径、安装面或 `voice-gen` CLI 没跑起来的问题,而是 MiniMax 侧“上传文件”和“可用 voice_id”之间还缺一步注册。
我建议下一步不要重新上传音频。更稳的是:用现有 `file_id=407449867293232` 注册一次 `voice_id=BroTsong-Saying`,不产生新的上传文件。这个动作仍然会改变 MiniMax 服务器状态,所以我需要你确认后再做。
# 16
我修改了voice_id 为 `BroTsong-2026-06-10`,你再重新试一下
OK这次真实环境测试已经跑通并已提交推送。
结果:
- 使用统一 Conda 环境里的 `voice-gen`
`C:\Users\wangq\.conda\envs\skills-vault\Scripts\voice-gen.exe`
- 工作目录:
`D:\Mine\口播2`
- 使用已有 voice
`BroTsong-2026-06-10`
- 输入:
`D:\Mine\口播2\scripts\hello.md`
- 输出:
`D:\Mine\口播2\output\hello.mp3`
- 最终运行成功:
```text
OK hello.md -> output\hello.mp3
done: 1 ok, 0 failed
```
中间发现并修了一个 Windows 控制台编码问题:原 CLI 成功后打印 `✓` / `→`,在 GBK 控制台下会导致返回失败。我已改成 ASCII 输出 `OK ... -> ...` / `ERROR ...`,单元测试也重新通过:
```text
37 passed, 1 skipped
```
已提交并推送:
```text
c3c56b9 feat: migrate voice-generation skill
```
当前仓库 `main` 已与 `origin/main` 同步。
# 17
现在可以删掉`voice-gen`原来旧的conda环境
提交并同步到远程库,这样第二个技能也迁移完毕。
已完成。
- 旧独立 Conda 环境 `voice-gen` 已删除:
`C:\Users\wangq\miniconda3\envs\voice-gen`
- 已确认环境列表里只剩统一环境:
`skills-vault -> C:\Users\wangq\.conda\envs\skills-vault`
- 已确认 `voice-gen` 包仍以 editable 方式安装在统一环境中,指向:
`C:\Users\wangq\Documents\Codex\skills-vault\skills\voice-generation`
- 已把清理记录写入并同步到 `skills/voice-generation/MIGRATION.md`
- 已提交并推送远程:
```text
e69a195 docs: record voice-gen env cleanup
```
当前 `main``origin/main` 同步。第二个技能 `voice-generation` 迁移完成。