Skills on KnightLi的博客

市面上主流 AI PPT 工具大盘点：自动生成、网页演示、PPTX 和图像路线怎么选

Mon, 18 May 2026 22:29:43 +0800

AI 做 PPT 已经不只是“输入标题，套一个模板”。在 Claude Code、Codex、Cursor 这类 AI 编程环境里，PPT 生成正在变成一组可安装、可复用的 Agent Skill：有的输出网页演示，有的生成真正可编辑的 .pptx，有的直接用图像模型把每页做成视觉稿，还有的通过 MCP 让 AI 操作 PowerPoint 文件。

这次整理了一批主流 PPT 相关 Skill。真正有价值的地方不只是榜单，而是把这类工具按交付形态拆开来看。选工具前，先问一句：最终交付物到底要给谁改、在哪里播放、是否需要继续协作？

几条路线

1. HTML 网页演示

代表项目包括 frontend-slides、guizang-ppt-skill、html-ppt-skill。

这条路线的优势是视觉表现力强。CSS 动画、Canvas、WebGL、响应式布局都能用，浏览器打开即可演示，适合技术分享、产品发布、Demo Day 和个人风格强烈的演讲。

代价也很明确：交付后不太适合让客户逐字改。客户如果拿到的是 HTML，而不是 PowerPoint 文件，后续修改往往还要回到生成流程。

如果只看 HTML 演示，frontend-slides 更像高星通用入口，guizang-ppt-skill 强在审美约束和主题风格，html-ppt-skill 则胜在主题数量、布局数量和演讲者模式。

2. 原生 PPTX

代表项目包括 mckinsey-pptx、ppt-agent-skills、claude-office-skills 和 ppt-master。

这是商业交付最稳的路线。只要客户要求“能在 PowerPoint 里改字、改图、套公司模板”，最终就要落到 .pptx。

其中 ppt-master 很值得单独关注。它的思路是先让 LLM 生成 SVG，再转成 PowerPoint 原生 DrawingML 对象，目标是让文字框、形状、图表都能在 PPTX 里继续编辑。它还支持从 PDF、DOCX、URL、Markdown 生成 PPTX，并能做模板复刻、动画、旁白和本地预览。

这条路线适合咨询交付、公司汇报、白皮书演示、长报告压缩成 PPT 等场景。缺点是视觉上限通常受 PowerPoint 本身限制，复杂效果不如 HTML 或图像路线自由。

3. AI 图像驱动

代表项目包括 NanoBanana-PPT-Skills、gpt_image_2_skill 和 ppt-image-first。

这条路线先把每一页当成视觉图来生成，再把图片放进 PPTX 或其它容器里。优点是完成度高，尤其适合封面、社交媒体图、视觉提案、传播型内容。

问题是可编辑性差。页面本质上是一张图，后面要改一个标题、换一段文案、挪一个图标，可能就要重新生成。它适合“看起来要好”，不适合“客户要反复改”。

4. MCP / 协议层

代表项目包括 Office-PowerPoint-MCP-Server、PPTAgent。

这类工具不一定直接生成完整 PPT，而是给 AI 一个操作 PowerPoint 的接口。接入 MCP 后，模型可以读、改、写 .pptx 文件。

这条路线适合已经有 PPT 文件、需要 AI 辅助修改的工作流。比如批量改格式、根据反馈重排页面、让模型检查每页是否符合目标。PPTAgent 强调反思式生成，也就是每生成一页后再回头检查，这个方向对减少“AI PPT 很粗糙”的问题有启发。

5. 综合设计平台

代表项目包括 open-design 和 docsagent。

这类项目已经超出 PPT 生成本身。open-design 更像本地优先的设计平台，可以生成原型、slides、images、videos，并支持多种导出格式。docsagent 不是 PPT 工具，但能索引和对话本地文档，适合作为 PPT 生成前的资料整理层。

如果你的需求不是单次做 PPT，而是从资料、设计、原型到交付的一整套流程，这类平台更值得看。

Skill 元信息

Star 数来自原文 2026-05-15 的抓取结果，只适合作为热度参考，实际使用前建议再打开仓库确认维护状态、README 和 LICENSE。

Skill	作者	链接地址	Star	语言	路线
frontend-slides	@zarazhangrui	GitHub: zarazhangrui/frontend-slides	17,530	Shell	HTML 网页演示
guizang-ppt-skill	@op7418（歸藏）	站内文章: guizang-ppt-skill GitHub: op7418/guizang-ppt-skill	8,832	HTML	HTML 网页演示
html-ppt-skill	@lewislulu	GitHub: lewislulu/html-ppt-skill	3,834	HTML/CSS/JS	HTML 网页演示
mckinsey-pptx	@seulee26	GitHub: seulee26/mckinsey-pptx	426	Python	原生 PPTX
ppt-agent-skills	@sunbigfly	GitHub: sunbigfly/ppt-agent-skills	714	Python	原生 PPTX
claude-office-skills	@tfriedel	GitHub: tfriedel/claude-office-skills	631	Python	原生 PPTX
ppt-master	@hugohe3	GitHub: hugohe3/ppt-master	16,626	Python	原生 PPTX
NanoBanana-PPT-Skills	@op7418（歸藏）	GitHub: op7418/NanoBanana-PPT-Skills	2,668	Python	AI 图像驱动
gpt_image_2_skill	@wuyoscar	GitHub: wuyoscar/gpt_image_2_skill	2,102	Python	AI 图像驱动
ppt-image-first	@NyxTides	GitHub: NyxTides/ppt-image-first	799	Python	AI 图像驱动
Office-PowerPoint-MCP-Server	@GongRzhe	GitHub: GongRzhe/Office-PowerPoint-MCP-Server	1,708	Python	MCP / 协议层
PPTAgent	@icip-cas	GitHub: icip-cas/PPTAgent	4,354	Python	MCP / 协议层
open-design	@nexu-io	站内文章: open-design GitHub: nexu-io/open-design	40,822	TypeScript	综合设计平台
docsagent	@docsagent	GitHub: docsagent/docsagent	687	TypeScript	综合设计平台

选型可以这样判断

如果客户要继续编辑，优先看原生 PPTX 路线，尤其是 ppt-master、mckinsey-pptx、ppt-agent-skills。

如果是自己演讲，且视觉表现比后续编辑更重要，优先看 HTML 路线，尤其是 frontend-slides、guizang-ppt-skill、html-ppt-skill。

如果目标是海报感、封面感、传播图，优先看图像路线，比如 ppt-image-first、gpt_image_2_skill、NanoBanana-PPT-Skills。

如果已经有 PPT 文件，只想让 AI 帮你读、改、重排，可以看 MCP 路线。

如果是学术、营销、翻译、长报告压缩这类明确场景，也可以继续找垂直 Skill，而不是拿通用 PPT 生成器硬做。

最后要注意的事

开源项目不能只看 Star。真正使用前还要确认三件事：

LICENSE 是否允许你的使用方式。
生成物是否满足交付要求，尤其是可编辑性。
成本是否可接受，包括模型调用、图像生成、大上下文模型和可能的云服务费用。

这类工具变化很快，Star 数会变，项目维护状态也会变。但选型逻辑相对稳定：先确定交付形态，再看具体工具。PPT 是给人讲、给人改、还是给人看，这三个答案往往会把选择范围直接缩小一大半。

