knowledge-vault/discussions/technology/Codex/4.Skills/fix文档标题.md

1

我想开发一个修复Markdown文档标题的技能。 这个技能不但可以在Codex下使用，也可以被Claude code/OpenClaw等进行调用。

在我本机上公共的Skill位置在：C:\Users\wangq\.agents\skills；其他都是调用的这个位置的技能。 技能的开发路径位置在C:\Users\wangq\Documents\Codex\knowledge-vault\skills\，下面建立一个文件夹比如fix-title。

具体来说，我与ChatGPT交流后，它的回复，我复制下来，标题往往是错乱的。这里有个示例，放的是ChatGPT的回复原始内容：C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title\ref\erro-example.md。

由于我有保留讨论稿记录的习惯，我需要把GPT的回复放到我的记录讨论稿中，每个回合以大标题“# 数字”标记，GPT的回复放在“## GPT”下，这里有我整理后的样例： C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title\ref\recorder-example.md

我若直接放回复内容，标题是对不上的，我需要手动在每个标题上增加“##”，以便放在## GPT下，作为其内容。

这个fix-title就是，我告诉它一个文件路径——ChatGPT的原始回复，告诉它增加几级，加几个“##”，默认是2个，有时候可能也需要三个或一个“#”不等。它帮我直接修改这个原始回复的标题。

实现用什么技术，正则表达式还是提示词工程，这个你自己判断。

你有什么问题，可以先提出。

已完成 fix-title 技能开发，并复制到公共技能目录：

• 开发目录：skills/fix-title/SKILL.md
• 公共目录：C:\Users\wangq\.agents\skills\fix-title
• 核心脚本：fix_markdown_titles.py
• 索引已更新：indexes/skill-index.md

用法示例：

python C:\Users\wangq\.agents\skills\fix-title\scripts\fix_markdown_titles.py "C:\path\reply.md"
python C:\Users\wangq\.agents\skills\fix-title\scripts\fix_markdown_titles.py "C:\path\reply.md" --levels 3
python C:\Users\wangq\.agents\skills\fix-title\scripts\fix_markdown_titles.py "C:\path\reply.md" --dry-run

默认 --levels 2，只处理 Markdown ATX 标题行，跳过 fenced code block、引用行和缩进代码。验证已通过：

python -m unittest discover ... -> Ran 4 tests, OK
quick_validate.py ... -> Skill is valid!
公共目录版本 quick_validate.py -> Skill is valid!

另外，仓库本来就有大量无关未提交变更；我只改了 skills/fix-title/、skills/README.md、indexes/skill-index.md，没有碰其他文件。

2

这个技能我怎么调用？ 我们做个测试。

按照默认的条件修复标题： C:\Users\wangq\Documents\Codex\knowledge-vault\diary\2026\2026-06\gpt回复.md

调用有两种方式：

1. 直接对 Agent 说：使用 fix-title 修复这个 Markdown 文件标题，默认级数
2. 直接跑脚本：

python C:\Users\wangq\.agents\skills\fix-title\scripts\fix_markdown_titles.py "C:\Users\wangq\Documents\Codex\knowledge-vault\diary\2026\2026-06\gpt回复.md"

我已经按默认条件执行了，也就是 --levels 2 原地修改：

# 标题  -> ### 标题
## 标题 -> #### 标题

验证结果里普通标题已经下沉，例如：

13  ### 一、必须改的几个小 bug / 强冲突
15  #### 1. “两种封装策略”要改成“三种封装策略”
216 ### 二、我认为还缺的纲领级内容
453 ### 六、总评

文件里仍有 ## 文档边界，我查了上下文，它们在 fenced code block 示例里，脚本按规则没有改，这是正确行为。

目标文件当前是 Git 未跟踪文件：?? diary/2026/2026-06/gpt回复.md。

3

我在远程库中搭建了一个仓库 skills-vault.git

我将来会有很多类似这样的skills，我要放在远程仓库里，可以把C:\Users\wangq\Documents\Codex\knowledge-vault\skills\fix-title 提交到https://git.wantsong.life/wantsong/skills-vault.git 一份么？

