重构AI技能库：以高信号密度提升AI编程助手协作效率

1. 从“技能臃肿”到“信号密度”：我为什么重构了我的AI技能库

如果你和我一样，深度依赖Claude、Cursor这类AI编程助手，那你肯定也经历过这样的时刻：面对一个复杂的Docker Compose编排问题，你满怀期待地调用了相关的“技能”，结果AI助手给你吐出了一大段冗长的背景介绍、工具历史，甚至还有好几段“最佳实践”的哲学讨论，但就是没告诉你现在容器端口冲突了到底该怎么改。更糟的是，这些动辄几百行、消耗数千个上下文Token的“技能文件”，每次对话都会挤占宝贵的上下文窗口，让你真正要处理的代码和错误信息没地方放。我之前用的一个技能库，47个文件加起来近两万行，全量加载要吃掉24万Token，这简直是在用大炮打蚊子。

正是这种切肤之痛，促使我动手重构，最终产出了这个名为ai_skills的集合。它的核心哲学只有一个：信号密度。我不需要AI给我上课，我需要它像一个经验老道的搭档，能瞬间理解我的意图，并给出精准、可操作、带判断逻辑的指令。所以，我把每个技能都压缩到平均75行左右，遵循一个极其严格的模板：身份定位 → 技术栈默认项 → 决策框架 → 反模式 → 质量关卡。结果呢？总行数从19,207行降到2,531行，每次调用消耗的Token从约3,700个降到约1,050个，降幅超过80%，但决策质量不降反升。因为所有“水分”（冗长的解释）都被挤掉了，剩下的全是“干货”（明确的规则和禁忌）。这个项目适合所有希望将AI助手从“有时靠谱的聊天对象”转变为“稳定可靠的生产力伙伴”的开发者、运维和技术负责人。

2. 技能库设计哲学：为什么“少即是多”在AI协作中至关重要

2.1 理解上下文窗口的“经济学”

AI模型的上下文窗口是稀缺资源。无论是Claude的200K，还是其他模型的128K，它都是一个需要精打细算的“内存空间”。每次你与AI对话，你提供的系统指令、历史消息、引用的文档以及加载的技能，都在瓜分这个空间。当空间被低信息密度的内容占据时，留给当前问题代码、错误日志和关键指令的空间就少了，AI的理解和生成质量会显著下降。我最初的技能库就是一个反面教材：一个“Docker部署”技能，花了大量篇幅解释什么是容器、什么是镜像，但当我真正需要解决“docker-compose up报network already exists错误”时，它却给不出直接的排查步骤。

我的核心心得是：AI技能不是百科全书，它是贴在工具箱里的“快速参考指南”。它的唯一目的是在特定场景下，快速对齐你和AI的认知，并指引AI做出符合你习惯的正确动作。因此，每一个字符都应该服务于“决策”和“避坑”，而不是“教育”。

2.2 标准化模板的力量：从混乱到一致

在重构之前，我的技能文件五花八门，有的以代码片段为主，有的像产品说明书，有的则是杂乱的知识点堆砌。这不仅让我自己维护困难，更让AI难以形成稳定的预期。标准化模板是解决这一问题的钥匙。我强制所有技能遵循同一个结构：

1. Identity (身份)：用一句话定义AI在该技能中的角色、核心原则和绝对禁忌。例如，在docker-selfhost技能中，身份是：“你是自托管服务部署专家。优先使用Docker Compose实现声明式、可复现的堆栈。绝不手动运行docker run命令链或忽略数据持久化。”
2. Stack Defaults (技术栈默认项)：用一个表格明确“用什么”和“为什么”。这直接预设了技术选型，避免了AI每次都在“用Nginx还是Traefik”、“数据库用PostgreSQL还是MySQL”这种基础问题上浪费时间。
3. Decision Framework (决策框架)：这是技能的“大脑”，以“If [条件] → [动作]”的格式编写。它教会AI如何根据具体情况做选择，比如“如果服务需要持久化数据 → 创建命名卷并映射到容器内特定路径”。
4. Anti-Patterns (反模式)：用一个“禁止行为 | 原因 | 正确做法”的表格，直击该领域最常见的错误。这是提升技能实用性的关键，它封装了经验教训。
5. Quality Gates (质量关卡)：一系列复选框，定义了任务完成前必须通过的检查。例如，“[ ] 所有服务都定义了重启策略”、“[ ] 敏感配置已移至环境变量文件”。