Claude Code 24 个使用技巧：计划模式、回滚、CLAUDE.md、Skills、Agents 和插件

Fri, 08 May 2026 08:54:14 +0800

Claude Code 不只是一个聊天框。它更像一个能进入项目目录、读写文件、执行命令、维护上下文的编程 Agent。

如果只是把需求丢进去让它生成代码，很快会遇到几个问题：计划不够清楚、权限反复确认、上下文越来越长、生成结果不满意、不知道怎么回滚，也不知道怎么把项目规则长期保存下来。

下面整理一组常用操作，适合刚开始使用 Claude Code 的开发者快速建立工作流。

先在项目目录启动

Claude Code 最好在项目目录里启动，而不是随便打开一个终端就开始用。

可以先创建一个文件夹作为项目目录，进入目录后打开命令行，再启动 Claude Code：

claude

首次进入项目时，如果 Claude Code 询问是否信任当前文件夹，确认后再继续。这样它才能围绕当前项目读取文件、创建文件和执行后续操作。

一个简单的练习方式是让它创建一个摄影师个人网站。这个任务足够直观：能看到页面效果，也能练习文件生成、命令执行、回滚和后续重构。

计划模式先把方向想清楚

Claude Code 在面对较复杂任务时会进入计划模式。计划模式的作用是先讨论需求、拆解步骤，再让用户决定是否批准执行。

当它给出计划后，通常会出现几类选择：

批准计划，并允许后续自动使用编辑工具。
批准计划，但后续编辑仍然需要手动确认。
暂停执行，继续和 Claude Code 讨论计划。

如果任务比较明确，可以批准计划并继续。如果任务还不清楚，建议先让它继续补充方案，比如页面风格、技术栈、目录结构、交互效果和验收标准。

计划模式的好处是减少返工。直接让 Agent 动手，可能很快生成一堆文件；但如果方向错了，后面越改越乱。

用 Shift + Tab 切换模式

在 Claude Code 中，可以用 Shift + Tab 在不同工作模式之间切换。常见用途是进入计划模式，或者切换到自动同意编辑工具的模式。

建议的习惯是：

新项目、新功能、大改动：先进入计划模式。
小改动、明确修复：可以直接执行。
涉及删除、批量替换、安装依赖：保持人工确认。

计划模式下，Claude Code 可能会主动询问项目细节。可以用方向键选择选项，用回车确认。提交反馈后，它会根据你的选择更新计划。

权限确认不要一律放开

Claude Code 执行命令、编辑文件或启动程序时，可能会申请权限。

常见选择包括：

只同意本次使用。
在当前会话中以后都同意同类命令。
拒绝或暂停。

如果只是启动本地页面、运行开发服务器、查看文件，可以根据需要允许。但不要为了省事长期使用“自动同意所有权限”的启动方式。

全自动权限适合非常确定、风险很低、项目已经有 Git 备份的场景。日常使用中，涉及删除文件、覆盖目录、安装依赖、联网、提交代码、执行脚本时，最好保留人工确认。

用终端模式执行本地命令

Claude Code 里可以进入终端命令模式，直接执行一些本地命令。

例如页面生成后，可以用系统命令打开 HTML 文件：

`1`	`start index.html`

这里的 start 是 Windows 下打开文件的命令，后面接文件名。这样可以快速查看生成页面，而不用手动去资源管理器里找文件。

终端模式适合执行这些轻量操作：

打开生成的页面。
查看目录内容。
启动本地开发服务器。
运行测试或构建命令。

但高风险命令仍然要谨慎，比如递归删除、移动目录、批量覆盖和修改系统环境。

回滚：结果不满意时及时退回

如果 Claude Code 做出的页面或代码不是你想要的，而且越改越乱，就应该及时回滚。

回滚功能可以把对话或代码退回到某个节点。常见选项包括：

同时回滚代码和对话。
只回滚对话。
只回滚代码。
把某个节点之前的内容压缩成摘要。
取消操作。

更推荐在明显走偏时选择“同时回滚代码和对话”。这样可以让上下文和文件状态一起回到较干净的位置。

需要注意：Claude Code 的回滚通常只能覆盖它通过内置工具创建或修改的文件。如果文件是通过外部命令生成的，未必能完整回滚。因此重要项目仍然要配合 Git 使用。

长提示词用编辑器写

复杂需求不要全挤在一行输入框里。

如果系统支持在文本编辑器中编辑长提示词，可以打开编辑器，把需求写完整后保存，再发送给 Claude Code。

长提示词里建议写清楚：

目标是什么。
使用什么技术栈。
不要做什么。
需要保留哪些文件。
完成后如何验证。
页面或功能的验收标准。

例如让 Claude Code 把一个普通 HTML 页面重构成更现代的技术栈时，不要只写“重构一下”。可以说明希望使用组件化结构、保留视觉内容、增加响应式布局，并要求它运行构建检查。

退出后用历史恢复会话

如果中途需要退出 Claude Code，可以正常退出。之后回到同一个项目目录，再次启动：

claude

如果发现前面的记录没有直接显示，可以使用历史相关命令查看最近会话，并加载之前的会话。

这个功能适合中断后继续工作。不过不要把会话历史当成唯一记忆。项目规则、技术栈、常用命令和注意事项，最好写进项目文件里。

用 CLAUDE.md 保存项目规则

CLAUDE.md 是 Claude Code 很重要的记忆文件。它通常放在项目根目录，用来告诉 Claude Code 项目规则、技术栈、目录结构和协作约束。

可以让 Claude Code 初始化这个文件：

/init

CLAUDE.md 适合记录：

项目目标。
技术栈。
常用启动、测试、构建命令。
目录说明。
代码风格。
不允许执行的操作。
提交和部署规则。

每次对话时，Claude Code 会把这类规则作为上下文的一部分使用。你可以把它理解成“项目说明书”。

一个简单验证方式是：在 CLAUDE.md 里加入一条明显规则，然后再向 Claude Code 提问。如果回答遵循了这条规则，就说明它确实读到了项目记忆。

用 @ 引用文件

在输入框中使用 @，可以选择文件或 Agent，把指定内容加入当前对话上下文。

这适合几类场景：

让 Claude Code 阅读某个配置文件。
让它修改某个指定页面。
让它根据 CLAUDE.md 或其他文档继续工作。
明确告诉它“只看这个文件，不要猜项目结构”。

相比把文件内容复制到输入框里，@ 引用更清晰，也更不容易漏内容。

查看和压缩上下文

长时间对话后，上下文会越来越大。上下文太长时，模型可能变慢，也可能开始忽略早期细节。

可以使用上下文查看命令了解当前占用情况：

`1`	`/context`

如果上下文已经很长，可以压缩历史：

`1`	`/compact`

如果压缩后效果仍然不好，可以考虑清空当前上下文：

/clear

清空上下文后，Claude Code 仍然可以通过项目文件、CLAUDE.md 和当前目录重新理解一部分项目情况，但不会保留完整对话历史。

实用建议是：一个任务完成后就开新会话；项目级规则写进 CLAUDE.md；临时讨论不要无限堆在一个聊天里。

Skills：把固定流程做成说明书