即，远程仓库是一个，本地不同的路径（不同skills）都能提交到这个远程仓库下。而本地仓库的路径，也可以提交到不同的远程仓库里。

形如：

knowledge-vault ---> 远程库 knowledge-vault
  |-- skills
     | --- skill-a  ---> 远程库 skills-vault

...

Claude-workspace
  | -- skill-project-b  ---> 远程库 skills-vault

这个看上去有些复杂。

简单点的，本地skills 源码库和远程库一一对应，这样我需要在文件路径上统一。因为有些skill，是我用Cluade打造的。

指令：

1. 第一种情况，是否能支持？
2. 你建议哪一种，或者哪一种有什么优劣。

先回答问题，不要做任何实际操作。

可以支持，但我不建议把它做成“任意本地子目录直接 push 到同一个远程 repo”的常态流程。

1. 第一种情况是否能支持？

能，Git 技术上支持几种做法：

• 一个本地目录可以有自己的 Git 仓库，并 push 到 skills-vault.git。
• 同一个远程仓库可以被多个本地 clone 推送。
• knowledge-vault/skills/fix-title 也可以变成一个嵌套 Git 仓库、submodule、subtree，或者通过脚本同步到另一个仓库后提交。
• 一个本地仓库也可以配置多个 remote，推到不同远程。

但这里的难点是：skills-vault.git 如果是一个“多个 skill 的总仓库”，那么每次提交最好发生在这个总仓库的完整工作树里，例如：

skills-vault/
  fix-title/
  another-skill/
  claude-made-skill/

如果你让 knowledge-vault/skills/fix-title 自己直接作为一个 Git repo 推到 skills-vault.git，它看到的仓库根目录就是 fix-title，不是 skills-vault/fix-title。这会和“一个远程仓库存很多 skill 子目录”的模型冲突，除非你做 subtree/filter/sync 这类额外流程。

2. 我建议哪一种？

我建议用一个独立的本地规范源码库，一一对应远程 skills-vault.git：

C:\Users\wangq\Documents\Codex\skills-vault\
  fix-title\
  skill-a\
  skill-b\

远程：

https://git.wantsong.life/wantsong/skills-vault.git

然后：

skills-vault/              # skill 源码 canonical
  fix-title/

C:\Users\wangq\.agents\skills\
  fix-title/               # 安装/运行位置，可由复制或同步生成

knowledge-vault/skills/
  fix-title/               # 如果需要，可作为项目侧副本或引用，不作为主源码

这样边界最清楚：

• skills-vault 管 skill 源码和版本。
• .agents\skills 管本机可调用安装面。
• knowledge-vault 管知识库自己的内容，不被技能源码发布流程绑死。
• Claude 做出来的 skill，最终也归档/迁移到 skills-vault/<skill-name>。

各方案优劣

方案 A：每个 skill 一个独立远程仓库
优点：最简单、边界极清楚。
缺点：skill 多了以后仓库太碎，管理、同步、搜索都麻烦。

方案 B：一个 skills-vault monorepo 管所有 skill
优点：我最推荐。集中管理、统一索引、统一测试、统一发布，适合你将来很多 skill 的情况。
缺点：需要养成“先进入 skills-vault 再提交”的习惯，或者写同步脚本。

方案 C：在 knowledge-vault/skills/fix-title 下做嵌套 Git/submodule
优点：看起来可以在原地开发。
缺点：Git 心智负担高，父仓库会看到嵌套仓库或 gitlink；提交、移动、同步时容易混乱。我不建议作为默认方案。

方案 D：本地到处开发，再用脚本同步到 skills-vault
优点：符合“Claude/Codex 在不同工作区生产 skill”的现实。
缺点：需要一个明确的 publish/sync 流程，否则容易忘记哪个版本是准的。

我的建议是：用方案 B 作为主结构，方案 D 作为辅助流程。也就是 skills-vault 是唯一规范源码库；其他地方产生的 skill，成熟后同步进去。