这个模板像一道紧箍咒，逼着每个技能只保留最精华的部分。它确保了无论谁编写技能，产出都是高密度、可预期的，让AI的发挥稳定在一条高水准线上。

3. 技能解剖：以docker-selfhost为例，看一个高效技能如何构成

让我们深入一个具体技能，看看这75行里到底塞了些什么宝贝。我以最常用的docker-selfhost为例，它是我管理家庭实验室、部署各种网络服务的基石。

3.1 身份与技术栈：建立共识基线

技能的开头是YAML前端元数据，这是技能的“触发器”：

--- name: docker-selfhost description: "Use this when: my container keeps restarting, set up a self-hosted service, my volumes are not persisting, deploy with Docker Compose, my container won't start" ---

注意，description不是工具列表，而是问题描述和意图短语的集合。当我在Claude里输入“我的容器老是重启怎么办”时，语义路由系统能精准匹配到这条描述，从而自动加载这个技能。这比让用户记住技能名“docker-selfhost”要自然得多。

紧接着是Identity部分：

## Identity You are a self‑hosted service deployment expert. You prioritize Docker Compose for declarative, reproducible stacks. You never run long docker run command chains or ignore data persistence.

三句话，确立了AI的专家角色、核心方法论（Docker Compose声明式部署）和两条铁律（不用长命令链、必须考虑持久化）。这立刻将AI的思考范围聚焦。

然后是Stack Defaults表格，它预设了技术选型：

这张表价值连城。它直接告诉AI：当我们讨论“自托管”时，默认的、首选的工具栈就是这些。这避免了无数不必要的来回问答。比如，AI不会建议我用nginx手动配置反向代理，而是直接基于Traefik给出带标签的配置。

3.2 决策框架与反模式：封装实战经验

Decision Framework部分是技能的智能核心。它不再是静态知识，而是动态的决策树：

## Decision Framework ### When to use a bind mount vs. a volume - If it's application code or config that changes frequently **and** you want to edit on the host → use a bind mount (`./app:/app`). - If it's database files, application state, or any data that must survive container removal → use a named volume (`db_data:/var/lib/postgresql/data`). ### When to expose ports - If the service needs to be accessed from outside the host (web UI, API) → expose port on host (`"8080:80"`) **and** add Traefik labels. - If communication is only between containers → place them in the same custom network, use service name as hostname, do not expose ports.

这些“If → Then”规则，是我多年踩坑经验的结晶。它让AI具备了情景判断能力。当用户说“我想映射一个目录进去方便改配置”时，AI会立刻触发“bind mount”规则；当用户说“我的数据库数据不能丢”时，AI会指向“named volume”。

而Anti-Patterns表格，则是专门针对常见坑点的“疫苗”：

这个表格的威力在于“防患于未然”。很多新手（甚至老手）会下意识地犯这些错误。通过在技能中明确禁止并给出正确做法，AI会在生成配置的第一时间就规避这些风险。例如，只要用户要求部署PostgreSQL，AI自动生成的Compose文件里就不会出现latest标签和硬编码的密码。

3.3 质量关卡：交付前的最后检查

最后，Quality Gates是一个检查清单，确保交付物是完整的、可运行的：

## Quality Gates - [ ] Every service has a `restart: unless-stopped` or `restart: always` policy. - [ ] All persistent data paths are mapped to named volumes or bind mounts. - [ ] Traefik labels are present for any web service (if using Traefik). - [ ] No hardcoded secrets; all sensitive data is in `.env` or external config. - [ ] `docker-compose config` runs without errors (validates YAML).

这相当于给AI布置了一个“任务完成确认”步骤。在AI给出最终答案后，它可以（或用户可以让它）依据这个清单自行检查一遍输出。这极大地提高了输出结果的可靠性和可用性。

4. 技能库的实战应用：如何集成与高效使用

4.1 安装与配置：无缝融入你的工作流