Skills 可以理解为 Claude Code 的工作说明书。它不是一次性提示词，而是一套可复用的任务流程。

例如你经常要生成周报，就可以创建一个周报 Skill，里面写清楚：

输入需要哪些信息。
输出格式是什么。
语气和结构怎么控制。
哪些内容必须保留。
哪些内容不能编造。

Skills 通常由 name、description 和具体指令组成。安装到全局 Skills 目录后，Claude Code 在遇到相关任务时可以识别并加载。

这适合处理重复工作：

周报。
代码审查模板。
文档整理。
图片批处理。
固定格式文章。
项目初始化流程。

如果你发现自己反复复制同一段提示词，就可以考虑把它做成 Skill。

Agents：把子任务交给独立助手

Agents 和 Skills 不一样。

Skill 更像说明书，告诉 Claude Code 怎么做某类任务；Agent 更像一个独立助手，可以在当前主会话之外执行任务，完成后把结果返回。

Agents 的价值在于隔离上下文。比如做代码巡检时，可以创建一个只读 Agent，让它只读取项目并输出报告，不直接修改文件。这样不会污染主会话，也能降低误操作风险。

创建 Agent 时通常要考虑：

是项目级 Agent，还是用户级 Agent。
是否需要 Claude Code 帮你生成配置。
允许哪些工具权限。
使用哪个模型。
是否保存记忆。
Agent 的提示词是否足够明确。

对于代码巡检类 Agent，建议只给读取权限，不给写入权限。先让它输出报告，再由主会话决定是否修改代码。

插件：打包 Skills、Agents、MCP 和 Hooks

插件可以理解为更完整的能力包。它可能同时包含：

Skills
Agents
MCP
Hooks

相比单独安装一个 Skill，插件更适合成套能力。例如前端设计插件可能会把页面审美、布局规则、组件习惯和相关 Agent 一起打包。

安装插件时通常会有几个位置选项：

如果是个人常用能力，可以放在用户目录；如果是团队项目约定，可以放进项目目录；如果只是临时测试，放本地项目目录更稳。

插件能明显改善特定任务效果

在前端页面生成这类任务里，插件往往比裸提示词更稳定。

例如同样是“制作一个摄影师个人网页”，只用普通提示词可能生成一个能看的页面；如果明确使用前端设计插件，页面结构、视觉层次、间距、配色和整体完成度通常会更好。

这并不意味着插件能替代人工审美。更合理的用法是：先让插件生成一个更好的初稿，再由人做细节微调。

一套更稳的 Claude Code 工作流

把上面这些技巧组合起来，可以形成一套比较稳的流程：

在项目目录启动 claude。
先用计划模式讨论需求。
批准计划前确认技术栈和验收标准。
涉及高风险操作时保留手动确认。
用终端模式执行本地预览和测试。
结果走偏时及时回滚。
把项目规则写进 CLAUDE.md。
长对话定期查看和压缩上下文。
重复流程沉淀成 Skills。
巡检、研究、分析类任务交给只读 Agents。
特定领域任务优先用插件。
重要项目始终配合 Git 提交点。

这样使用 Claude Code，会比单纯“发一句需求等它生成”稳定得多。

小结

Claude Code 的效率不只来自模型能力，也来自工作流控制。

计划模式决定方向，权限确认控制风险，回滚减少返工，CLAUDE.md 保存项目规则，/context、/compact 和 /clear 管理上下文，Skills 复用固定流程，Agents 隔离复杂子任务，插件则把成套能力打包进项目。

真正好用的 Claude Code 工作方式，是让它在清楚边界内持续推进任务，而不是把整个项目一次性交给它自由发挥。

Awesome Codex Skills：给 Codex CLI 扩展技能的社区清单

Thu, 07 May 2026 20:19:15 +0800

ComposioHQ 的 awesome-codex-skills 是一个面向 Codex CLI 的社区技能清单。它的价值不在于再写一堆提示词模板，而是把一类可重复的工作流程整理成可安装、可复用、可维护的 Skill。

如果你已经把 Codex 当成日常开发搭档，这类仓库的意义会很直接：把经常重复讲的规则、命令、资料入口和操作步骤沉淀下来，下次只要调用对应技能，Codex 就能按同一套上下文继续工作。

这个仓库解决什么问题

Codex Skills 可以理解成给 Codex CLI 增加“专门工作模式”的方式。普通提示词适合临时说明一次需求，Skill 更适合长期复用。

比如你经常需要：

按固定格式生成提交信息；
查阅某类 API 文档；
运行特定项目的测试和部署命令；
按团队规范重写文章、翻译文档或整理资料；
调用外部工具完成重复性的开发辅助任务。

这些内容如果每次都重新输入，很快就会变成负担。Skill 的思路是把这些规则放进一个独立目录里，核心通常是一份 SKILL.md，必要时再配合脚本、模板、参考资料或资产文件。Codex 在被触发时读取这份说明，然后按照里面定义的流程执行。

和普通提示词有什么不同

普通提示词更像一次性指令，适合告诉模型“这次怎么做”。Skill 更像一个小型操作手册，适合告诉 Codex“以后遇到这类任务都按这个方式做”。

它的优势主要有三个：

可复用：常用工作流不用反复复制粘贴。
可审查：技能文件通常是本地 Markdown，可以直接打开、修改和版本管理。
可扩展：复杂技能可以带脚本、模板和参考资料，不只是自然语言说明。

这也是 awesome-codex-skills 这类清单的价值所在：它帮你集中发现已经写好的技能，再根据自己的工作习惯挑选、安装和改造。

如何安装和使用

仓库提供了安装脚本，也支持手动安装。典型流程是先克隆仓库，再运行安装脚本：

1
2
3

git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills
python install.py

如果你只想试用少数技能，建议先看清每个技能目录里的 SKILL.md，确认它会读取哪些资料、运行哪些脚本、修改哪些文件，再安装到本地 Codex skills 目录。

安装之后，Codex 可以在合适的任务中自动匹配技能，也可以通过明确点名的方式调用。对长期使用者来说，更实用的方式往往是：先安装一个社区技能，再把里面的说明改成自己的项目规范。

适合关注哪些技能

这类仓库里最值得优先看的，不一定是名字最酷的技能，而是能稳定减少重复劳动的技能。

我会优先关注几类：

开发流程类：代码审查、测试、提交、发布、依赖检查。
文档处理类：重写、翻译、摘要、结构化整理。
工具集成类：把 Codex 和外部服务、API、命令行工具连接起来。
项目规范类：把团队约定、目录结构、命名规则、部署步骤写进固定流程。

如果一个技能只是把一句提示词包装了一下，价值有限；如果它能把“查资料、判断、执行、验证、输出”串成稳定流程，就值得长期保留。

使用时要注意什么

社区技能虽然方便，但不要把它当成黑盒直接运行。尤其是带脚本的 Skill，安装前最好先检查三件事：

SKILL.md 里要求 Codex 做什么；
是否包含会访问网络、读写文件或调用外部服务的脚本；
默认路径、命令和权限是否适合你的本地环境。

Skill 本质上是在扩大 Codex 的行动边界。写得好，它会让 Codex 更像熟悉你项目的同事；写得粗糙，它也可能把不适合你的规则带进工作流。所以最理想的用法不是“装很多”，而是“装少数、改到顺手、长期维护”。

我的判断

awesome-codex-skills 值得收藏，尤其适合已经开始用 Codex CLI 做真实开发、文档或自动化任务的人。它不是官方能力本身，而是一个社区整理的技能入口：你可以从里面找灵感，也可以把常用流程改造成自己的本地技能库。

对重度用户来说，Codex Skills 的重点不是让 AI 多记一点东西，而是让 AI 在同类任务中少走弯路。把规则写成 Skill，等于把一次次临时沟通沉淀成可复用的工作基础设施。

CC Switch：一个桌面工具统一管理 Claude Code、Codex、Gemini CLI 和 OpenClaw

Wed, 06 May 2026 09:03:08 +0800

CC Switch 是一个面向 AI 编程重度用户的桌面管理工具。它要解决的问题很直接：现在很多人同时使用 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw，但每个工具都有自己的配置格式、Provider 写法、MCP 配置和 Skills 管理方式。

当你只用一个工具时，手动改配置还能忍；一旦多个工具混用，再加上官方账号、第三方 API、中转服务、本地模型和团队共享配置，手动编辑 JSON、TOML、.env 很快就会变成一件很烦的事。

CC Switch 的定位，就是把这些分散配置收进一个跨平台桌面应用里。

它解决什么问题

现代 AI 编程工具越来越像“命令行里的开发同事”，但每个工具的生态还没有完全统一。

常见痛点包括：

Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 配置格式不同。
切换 API Provider 时，要反复改配置文件。
MCP server 在不同工具之间重复配置。
CLAUDE.md、AGENTS.md、GEMINI.md 这类提示文件难以统一维护。
Skills 安装、同步、备份和卸载缺少一个集中入口。
多个账号、多个 relay、多个模型服务切换很容易搞混。
配置文件手工修改出错后，排查成本很高。

CC Switch 的思路是：不要让用户记住每个工具的配置细节，而是用一个统一界面管理 Provider、MCP、Prompts、Skills、Sessions 和代理。

支持哪些工具

README 中列出的核心支持对象包括五类：

Claude Code
Codex
Gemini CLI
OpenCode
OpenClaw

这几个工具本身定位相近，都是围绕 AI 编程、Agent 工作流和命令行协作展开。但它们的配置体系不同，CC Switch 的价值就在于把这些差异包装起来。

对经常比较不同 AI 编程工具的人来说，这比每次手动翻配置文件省心很多。

Provider 管理

CC Switch 的第一层能力是 Provider 管理。

它内置了 50 多个 Provider 预设，README 中提到的方向包括 AWS Bedrock、NVIDIA NIM，以及各种社区 relay。用户可以复制 API key，一键导入，然后在界面中切换。

实用点主要有几个：

一键添加 Provider。
Provider 拖拽排序。
系统托盘快速切换。
Provider 导入和导出。
部分通用 Provider 可同步到多个应用。

对很多人来说，这个功能已经足够有吸引力。因为 AI 编程工具的日常使用，经常不是“模型不会用”，而是“今天这个 key 用哪个工具、哪个 endpoint、哪个账号”容易乱。

本地代理与故障切换

除了写配置文件，CC Switch 还提供本地代理模式。

这个能力的重点是：

热切换 Provider。
格式转换。
自动故障转移。
熔断器。
Provider 健康检查。
请求修正。

简单说，它不只是把配置写进目标工具，还可以在中间加一层本地代理，让不同工具通过代理访问模型服务。

这对多 Provider 用户很有用：一个服务挂了，可以切到另一个；一个模型贵，可以换成更便宜的；某个请求格式不兼容，也可以通过代理层做适配。

MCP、Prompts 和 Skills

CC Switch 比较重要的第二层能力，是统一管理 MCP、Prompts 和 Skills。

MCP

它提供统一 MCP 面板，可以在多个应用之间管理 MCP server，并支持双向同步和 Deep Link 导入。

这对正在用 MCP 的用户很实用。因为 MCP server 一多，配置很容易分散在不同客户端里。统一面板可以减少重复配置，也方便迁移。

Prompts

Prompts 部分支持 Markdown 编辑，并且可以在不同工具之间同步对应文件，例如：

CLAUDE.md
AGENTS.md
GEMINI.md

这些文件本质上都是给 Agent 的项目说明书。统一管理后，可以更容易维护团队规则、项目约定和全局提示。

Skills

Skills 支持从 GitHub 仓库或 ZIP 文件一键安装，也支持自定义仓库管理、符号链接和文件复制。

如果你同时使用 Claude Code、Codex、OpenClaw 这类工具，Skills 很容易变成一堆散落在不同目录的文件。CC Switch 把它们集中起来，能降低维护成本。

会话与工作区

README 还提到 Session Manager 和 Workspace 相关能力。

它可以浏览、搜索和恢复多个应用里的会话历史。对长期使用 AI 编程工具的人来说，会话管理其实很重要：很多有价值的上下文、调试过程、方案比较，都埋在旧对话里。

此外，它还为 OpenClaw 提供 Workspace editor，可以编辑 AGENTS.md、SOUL.md 等 agent 文件，并带 Markdown 预览。

这说明 CC Switch 不只是一个“切换 key 的小工具”，而是在往 AI Agent 工作台方向扩展。

云同步与数据存储

CC Switch 支持通过 Dropbox、OneDrive、iCloud、NAS 或 WebDAV 同步 Provider 数据。

本地数据存储方式也比较清楚：

数据库：~/.cc-switch/cc-switch.db
本地设置：~/.cc-switch/settings.json
自动备份：~/.cc-switch/backups/
Skills：~/.cc-switch/skills/
Skill 备份：~/.cc-switch/skill-backups/

它使用 SQLite 作为主要数据源，并强调原子写入和自动备份，目标是避免配置文件在切换或写入时损坏。

这个设计对重度用户很关键。因为一旦配置管理工具本身把配置写坏，影响的是所有 AI 编程工具。

安装方式

CC Switch 是跨平台桌面应用，基于 Tauri 2 构建。

系统要求大致如下：

Windows：Windows 10 及以上
macOS：macOS 12 Monterey 及以上
Linux：Ubuntu 22.04+、Debian 11+、Fedora 34+ 等主流发行版

Windows 用户可以下载 .msi 安装包或便携版压缩包。

macOS 用户可以用 Homebrew：

1
2

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

`1`	`brew upgrade --cask cc-switch`

Linux 用户可以选择 .deb、.rpm 或 AppImage。Arch Linux 用户也可以通过 paru -S cc-switch-bin 安装。

截至 2026 年 5 月 6 日，仓库页面显示最新 release 为 CC Switch v3.14.1，发布时间是 2026 年 4 月 23 日。

技术栈

从仓库结构看，CC Switch 是典型的 Tauri 桌面应用：

前端：React 18、TypeScript、Vite、TailwindCSS、TanStack Query、shadcn/ui
后端：Tauri 2、Rust、SQLite、Tokio
测试：Vitest、MSW、Testing Library

核心设计模式包括：

SQLite 作为 Single Source of Truth。
JSON 保存设备级本地设置。
切换时写入目标工具的 live config。
编辑当前 Provider 时从 live config 回填。
使用临时文件加 rename 的方式做原子写入。
数据库连接加锁，避免并发写入问题。