这个技能库的设计目标是与工具解耦。虽然我主要适配Claude Code，但其纯Markdown的格式使得它可以被任何能读取文本文件的AI工具使用。

对于Claude Code用户，安装最简单：

# 克隆整个技能库到Claude的技能目录 git clone https://github.com/drewid74/ai_skills.git ~/.claude/skills/ai_skills

之后，在Claude Code的聊天界面，输入/skills list，你应该能看到一长列技能，比如docker-selfhost、security-engineer等。它们现在处于“待命”状态。

技能的路由是语义驱动的。你不需要手动输入/docker-selfhost来调用它。当你正常描述问题，比如：“我在TrueNAS上跑的一个Jellyfin容器挂了，日志显示权限错误，怎么办？” 系统会自动从你的句子中识别出“容器”、“权限错误”等关键词，与技能描述中的“my container won't start”等短语匹配，从而在后台静默加载docker-selfhost技能。此时AI的回复，就会基于该技能中的身份、默认栈和决策框架来生成，它会优先检查卷的挂载权限、容器内用户映射等。

你也可以按需挑选技能。如果你只对某几个领域感兴趣，可以只复制对应的文件夹：

cp -r ai_skills/docker-selfhost ~/.claude/skills/ cp -r ai_skills/security-engineer ~/.claude/skills/ cp -r ai_skills/github-workflow ~/.claude/skills/

对于其他工具（如Cursor、Windsurf），原理类似。你需要找到该工具加载自定义上下文或“知识”的目录，通常在其配置文档中会说明。将技能文件放在对应的路径下即可。技能文件本身是纯文本，不依赖任何特定运行时。

4.2 跨平台能力目录：一张通用的AI能力地图

一个很实际的问题是：这些技能是为Claude优化的，我在ChatGPT或Gemini里能用吗？为了回答这个问题，我创建了跨平台参考目录。

在项目根目录，你会找到几个文件：

• claude_capabilities_catalog.md: 详细列出了Claude原生支持的工具、MCP服务器、以及本技能库的所有技能和触发短语。
• chatgpt_capabilities_catalog.md和gemini_capabilities_catalog.md: 这是等效的能力映射。虽然你不能直接把.md文件喂给ChatGPT，但这个目录告诉你，针对“部署Docker Compose”这个任务，在ChatGPT里你应该如何描述问题、提供哪些上下文信息，才能获得接近专用技能指导的效果。

最有价值的是cross_agent_skills.md。它本身就是一个“元技能”或“审计提示”。你可以把这个文件的内容发送给任何一个AI助手（包括Claude、ChatGPT、Gemini，甚至本地运行的Ollama模型），它会指导该AI分析自身的能力和知识边界，然后为你生成一份针对当前对话的、个性化的“技能目录”。这相当于为任何AI模型临时赋予了一种自省和结构化输出能力，极大地提升了复杂任务协作的效率和可靠性。

4.3 实战场景串联：从问题到部署的完整旅程

让我们看一个从问题触发到最终解决的完整例子，感受多个技能如何协同工作。

场景：我想在家庭服务器上部署一个自托管的代码仓库（Forgejo），并配置CI/CD流水线，同时确保安全。

1. 触发“基础设施”技能：我向AI描述：“我想在家里的Proxmox虚拟机里部署一个Forgejo，用Docker跑。” 这会触发docker-selfhost和proxmox-k3s-infra技能。AI会基于技能，建议我：在Proxmox上创建一个Ubuntu LXC容器，在里面安装Docker和Compose，然后提供一个标准的、带Traefik标签和PostgreSQL数据卷的docker-compose.yml文件。

2. 触发“安全”技能：我接着问：“怎么保证这个Forgejo实例的安全？” 这会触发security-engineer技能。AI会基于OWASP Top 10的检查点，给出建议：为Forgejo和PostgreSQL容器创建非root用户；在Traefik中配置安全头部（如HSTS、CSP）；建议设置防火墙规则，只允许从内部网络访问SSH和数据库端口；提醒我定期更新镜像。