这类架构说明项目并不是简单脚本，而是按长期桌面工具来设计的。

适合谁用

CC Switch 适合下面几类用户：

同时使用 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw。
经常切换官方账号、第三方 relay、本地模型或团队 Provider。
已经开始大量使用 MCP。
想统一维护 CLAUDE.md、AGENTS.md、GEMINI.md。
经常安装、测试和迁移 Skills。
想看不同工具的会话历史和使用情况。

如果你只用一个 AI 编程工具，而且一直走官方登录，不怎么折腾 Provider、MCP 和 Skills，那它的价值可能没那么明显。

但如果你已经进入“多工具、多账号、多 Provider、多项目”的状态，它能省掉很多琐碎配置工作。

需要注意什么

这类工具很方便，但也要注意边界。

第一，它会管理多个 AI CLI 的配置，因此要确认自己信任这个工具和它的写入逻辑。

第二，API key、relay endpoint、MCP server 都属于敏感配置。开启云同步前，要确认同步目录和 WebDAV 服务本身安全可靠。

第三，切换 Provider 后，多数工具仍然需要重启终端或 CLI 才能生效。README 中提到，Claude Code 对 Provider 数据支持热切换，但其他工具通常仍需要重启。

第四，切回官方登录时，最好按项目说明添加 official provider，再重新走对应工具的登录流程。

小结

CC Switch 的价值不在于又做了一个 AI 编程工具，而在于它承认了一个现实：AI 编程生态已经进入多工具并存阶段。

Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 各有自己的配置系统，MCP、Skills、Prompts、Provider 又在快速扩展。继续靠手动改配置，迟早会变成负担。

CC Switch 把这些东西收进一个桌面应用里，让用户可以更轻松地切换 Provider、同步 MCP、管理 Skills、维护提示文件和查看会话。对重度 AI 编程用户来说，这类工具很可能会从“可选小工具”变成“日常基础设施”。

参考资料

farion1231/cc-switch

Codex App 保姆级上手：安装、沙盒、并行任务、Skills 与 MCP

Wed, 06 May 2026 08:41:17 +0800

Codex App 可以理解成一个面向 AI 编程的任务工作台。它不是传统 IDE，也不是单纯聊天窗口，而是把多任务、项目管理、沙盒权限、Git、云端运行、插件、Skills、MCP 和自动化集中到一个界面里。

如果你已经在用 Codex CLI、Claude Code、Cursor 或其他 coding agent，Codex App 最值得关注的地方，是它把“多个 agent 并行干活”做成了一个更清晰的桌面工作流。

Codex App 适合做什么

Codex App 的核心价值不是让 AI 回答问题，而是让 AI 在项目目录里持续执行任务：

修改代码、运行命令、启动开发服务。
管理多个项目和多个任务。
在本地或云端执行长任务。
调用插件、Skills 和 MCP 扩展能力。
通过 Git、worktree 和 PR 管理改动。

OpenAI 官方也把 Codex App 定位成一个用于管理多个 coding agent 的界面。它适合需要同时推进多个代码任务的人，尤其适合前端页面、脚本工具、小型应用、文档整理和自动化工作流。

安装前准备

使用 Codex App 前，建议先准备好三个基础工具：

Git
Node.js
VS Code 或你常用的 IDE

Codex App 支持 macOS 和 Windows。安装后使用 ChatGPT 账号登录，首次进入时可以选择主要使用场景，例如编程或日常工作。Codex 会根据选择预装一部分插件和 Skills，后续也可以在设置和插件市场里调整。

Windows 和 macOS 的主要功能大体一致，但部分电脑自动化能力可能依赖具体平台和插件支持，实际以你当前版本显示为准。

界面结构：项目、任务和对话

Codex App 是典型的三栏布局：

左侧：项目、任务、历史对话、插件和自动化入口。
中间：当前对话窗口。
右侧：文件、浏览器、终端、运行结果等多功能区域。

一个项目通常对应一个本地文件夹。你可以在同一个项目里开多个对话，也可以同时打开多个项目，让不同 agent 并行执行任务。

任务列表会显示不同状态：

正在运行：agent 仍在执行。
等待批准：需要你确认权限、联网、安装依赖或执行高风险操作。
已完成：任务已经结束，可以查看结果或继续追问。

这比在多个终端窗口里来回切换更直观，也更适合同时管理多个 AI 任务。

沙盒与权限控制

Codex App 的权限体系围绕沙盒展开。默认情况下，当前项目文件夹会成为 agent 的主要工作范围。

常见权限边界包括：

可以读取和修改项目目录内的文件。
默认不能随意修改项目外文件。
默认会限制联网或高风险命令。
需要越权时，会向用户申请批准。

比较实用的模式是“自动审查”：低风险操作由系统自动放行，高风险操作再交给用户确认。这样既能减少频繁弹窗，又能避免 agent 在不知情的情况下执行危险操作。

“完全访问”要谨慎开启。它适合你明确知道 agent 要做什么，并且项目已经有 Git 备份、重要文件也有额外备份的场景。日常使用不建议长期保持完全访问。

上下文、模型和额度

Codex App 会显示当前对话的上下文使用情况。对话越长，历史内容越多，模型需要处理的上下文也越大。

实用建议是：

一个任务完成后，优先开新对话。
长对话可以手动压缩，但不要把压缩当成万能记忆。
复杂任务先写清楚目标、边界和验收标准。
不要把大量无关日志、报错和文件一次性塞进对话。

模型选择上，可以根据任务复杂度调整思考强度。简单修改、文案整理、重复任务不一定需要最高规格模型；架构迁移、疑难 bug、跨文件重构则更适合使用更强模型。

如果界面里有快速模式，也要注意它通常会带来更高的额度消耗。赶时间时可以开，日常不必默认开启。

图片生成与多模态输入

Codex App 可以接收图片和文件作为上下文，也可以在合适场景中调用图像生成能力。

这对前端和内容类项目很有用。例如你可以让 Codex：

根据截图修正页面样式。
替换网页中的不合适配图。
生成产品图、轮播图或页面素材。
根据 UI 截图指出需要修改的位置。

更高效的用法是：不要只说“改好看一点”，而是结合截图指出具体问题，例如“这个卡片间距太大”“这里的图和服务场景不匹配”“把地图区域做得更清楚”。

Steer：任务执行中及时纠偏

Steer 可以理解成“执行中接管方向”。当 agent 已经开始执行，但你发现它理解错了方向，不应该等它全部跑完再改。

这时可以使用引导功能，把新的指令插入当前执行流程，让 Codex 及时修正路线。

适合使用 Steer 的场景包括：

agent 误解了需求。
生成的页面风格明显不对。
正在执行的方案成本太高。
你临时补充了关键约束。

一般建议保留默认排队行为，只在确实需要干预时手动使用 Steer。这样既不会打乱正常任务，也能在关键时刻把方向拉回来。

计划模式和内置浏览器

复杂任务建议先开计划模式。计划模式下，Codex 不会马上改代码，而是先输出方案，必要时还会用卡片形式追问关键选择。

适合开计划模式的任务：

框架迁移，例如从普通 React 项目迁到 Next.js。
大范围重构。
涉及数据库、认证、部署的功能。
你还没想清楚技术路线的需求。

Codex App 的右侧区域可以打开内置浏览器，用来预览本地开发服务。你可以在页面上做批注，让 Codex 按具体 UI 位置修改问题。这种“看页面、点位置、让 AI 改”的流程，比纯文字描述更适合前端调试。

Git、IDE 和代码回滚

Codex App 不是完整 IDE。它可以查看代码、批注代码，但真正的手写编辑仍然更适合交给 VS Code、Cursor、Windsurf 等 IDE。

建议每个 Codex 项目都尽早初始化 Git：

让 Codex 创建或检查 .gitignore。
在完成一个可用状态后提交一次。
每次大改前确保有干净提交点。
不满意时用 Git 回滚代码。

如果只回滚对话历史，代码不会自动跟着回滚。比较稳的做法是：对话层面回到合适节点，代码层面用 Git commit hash 回到对应状态。

Worktree：并行开发多个方向

git worktree 是 Codex App 里非常适合并行 agent 的能力。

它的本质是：基于同一个仓库创建多个独立工作目录，每个目录对应不同分支。这样你可以让不同 agent 在不同文件夹里同时开发，不互相覆盖。

典型用法：

一个 worktree 优化客户评价组件。
一个 worktree 调整门店信息和地图布局。
两个任务完成后分别合并回主干。
合并完成后删除临时 worktree。

这比在同一个目录里让多个 agent 同时改代码稳得多。遇到冲突时，也可以按正常 Git 流程 review 和合并。

云端运行环境

Codex 不只能在本机工作，也可以把任务委托到云端环境执行。

云端运行适合这些场景：

出门在外，手边只有手机。
希望 agent 在后台跑长任务。
代码已经同步到 GitHub，需要让 Codex 基于远端仓库修改。
希望通过 PR 形式审查和合并改动。

典型流程是：先把本地代码推到 GitHub，再让 Codex 在云端环境中拉取仓库、执行任务、生成改动，最后以 PR 或 diff 的方式交给你审核。

本地继续开发时，要记得把远端最新改动同步回来。

记忆系统：写好 AGENTS.md

新对话默认没有完整历史记忆。项目一复杂，如果每次都重新解释背景，会很浪费。

最通用的做法，是在项目根目录维护 AGENTS.md。这个文件可以记录：

项目目标和主要技术栈。
常用命令。
目录结构说明。
代码风格和命名约定。
禁止事项，例如不要批量删除文件。
测试、构建和部署规则。

你也可以让 Codex 先通读项目，再生成一版 AGENTS.md，然后人工审一遍。复杂项目里，这个文件非常值得维护。

全局规则也要谨慎。适合写入所有项目都通用的安全约束，例如“不要递归删除目录”“执行破坏性操作前必须确认”。不要把某个项目的细节写进全局规则，否则会污染其他项目。

插件和自动化

插件用于把外部服务接入 Codex，例如 GitHub、Gmail、Google Drive、数据库、部署平台等。

插件的价值在于减少复制粘贴。比如你可以让 Codex：

查看某个 GitHub 仓库的 star 趋势。
整理邮件内容并发给自己。
定期执行某个检查任务。
把结果写成摘要。

自动化则适合重复任务。例如每周五下午检查一次仓库数据，并发送邮件报告。简单自动化任务通常不需要最高规格模型，选择较轻量的模型即可。

Skills：把工作流变成可复用能力

Skills 是 Codex 的“专业说明书”。它不是单次提示词，而是把某类任务的流程、规范、脚本和注意事项沉淀下来，让 Codex 后续稳定复用。

常见来源有三类：

官方 Skills。
第三方 Skills。
自己编写的 Skills。

适合做成 Skill 的工作：

把字幕整理成图文笔记。
按公司规范写周报。
批量处理图片或文档。
固定格式的代码审查。
特定框架的项目初始化。

如果某个提示词你已经复制粘贴了很多次，就值得考虑把它做成 Skill。

MCP：接入外部工具和数据库

MCP 可以理解成给大模型使用的标准化工具协议。通过 MCP，Codex 可以调用外部服务完成更具体的任务。

例如接入 Supabase 后，可以让 Codex：

创建数据表。
读取数据库结构。
修改后端接口。
把前端表单提交到数据库。
根据数据库状态调试问题。

这类能力很强，但也要注意权限边界。数据库、生产环境、部署平台、邮件账号都属于高风险资源。第一次接入时，最好使用测试项目和低权限账号。

部署插件

部署平台插件可以让 Codex 直接完成构建和发布，例如把前端项目部署到 Netlify 一类平台。

这类插件适合小型网站、原型页面、内部工具和展示项目。实际使用时建议注意：

部署前先跑本地构建。
环境变量不要直接写进代码。
发布后检查页面是否能正常访问。
生产项目要保留人工 review。

AI 可以帮你打通发布流程，但发布权限仍然要谨慎管理。

电脑自动化

在支持的平台和插件环境里，Codex 还可以操作浏览器或桌面应用，完成更接近 RPA 的任务。

例如：

打开聊天软件并准备一条消息。
浏览项目看板，汇总任务状态。
生成英文简报。
在你确认后发送给指定对象。
把这套流程做成定时自动化。

这类功能很有想象力，但也最需要安全边界。凡是涉及发消息、发邮件、提交表单、付款、删除数据的操作，都应该保留人工确认。

使用建议

Codex App 的正确打开方式，不是让它一次性全自动接管一切，而是把任务拆清楚，让它在受控环境里高效执行。

推荐习惯：

每个项目先初始化 Git。
复杂任务先开计划模式。
并行任务优先用 worktree。
项目规则写进 AGENTS.md。
高风险操作保留人工确认。
重复流程沉淀成 Skill 或自动化。
插件和 MCP 先在测试环境验证。

参考资料

小结

Codex App 的重点不是“多一个 AI 聊天窗口”，而是把 AI 编程变成一个可管理的工作台：本地项目、云端任务、Git、worktree、插件、Skills、MCP 和自动化都能串起来。

真正用好它的关键，是在“放权”和“控制”之间找到平衡。小任务可以大胆交给 Codex，复杂任务先让它计划，高风险动作必须确认。这样它才会从一个会写代码的助手，变成可以长期协作的工程工具。

mattpocock/skills：给 AI 编程 Agent 准备的实用技能集合

Fri, 01 May 2026 03:43:20 +0800

mattpocock/skills 是 Matt Pocock 公开的一组 AI 编程 agent skills。

它不是一个完整的应用，也不是一个新的聊天客户端，而是一套可以给 AI 编程助手使用的工作技能。它的思路很实用：把 AI 编程里经常出现的问题拆成一个个小技能，让 Agent 在合适的任务里调用，而不是每次都靠一大段提示词硬撑。

如果你经常使用 Claude Code、Codex、Cursor 或类似的 AI 编程工具，这类 skills 很值得关注。因为真正影响 AI 编程体验的，往往不是“模型会不会写代码”，而是它能不能按你的工作方式推进任务。

它解决什么问题

AI 编程助手很强，但也很容易出问题。

常见情况包括：