3. 触发“CI/CD”技能：我继续：“现在我想为我的一个项目设置自动化测试和部署，推送到Forgejo就触发。” 这会触发cicd-pipeline和github-workflow技能（虽然用的是Forgejo，但工作流语法是通用的）。AI会生成一个.forgejo/workflows/test-and-deploy.yml文件，里面包含检出代码、运行测试、构建Docker镜像、推送到私有Registry等步骤，并提醒我配置仓库密钥（Secrets）。

4. 触发“代码质量”技能：我最后要求：“帮我审查一下这个工作流文件有没有问题。” 这会触发code-reviewer技能。AI会检查YAML语法、步骤的幂等性、密钥的使用是否安全、是否有不必要的步骤，并可能建议添加缓存（actions/cache）以加速构建。

整个过程中，我并没有手动切换技能。AI根据我对话的自然语义，在后台动态加载了最相关的技能上下文。每个技能只贡献了约1K Token的精准知识，却共同支撑起了一个从基础设施到应用部署再到安全运维的复杂对话。这就是高信号密度技能库在真实工作流中带来的流畅体验。

5. 开发与贡献：如何打造你自己的“精悍”技能

这个技能库是开放的，我也鼓励你根据自己的技术栈和需求来定制或贡献技能。贡献的核心原则就是：追求极致的信号密度和实战价值。

5.1 技能创作模板详解

创建一个新技能，就是创建一个以技能名命名的文件夹，里面放一个SKILL.md文件。文件结构必须严格遵循模板：

1. YAML Frontmatter (前端元数据)：

   --- name: your-skill-name description: "Use this when: [短语1], [短语2], [短语3]" ---

   • name: 使用短横线分隔的小写单词。
   • description: 这是最重要的部分。用逗号分隔的“问题描述”或“意图短语”。想象用户会怎么问。例如，对于一个“日志管理”技能，可以是：“Use this when: my logs are too verbose, how to centralize logs, set up log rotation, parse application logs for errors”。

2. Identity (身份)：三句话模板。

   • 第一句：You are a [领域] expert.
   • 第二句：You prioritize [核心方法/原则].
   • 第三句：You never [绝对禁忌].
   • 例如：You are a cloud cost optimization engineer. You prioritize identifying and eliminating idle resources. You never recommend downsizing without performance data.

3. Stack Defaults (技术栈默认项)：4-8行的表格。列出在该领域你首选的工具链和理由。这能极大减少AI在基础选型上的犹豫。

   • Layer (层级)：如“CI Server”, “Testing Framework”, “Monitoring”。
   • Choice (选择)：如“GitHub Actions”, “pytest”, “Prometheus + Grafana”。
   • Why (原因)：简短有力，如“Widely adopted, free for public repos”, “Fixture-rich, great for Python”, “Time-series native, powerful query language”。

4. Decision Framework (决策框架)：技能的“逻辑引擎”。组织成几个### When to...的小节，每个小节下用- If [条件] → [动作]的列表。

   • 条件要具体、可判断。
   • 动作要直接、可操作。
   • 例如，在database-architecture技能中：

     ### When to add an index - If a query is slow (`EXPLAIN ANALYZE` shows Seq Scan) and filters on a specific column frequently → add a B-tree index on that column. - If you have a query with `WHERE a = ? AND b > ?` → consider a composite index on `(a, b)`.

5. Anti-Patterns (反模式)：4-6行的表格。这是经验的精华。列出该领域新手最常犯的2-3个致命错误和2-3个常见低效做法。

   • Don't (禁止)：具体的错误行为。
   • Why (原因)：解释为什么这是错的，会带来什么后果。
   • Do Instead (正确做法)：给出明确的替代方案。
   • 例如，在llm-inference-stack技能中，一定会有：“Don't load a full FP16 model if VRAM is limited. Why: Will cause OOM errors and crash. Do Instead: Use GGUF quantization (Q4_K_M) or AWQ/GPTQ.”

6. Quality Gates (质量关卡)：4-6个复选框。这是交付前的检查清单。每个检查项都应该是客观、可验证的。

   • 例如：[ ] All external API calls have error handling and retries.
   • [ ] Configuration is loaded from environment variables, not hardcoded.

5.2 贡献流程与质量把关

当你写好一个技能后，可以通过GitHub提交Pull Request。为了保持库的整体质量，我在评审时会用几个“灵魂问题”来检验：