还没理解需求就开始改代码
一次性改太多文件
输出解释很多，真正有用的行动很少
遇到报错后盲目尝试
没有及时运行测试或检查
忽略项目里已有模式
为了完成任务引入不必要的抽象
写完代码后没有真正 review 风险

这些问题不一定是模型能力不够，而是工作流没有被约束好。

mattpocock/skills 的价值在于，把这些常见失败模式拆成可以复用的操作方式，让 Agent 在不同场景下更像一个有经验的工程协作者。

Skills 是什么

在 AI Agent 语境里，skill 可以理解成一段可复用的任务说明、工作方法或专业流程。

它不一定是代码插件，也不一定必须调用外部服务。很多时候，一个 skill 就是一套明确规则：

什么时候使用
先做什么
不要做什么
需要输出什么
怎么判断任务完成

这和普通提示词模板有点像，但粒度更接近“任务能力”。

普通提示词模板通常是用户每次临时复制粘贴；skills 则更适合作为 agent 工具箱的一部分，让 Agent 根据任务选择合适流程。

为什么要小而可组合

README 中强调这些 skills 是小而可组合的。

这个方向很重要。

如果一个 skill 试图包办所有事情，它很快就会变成新的大提示词：又长、又模糊、又难维护。小技能的优势是边界清楚。

比如一个 skill 专门负责：

先做计划
修复 TypeScript 错误
运行测试并根据结果修复
做代码 review
总结项目约定
改进提示词
清理无用抽象

这些技能可以按任务组合使用。简单任务只用一个技能，复杂任务再串起来。

这更接近真实工程工作：你不会用同一套流程处理所有问题，而是根据问题选择工具。

保留工程师控制权

这个仓库的一个重要取向，是让工程师仍然掌握控制权。

AI 编程很容易滑向两种极端：

第一种是完全手动。AI 只是帮你写几行代码，所有上下文、计划、验证都靠你自己盯。

第二种是完全放手。你把任务丢给 Agent，让它自己大改一通，最后再面对一堆难以审查的 diff。

skills 的作用是在中间找一个更稳的位置。

它让 AI 承担更多重复流程，但仍然用规则限制它：

先理解任务再动手
先阅读相关文件再改
修改范围要可控
出现不确定时要回报
改完要验证
不能为了炫技重构无关代码

这不是削弱 AI，而是让 AI 的行动更容易被人类审查和接管。

对齐问题

AI 编程失败的第一类问题通常是对齐失败。

用户想要的是一个很具体的改动，但 Agent 可能理解成一个更大的重构；用户只想修 Bug，它却顺手改了样式；用户希望遵守现有架构，它却引入新模式。

Skills 可以在任务开始阶段帮助 Agent 做几件事：

重述目标
找出影响范围
识别已有实现模式
给出计划
明确不做哪些事情

这一步很像工程师开工前的自检。

如果 Agent 连任务边界都没说清楚，就直接写代码，后面很容易越走越偏。

反馈循环问题

AI 写代码不能只靠一次生成。

真实开发里，反馈循环很重要：

改一小步
跑测试或类型检查
看错误
修正
再验证

很多 Agent 失败，是因为它跳过了中间反馈。它一次性改很多内容，然后凭感觉总结“应该可以工作”。

Skills 可以把反馈循环显式写进流程里。比如要求 Agent：

修改后运行相关检查
如果检查失败，先读错误信息
不要盲目改无关文件
每轮修复后重新验证
最后报告验证结果

这会让 AI 编程更像真实调试，而不是一次性作文。

架构控制问题

AI 很擅长生成抽象，也很擅长过度生成抽象。

为了完成一个小需求，它可能新建服务层、工具函数、配置对象、类型包装、适配器，最后让代码比需求本身复杂得多。

这类问题在大型项目里尤其危险。因为 AI 生成的抽象看起来很“专业”，但它可能不符合项目已有风格，也可能增加维护成本。

好的 skills 会提醒 Agent：

优先沿用现有模式
不引入没有必要的新抽象
不顺手重构无关区域
修改要和任务规模匹配
先理解代码再设计结构

这能减少“看起来很工程化，实际上更难维护”的输出。

Review 技能为什么重要

写代码和 review 代码是两种不同状态。

Agent 在写代码时，通常会倾向于证明自己的实现成立。它会解释为什么这样改可以工作，但不一定主动找风险。

Review skill 的意义，是让 Agent 切换角色：

找潜在 Bug
找行为回归
找遗漏测试
找边界条件
找复杂度上升
找和现有约定不一致的地方

这对 AI 编程很重要。因为 AI 生成代码的速度很快，如果没有 review，用户很容易被大量 diff 淹没。

一个好的 review 输出应该优先列问题，而不是先夸实现。它要帮助工程师判断这次改动能不能合并。

和普通 rules 文件有什么区别

很多 AI 编程工具都支持 rules、instructions 或 memory。

这些文件通常记录长期规则，比如：

项目技术栈
命名规范
测试命令
不要修改哪些目录
回答风格偏好

Skills 更偏任务流程。

rules 告诉 Agent “长期应该怎么做”，skills 告诉 Agent “面对某类任务时应该怎么执行”。

两者最好一起用。

比如 rules 里写项目用 pnpm test，review skill 里要求改完后检查测试覆盖。这样 Agent 不仅知道命令，也知道什么时候该用。

适合什么场景

mattpocock/skills 这类仓库适合这些场景：

高频使用 AI 编程工具
经常让 Agent 处理真实代码库
想减少 AI 越界修改
想让 Agent 更主动地验证结果
想把自己的工程习惯沉淀成技能
想学习别人如何设计 agent workflows
想把一堆临时提示词整理成可维护的技能集合

如果你只是偶尔让 AI 写一个小函数，可能不需要专门维护 skills。

但如果你已经把 AI 当成长期开发伙伴，skills 会逐渐变得重要。它们相当于给 Agent 配了一套可复用的工作方法。

怎么借鉴这个仓库

即使你不直接使用其中的每个 skill，也可以从这个仓库学到几件事。

第一，把失败模式写下来。

不要只在 AI 出错时临时抱怨。把它经常出错的模式整理成规则，下一次让 skill 提前防住。

第二，技能要短。

一个 skill 最好解决一个明确问题。越短越容易被正确调用，也越容易维护。

第三，输出格式要清楚。

如果你希望 Agent 先列计划、再执行、最后总结验证结果，就把输出结构写清楚。模糊要求通常会得到模糊结果。

第四，保留人工接管点。

好的 skill 不应该让 AI 独自跑到很远。遇到不确定、影响范围扩大、测试失败或需要产品判断时，应该让它停下来说明情况。

使用时要注意

第一，不要把所有事情都技能化。

太多 skills 会让系统变复杂，Agent 也可能不知道该选哪个。先从最高频、最痛的几个场景开始。

第二，skills 需要迭代。

第一次写出来的 skill 不一定好。看 AI 实际执行效果，再逐步删减、补充和改写。

第三，不要让 skill 替代工程判断。

Skill 可以改善流程，但不能保证实现正确。测试、review、构建检查和人类判断仍然重要。

第四，注意不同 Agent 的差异。

Claude Code、Codex、Cursor、Copilot 对 instructions、skills、rules 的支持方式不同。同一套思想可以复用，但具体格式要按工具调整。

参考

mattpocock/skills

最后一句

mattpocock/skills 值得关注的地方，不是里面某一个神奇提示词，而是它展示了一种更实用的 AI 编程思路：把工程经验拆成小技能，再让 Agent 按场景组合使用。

当 AI 编程从偶尔辅助变成日常工作流，skills 会成为约束 Agent、保留工程师控制权和提升反馈质量的重要工具。

Codex Skill 明明在目录里，为什么就是不显示？

Wed, 29 Apr 2026 11:18:00 +0800

这次遇到的问题很隐蔽：~/.codex/skills 里明明已经放好了多个 skill，新开 Codex 线程之后，侧边栏却还是只能看到少数几个。

一开始看起来像是缓存或索引问题，但实际原因更具体：几个 SKILL.md 文件开头带了 UTF-8 BOM，Codex 0.111.0 的 skill loader 没有跳过这个字节，于是误判文件没有合法的 YAML front matter。

现象

本地目录里有这些 skill：

~/.codex/skills/git-commit-push/SKILL.md
~/.codex/skills/hugo-rsync-deploy/SKILL.md
~/.codex/skills/bilibili-speech-transcriber/SKILL.md
~/.codex/skills/product-cutout-normalize/SKILL.md

但新开线程时，实际暴露出来的只有：

1
2

bilibili-speech-transcriber
product-cutout-normalize

也就是说，文件存在不等于当前会话一定能加载成功。Codex 会先解析每个 SKILL.md 的 front matter，解析失败的 skill 会直接被排除。

排查

用 codex exec 启动一个新会话时，可以看到更直接的错误（在vscode等IDE中可能看不到这些log）：

1
2

failed to load skill C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md: missing YAML frontmatter delimited by ---
failed to load skill C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md: missing YAML frontmatter delimited by ---

这些文件肉眼看起来都有正常的开头：

---
name: post-rewrite
description: ...
---

真正的问题在字节层面。

失败文件的开头是：

`1`	`EF-BB-BF-2D-2D-2D`

能正常加载的文件开头是：

`1`	`2D-2D-2D`

2D-2D-2D 就是 ---。前面的 EF-BB-BF 是 UTF-8 BOM。

原因

Codex 0.111.0 的 skill loader 当前要求 SKILL.md 文件第一个字节就是 --- 的第一个 -。

如果文件前面带了 UTF-8 BOM，那么文件实际开头就不再是 ---，而是：

`1`	`BOM + ---`

于是 loader 会认为它没有以 front matter 分隔符开头，最后报：

`1`	`missing YAML frontmatter delimited by ---`

这不是 skill 内容写错了，也不是目录放错了，而是编码细节让解析器没认出来。

修复

把出问题的 SKILL.md 转成无 BOM 的 UTF-8 即可。

PowerShell 可以这样处理：

$paths = @(
  'C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md',
  'C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md',
)

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)

foreach ($p in $paths) {
  $text = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
  [IO.File]::WriteAllText($p, $text, $utf8NoBom)
}

处理后再检查文件头，应该从：

`1`	`EF-BB-BF-2D-2D-2D`

变成：

`1`	`2D-2D-2D`

验证

重新启动一个 Codex 会话后，可见 skill 恢复为：

git-commit-push-zh
hugo-rsync-deploy
bilibili-speech-transcriber
product-cutout-normalize

如果侧边栏仍然只显示旧的列表，可以退出当前 Codex sidebar 或窗口，再重新打开项目。skill 列表通常在会话启动时加载，中途改文件不一定会立刻刷新到当前线程。

最后一句

这类问题最容易误判成“Codex 没重新索引”或“skill 没安装好”。

实际排查时可以先看三件事：

SKILL.md 是否真的在正确目录
文件头部是否有合法的 --- front matter
文件是否是无 BOM 的 UTF-8

这次的关键就是第三点：文件看起来没问题，但第一个字节不是 -，Codex 就没有把它当作一个有效 skill。

Codex 里的 ~/.codex/skills 和项目/.codex/skills 有什么区别

Wed, 29 Apr 2026 11:08:00 +0800

很多人整理 Codex skills 时，最容易卡住的问题就两个：

~/.codex/skills 和 项目/.codex/skills 有什么区别
为什么 skill 明明在目录里，当前会话里却不一定显示

这篇就直接说结论。

两者的区别

先记最短版本：

~/.codex/skills 是你的全局技能库
项目/.codex/skills 是这个仓库的本地技能库

`~/.codex/skills`

适合放：

你自己跨项目反复会用的 skill
跟具体仓库无关的通用流程
很明显属于你个人习惯的工作流

比如：

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

这类 skill 的特点就是：离开当前项目也还能用。

`项目/.codex/skills`

适合放：

只对这个仓库成立的流程
跟当前项目目录结构、脚本、模板绑定很深的规则
需要让团队一起共享的 skill

比如：

这个仓库特有的发布流程
只能在这个项目里用的生成模板
跟项目私有脚本强绑定的自动化步骤

这类 skill 的特点是：离开这个仓库就没意义。

什么时候放全局，什么时候放项目里

直接这样判断就够了：

跟你个人习惯有关，放 ~/.codex/skills
跟仓库规则有关，放 项目/.codex/skills
能跨项目复用，优先放全局
要多人共享、跟仓库一起演进，优先放项目里

当前这个仓库是什么情况

按我现在看到的实际状态：

你的本机里有 ~/.codex/skills
当前仓库里没有 .codex/skills

所以你现在主要依赖的是全局 skills。
也就是说，像 post-rewrite、post-translate、git-commit-push 这些流程，现在更多是你个人工作流的一部分，不是这个仓库显式自带的一部分。

为什么磁盘里有，当前会话里却不一定显示

这里要分清两件事：

磁盘存在：说明 skill 文件在本地目录里
会话暴露：说明当前会话把它注册进了可用 skill 列表

这两者不是一回事。

所以会出现这种情况：

~/.codex/skills 里已经有 skill
但 / 后面的列表里没有显示

这通常不代表 skill 坏了，更常见的原因是：当前会话没有把它重新索引进去。

怎样让 skill 被当前会话暴露

最实用的步骤就这几条：

1. 目录放对

全局：

`1`	`~/.codex/skills/<skill-name>/SKILL.md`

项目级：

`1`	`项目/.codex/skills/<skill-name>/SKILL.md`

2. `SKILL.md` 头部可识别

最少要有：

---
name: your-skill-name
description: 这个 skill 是干什么的
---

3. 新建或修改后，开新会话

很多时候 skill 没显示，不是文件有问题，而是当前会话启动时就已经把可用 skill 列表定下来了。
所以你中途新建 skill，磁盘里虽然已经有了，这次会话也未必会重新认。

最稳的做法就是：

放好 skill
结束当前会话
重新进入项目
开一个新会话
再看 / 里有没有出现

4. 项目 skill 最好提前放好

如果你想让 项目/.codex/skills 更稳定地被识别，最好在进入仓库、启动会话之前，就把这些 skill 放进项目里。

最后一句

最短结论就是：

~/.codex/skills 是你的个人技能库
项目/.codex/skills 是仓库的本地规则库
skill 在目录里，不等于当前会话一定会显示
想让它显示，最常见的办法就是放对目录、写好 SKILL.md，然后开新会话