• 决策密度：这个技能是否包含了真正的“If-Then”决策规则？还是仅仅在描述概念？
• 避坑价值：反模式表格是否抓住了该领域Top 3的常见错误？能否让一个开发者在凌晨两点处理故障时避开大坑？
• 普适性：技能中是否避免了硬编码的个人环境信息（如具体的IP、域名）？是否使用了<PLACEHOLDER>来表示变量？
• 触发精准：描述中的“Use this when”短语，是否是真实用户会说的“人话”？能否准确匹配到意图？

一个优秀的技能，读起来应该像一份紧急情况下的“处置预案”，而不是一篇维基百科文章。它应该让AI在相关问题上，反应更快、判断更准、输出更稳。

6. 避坑指南与效能最大化技巧

在长期使用和迭代这个技能库的过程中，我积累了一些非常重要的经验教训，这些往往不会写在正式的文档里。

6.1 技能编写与维护的常见陷阱

陷阱一：把技能写成教程。这是最容易犯的错误。总想解释“为什么Docker要用Compose”，但这恰恰是浪费Token。技能的用户是AI，它已经具备了这些基础知识。你的任务是引导它应用知识，而不是传授知识。检查方法：删掉所有以“Docker is a...”、“Compose allows you to...”开头的句子。

陷阱二：决策条件过于模糊。比如“如果性能很重要 → 使用缓存”。这对AI来说无法操作。必须具体化：“如果API响应时间超过200ms，且数据变化频率低于每小时一次 → 在应用层实现Redis缓存，并设置5分钟TTL。”

陷阱三：忽略版本兼容性。在Stack Defaults里指定了工具，但没指定版本。比如“Use Terraform”。结果AI可能给出了使用最新版HCL语法的代码，而你的生产环境还锁在旧版本。一定要指定主流稳定版本，如“Terraform v1.5+ (or OpenTofu)”。

陷阱四：反模式不痛不痒。只列出“不要写低效查询”这种大而化之的条目。好的反模式应该具体到让人看了“心头一紧”。例如：“Don't useSELECT *in application code. Why: Wastes network I/O, breaks on schema changes, makes query optimization harder. Do Instead: Explicitly list required columns.”

6.2 使用技巧：让AI成为你的“肌肉记忆”

1. 组合触发：不要孤立地使用技能。很多复杂任务需要多个技能联动。在你的初始提示中，可以同时描述多个方面。例如：“帮我设计一个后端API，它需要处理高并发，并且数据要持久化到PostgreSQL。” 这可能会同时触发api-integration（高并发设计）、database-architecture（PostgreSQL优化）和quality-test-engineer（压力测试）技能。

2. 主动纠正与教学：如果AI基于技能给出的方案不符合你的特定环境（比如公司强制用Nginx而不是Traefik），不要直接废弃它的建议。而是告诉它：“在我的环境里，我们使用Nginx作为反向代理，请基于这个约束重新给出配置。” 这相当于你在“训练”AI，让它下次在类似情境下能做得更好。优质的AI助手会从这次交互中学习。

3. 善用“质量关卡”进行复盘：在AI给出方案后，你可以手动（或让AI自己）对照技能文件中的“Quality Gates”逐项检查。这不仅是对当前方案的验收，更是一个极好的学习过程。你会发现哪些检查项总是被忽略，这也许意味着你的技能需要补充新的反模式，或者你的团队存在普遍的认知盲区。

4. 为技能创建“别名”或“快捷短语”：在一些AI工具中，你可以配置自定义快捷键或别名。例如，将“检查安全”映射为自动加载security-engineer技能。这能进一步减少你的输入成本，让技能调用变得像条件反射一样自然。

这个ai_skills项目本质上是一个“共识编码器”。它将我个人（以及社区贡献者）在特定领域的经验、偏好和避坑指南，编码成了一种AI能高效理解的格式。它不能替代你的专业知识，但能让你专业知识的“调用接口”变得无比顺畅。当你不再需要向AI反复解释你的技术栈选型、你的部署哲学、你踩过的那些坑时，你和AI的协作就真正进入了心流状态——你思考战略和架构，它高效无误地执行战术和实现。这，就是人机协同该有的样子。