1. 项目概述AI技能库的工程化实践如果你和我一样每天都要和Claude、Cursor这些AI编程助手打交道那你肯定也遇到过这样的烦恼每次想让AI帮你处理一个稍微复杂点的任务比如搭建一个Docker Compose服务栈或者设计一个数据库迁移方案你都得在对话里重新解释一遍你的技术栈偏好、最佳实践和要避开的坑。这就像每次开车去同一个地方都得重新看一遍导航既浪费时间又消耗宝贵的上下文窗口Context Window令牌数。drewid74/ai_skills这个项目就是来解决这个问题的。它不是一个普通的代码库而是一个高度结构化、极度精简的“AI技能库”。简单来说它把开发者或者说AI工程师在特定领域如基础设施、软件工程、安全运维的专家经验压缩成一个个约75行代码的Markdown文件。每个文件都遵循一个固定的模板包含了身份定义、技术栈默认选择、决策框架、反模式和质量门禁。你可以把它看作是给AI助手安装的“专业插件包”让它在处理特定任务时能立刻切换成该领域的专家模式给出更精准、更符合你团队习惯的答案。这个项目最吸引我的是它对“信号密度”的极致追求。最初的版本v1有47个文件近2万行全量加载会占用约24万令牌。而现在的v2版本精炼到35个技能总共只有2531行全量加载仅需约3.7万令牌单次技能调用更是降到约1050令牌。这意味着在同样的上下文预算下AI能“记住”更多你当前项目的代码和对话历史而不是被冗长的技能描述所淹没。这对于我们这些需要AI深度参与复杂项目开发的工程师来说价值巨大。2. 核心设计理念从知识库到决策引擎2.1 为何是“技能”而非“文档”传统的知识库或文档其核心是“解释是什么”What。例如一份Docker文档会详细解释docker run的每一个参数。但AI技能库的设计哲学完全不同它的核心是“指导如何做”How和“决定何时做”When。它假设AI已经具备了基础的工具知识需要的是在具体场景下做出正确决策的框架。这体现在每个技能固定的五段式结构中身份Identity明确AI在激活此技能时所扮演的“角色”和必须遵守的核心原则、硬性约束。这设定了行为的基调。技术栈默认值Stack Defaults一个分层表格定义了在该领域内“默认情况下应该使用什么工具/方法以及为什么”。这避免了每次都要从零开始讨论技术选型。决策框架Decision Framework以“当……时就……”If/Then的格式列出了最常见的场景判断逻辑。这是技能库的“大脑”将模糊的用户需求映射到具体的操作。反模式Anti-Patterns一个“不要做 | 为什么 | 应该怎么做”的表格。它直接封装了该领域最常见的错误和教训是经验价值的集中体现。质量门禁Quality Gates一系列复选框定义了在任务完成前必须检查的事项。这确保了输出的结果不仅是能运行的更是符合生产环境标准的。这种结构迫使技能作者必须提炼出最精华、最具操作性的决策逻辑而不是堆砌叙述性文字。例如在docker-selfhost技能中你不会看到对Docker命令的复述但你会看到“如果服务需要持久化数据 → 必须使用命名卷named volume并明确挂载路径”这样的明确指令。2.2 语义路由与意图匹配另一个精妙的设计在于技能的“描述”Description字段。它不使用工具关键词列表如“Docker, Compose, volumes”而是使用自然语言的问题描述或意图短语如“my container keeps restarting”, “set up a self-hosted service”。这种设计让技能的触发机制从“关键词匹配”升级为“语义路由”。当用户在聊天窗口中输入“我的容器老是重启怎么办”时AI能更准确地匹配到docker-selfhost技能而不是仅仅因为提到了“容器”这个词。这大大提升了交互的自然性和准确性因为用户就是用这种方式描述问题的。2.3 通用化与可移植性项目强调“通用而非个人”。所有技能中都使用占位符如NAS_IP、API_KEY、POOL_NAME避免硬编码任何个人或特定环境的信息。这使得这些技能可以被任何开发者、在任何基础设施上复用。它提供的是经过验证的模式和决策框架而不是某个特定服务器的配置脚本。这种抽象层次的选择保证了技能库的广泛适用性和长期价值。3. 技能库的实战部署与应用3.1 环境准备与安装这个技能库的设计是与工具无关的它本质上是一堆遵循特定格式的Markdown文件。因此部署的核心就是把这些文件放到你的AI助手能够读取的特定目录下。主流工具的技能目录路径Claude Code / Claude Desktop:技能通常存放在~/.claude/skills/目录下。这是目前最主流的支持方式。Cursor:Cursor的技能机制可能内置或通过插件管理需要查阅其最新文档。一种常见模式是类似Claude在用户配置目录下寻找skills文件夹。Windsurf / Codex CLI:这些工具如果支持外部技能也会有类似的配置目录。务必以官方文档为准。通用方法:对于任何宣称支持“MCPModel Context Protocol服务器”或“自定义技能”的工具你都可以尝试将技能库放在一个约定俗成的skills目录并在工具设置中指向该路径。安装操作实录我个人的工作流是在~/.claude/skills/下为不同类别的技能创建子目录便于管理。以下是具体步骤# 1. 进入Claude的技能目录如果不存在则创建 mkdir -p ~/.claude/skills cd ~/.claude/skills # 2. 克隆整个技能库仓库建议用一个有意义的文件夹名 git clone https://github.com/drewid74/ai_skills.git drewid74_skills # 3. 可选但推荐建立清晰的目录结构。例如我习惯按领域链接 ln -s ~/.claude/skills/drewid74_skills/infrastructure-and-homelab ~/.claude/skills/infra ln -s ~/.claude/skills/drewid74_skills/software-engineering ~/.claude/skills/se # 这样我可以通过 /infra/docker-selfhost 来调用更清晰。注意符号链接ln -s在大多数情况下工作良好但极少数工具可能无法正确解析链接。如果遇到技能加载失败的问题可以尝试直接将所需的SKILL.md文件复制到目标目录。安装后的验证安装完成后你通常需要在AI助手中重新加载技能列表。在Claude Desktop中你可以尝试输入指令/skills list如果配置正确你应该能看到已加载的技能列表其中包含drewid74_skills目录下的各个技能。有些工具可能需要重启客户端才能识别新技能。3.2 核心技能解析与调用模式技能库的威力在于组合使用。下面我以开发一个需要部署的全栈Web应用为例展示如何串联多个技能。场景我需要构建一个带有React前端、Node.js后端和PostgreSQL数据库的应用并配置完整的CI/CD流水线最终部署到自己的服务器上。第一步项目脚手架与SDLC软件开发生命周期我会首先显式调用full-sdlc技能。/full-sdlc 用户初始化一个名为“my-web-app”的全栈项目使用React Node.js PostgreSQL技术栈。此时AI会基于该技能的决策框架可能建议使用create-react-app初始化前端用express-generator或类似的脚手架创建后端并建立docker-compose.yml用于本地开发环境包含PostgreSQL服务。它还会建议分支策略如Git Flow或GitHub Flow和初始的.gitignore文件。第二步数据库设计与架构在编写后端模型时我会切入database-architecture技能。用户我需要为“用户”和“文章”设计数据库模式并考虑查询性能。 由于对话中涉及“数据库模式”、“查询性能”等意图短语AI可能会自动或在我提示下应用database-architecture技能技能会引导AI思考使用UUID还是自增ID作为主键如何为user_id和created_at字段建立复合索引是否使用ORM如Prisma、Sequelize以及如何编写可逆的迁移文件第三步API与安全集成设计API时api-integration和security-engineer技能会发挥作用。用户设计用户注册和登录的RESTful API端点。api-integration会指导使用JWT进行无状态认证、实现请求速率限制、以及为外部服务调用设计重试和熔断机制。security-engineer则会强制加入输入验证、防止SQL注入、确保密码加盐哈希存储使用bcrypt并提醒不要将敏感信息记录到日志中。第四步容器化与部署准备当需要打包应用时切换到docker-selfhost技能。/docker-selfhost 用户为这个全栈应用编写生产环境的Dockerfile和docker-compose.prod.yml。技能会输出多阶段构建的Dockerfile以减小镜像体积在compose文件中定义网络、配置命名卷用于数据库持久化并设置服务依赖关系和健康检查。它还会提醒反向代理如Traefik或Nginx的配置要点。第五步配置CI/CD流水线最后使用cicd-pipeline技能来构建自动化流程。/cicd-pipeline 用户为这个项目设置GitHub Actions流水线包括代码检查、测试、构建和部署到我的自有服务器。技能会生成一个.github/workflows/deploy.yml文件包含linting、单元测试、集成测试、构建Docker镜像、推送到私有Registry以及通过SSH连接到生产服务器执行更新脚本的步骤。它还会强调密钥Secrets的安全管理和回滚策略。通过这样串联技能AI从一个通用的代码助手变成了一个理解你完整技术栈和工程规范的“虚拟资深工程师”在每个环节都给出高度情境化且一致的专家建议。4. 技能创作指南打造你自己的专家模块4.1 技能模板深度拆解要贡献或为自己创建技能必须吃透这个约75行的模板。每一部分都有其明确的写作目标。1. YAML Frontmatter前言这是技能的“触发器”。name是技能的唯一标识。description是重中之重必须用意图短语来写。好的描述应该覆盖用户遇到问题时的自然表达。错误示例“Docker, Compose, container management”这是关键词列表正确示例“Use this when: my container keeps restarting, set up a self-hosted service, my volumes are not persisting, deploy with Docker Compose”这是问题描述2. Identity身份用三句话精确定义角色。句式“You [are/act as] [角色]. [核心原则]. Never [硬性约束].”示例来自security-engineer“You are a paranoid security engineer. Assume every input is malicious, every dependency is compromised. Never suggest disabling a security control for convenience.”写作要点“核心原则”是行为的北极星“硬性约束”是不可逾越的红线。这为后续所有决策定下了基调。3. Stack Defaults技术栈默认值用表格列出分层的技术选择。这避免了每次的重复讨论。结构| Layer | Choice | Why |示例LayerChoiceWhy容器编排Docker Compose单机部署简单声明式配置开发与生产环境一致。反向代理Traefik自动服务发现与SSL证书管理与Docker原生集成。数据持久化命名卷Named Volumes生命周期独立于容器便于备份和迁移。配置管理环境变量 .env文件将配置与代码分离便于不同环境切换。写作要点“Why”一栏要简洁有力体现的是经过权衡的工程判断而不是功能罗列。4. Decision Framework决策框架这是技能的灵魂必须是可执行的“如果-那么”规则。格式### When to [采取某个行动或使用某个方案]下面跟- If [条件] → [动作/建议]示例来自docker-selfhost### When to use a bind mount vs a volume - If you need to provide configuration files or code for development → use a bind mount (./app:/app) - If you need persistent data (database files, uploads) → use a named volume (db_data:/var/lib/postgresql/data)写作要点条件要具体、可判断。动作要明确、可操作。每条规则都应解决一个常见的决策点。5. Anti-Patterns反模式封装最常见、最致命的错误。格式为| Dont | Why | Do Instead |。示例DontWhyDo InsteadRun containers as root增加安全风险容器逃逸可能导致主机被控制。UseUSERdirective in Dockerfile to run as non-root user.Uselatesttag in production导致版本不可控更新可能引入不兼容变更。Use explicit version tags (postgres:15-alpine).写作要点“Why”要一针见血指出危害。“Do Instead”要给出立即可行的正确方案。6. Quality Gates质量门禁任务完成前的强制检查清单。格式- [ ]开头的复选框列表。示例[ ] All services have health checks configured.[ ] No secrets are hardcoded in Dockerfiles or Compose files.[ ] Docker images are scanned for CVEs (e.g., usingdocker scan).[ ] Backup strategy for named volumes is documented.写作要点每一条都应该是客观、可验证的确保输出达到生产就绪Production-Ready标准。4.2 从零创作一个技能以“Serverless Function部署”为例假设我要创建一个关于在AWS Lambda或Vercel等平台部署无服务器函数的技能。第一步定义核心场景与意图思考开发者在什么情况下需要这个技能“我需要部署一个API端点”、“我的函数在本地运行正常但上线失败”、“如何管理无服务器函数的依赖和环境变量”、“函数冷启动太慢怎么办”。将这些写成description。第二步填充Identity“You are a serverless operations specialist. Optimize for cold start performance, cost efficiency, and observability. Never ignore function timeouts and memory configuration.”第三步确定Stack Defaults根据主流实践填充表格。例如Layer可以是“Runtime”、“部署工具”、“监控”、“本地测试”。Choice对应“Node.js 18.x (LTS)”、“Serverless Framework”、“AWS CloudWatch Logs X-Ray”、“serverless-offline plugin”。Why栏写明选择理由如“长期支持稳定的API”、“多云支持配置即代码”、“AWS原生集成链路追踪”、“本地模拟快速迭代”。第四步提炼Decision Framework这是最难也最有价值的部分。需要总结关键决策点### When to choose provisioned concurrency### When to split a monolithic function### When to use environment variables vs. parameter store为每个点写下2-3条If/Then规则。第五步总结Anti-Patterns收集常见坑点如将大文件打包进部署包、在函数内创建数据库连接池、忽略异步函数返回值导致提前终止等。填入表格。第六步设置Quality Gates列出部署前检查项函数超时设置是否合理、权限策略是否遵循最小权限原则、是否配置了告警、部署包大小是否超标等。完成这六步一个高度浓缩、即插即用的专家技能就诞生了。你可以用它来武装你的AI助手也可以提交PR到原项目惠及更多开发者。5. 高级技巧与生态集成5.1 技能的组合与嵌套调用真正的威力来自于技能的协同。AI可以在一个对话中根据上下文动态切换或组合多个技能。例如在调试一个部署失败的应用时对话可能同时涉及docker-selfhost查看容器日志、sre-operations-lead检查监控指标、security-engineer排查是否有安全策略阻拦和sequential_thinking进行根因分析。技能库为此提供了可能因为每个技能都足够轻量可以同时加载多个而不至于撑爆上下文窗口。在实践中我发现在复杂任务开始时可以主动告诉AI“请结合project_orchestrator和full-sdlc技能为我分解这个微服务项目的开发计划。”这能引导AI采用更结构化的思维方式来规划任务。5.2 与MCP模型上下文协议的协同MCP是Anthropic提出的一种协议允许AI模型安全地访问外部工具、数据和计算资源如数据库、文件系统、API。ai_skills项目中的mcp-server-dev技能就是教你如何开发MCP服务器的。技能库和MCP服务器是互补的技能Skills提供的是决策逻辑和知识框架。它们告诉AI“怎么想”和“怎么做决定”。MCP服务器MCP Servers提供的是执行能力和数据访问。它们赋予AI“动手操作”的能力比如读取文件、执行命令、查询数据库。一个理想的AI助手工作流是技能指导AI做出“需要查看最近一小时的错误日志”的决策然后AI通过一个“日志查询MCP服务器”来实际获取这些数据最后再运用sequential_thinking技能来分析这些日志找出问题根源。技能库是大脑中的“经验手册”而MCP是连接现实世界的“手和眼睛”。5.3 个性化与团队知识沉淀这个开源技能库是一个极佳的起点但最大的价值在于将其“内化”为你个人或团队的知识资产。1. 创建私有技能库你可以在公司内网搭建一个Git仓库存放你们团队特有的技能。例如一个company-auth-skill里面定义了你们内部统一的OAuth2流程、特定的用户模型字段和审计日志规范。一个aws-our-account-setup技能封装了公司AWS组织架构、网络VPC规划和安全组基线配置。2. 技能版本化与迭代像管理代码一样管理技能。当团队引入新技术比如从Webpack换到Vite或者从某次线上事故中吸取了教训“永远不要在数据库事务中调用外部HTTP API”就把这些更新到对应的技能文件中。通过Code Review流程来合并技能的修改确保知识的持续进化。3. 与新工具集成虽然项目主要面向Claude、Cursor但其纯Markdown的格式使其易于适配。你可以编写简单的脚本将技能库转换成其他AI平台如JetBrains AI Assistant、甚至是自定义的ChatGPT GPT所能接受的提示词格式。项目中的cross_agent_skills.md文件就提供了这种审计和转换的思路。6. 常见问题与效能提升在实际使用和推广这个技能库的过程中我和我的团队遇到过一些典型问题以下是我们的解决方案和心得。Q1: 技能加载了但AI好像没有调用它还是给出通用回答。原因A描述Description意图匹配度不高。检查技能的description字段是否使用了用户真正会说的“问题语言”而不是技术名词。尝试在提问时更贴近那些意图短语。原因B上下文窗口已满或技能优先级。如果对话历史非常长较早加载的技能可能被“挤出去”。尝试在开启新对话时先调用核心技能或者使用工具的“/skills reload”命令。有些工具允许为技能设置触发优先级或关键词。解决方案显式调用。如果自动触发不理想最直接的方式就是在对话开始时使用“/技能名”命令显式激活它例如/docker-selfhost。Q2: 技能中的建议和我们团队的实际技术栈不符怎么办解决方案Fork and Modify复刻并修改。这是开源项目的标准操作。不要直接修改克隆的仓库而是将其作为模板。复制你需要的技能文件修改其中的Stack Defaults和Decision Framework使其符合你们的标准。例如原技能用Traefik你们用Nginx那就改掉。然后将其放入你们自己的技能目录。这才是“通用模式”的正确使用方式——将其个性化。Q3: 如何评估一个自创技能的质量自我审查清单决策密度它是否包含了关键的If/Then选择一个没有决策逻辑的技能只是文档。反模式价值它列出的“Don‘t”是不是新手常犯、后果严重的错误能否帮人避开大坑凌晨两点测试想象一下在凌晨两点处理线上故障时这个技能给出的步骤是否清晰、准确、可靠到让你敢照着做是否通用是否避免了项目特定的路径、IP或密钥使用了占位符吗篇幅控制是否在75行左右做到了信息密度最大化有没有冗余的废话Q4: 技能库和传统的提示词Prompt工程有什么区别结构化 vs 非结构化技能库是高度结构化的“模块”有固定的章节负责身份、决策、检查。传统长提示词往往是一段自由文本结构松散容易在长对话中丢失重点。可组合性技能可以按需加载和组合。而一个巨大的、包含所有知识的“超级提示词”会浪费大量令牌且难以维护。可维护性技能以文件形式存在可以用Git进行版本管理、差异对比和协作更新。提示词通常保存在聊天记录或笔记里难以系统化地迭代。核心区别技能库的本质是工程化的、可复用的提示词模块它借鉴了软件工程中“模块化”、“高内聚低耦合”的思想来管理AI的上下文知识。效能提升心法从消费者到生产者不要只使用现有的技能。当你发现自己在某个领域反复向AI解释同样的规则时就是创建新技能的最佳时机。把这次解释的内容按照模板整理出来就是你的第一个技能。建立技能索引为你的私有技能库维护一个简单的README.md列出所有技能的名称、一句话描述和主要意图短语。这在技能数量增多后非常有用。与文档结合技能不是用来取代详细的技术文档的而是作为文档的“高速缓存”和“决策指南”。将技能中的Stack Defaults链接到公司内部的技术选型文档将Quality Gates链接到部署检查清单形成知识网络。这个项目代表了一种更先进的与AI协作的模式从临时的、重复的提示转向系统的、可积累的“能力注入”。它节省的不仅仅是每次对话的几百个令牌更是开发者最宝贵的认知资源让我们能从重复性的知识传递中解放出来更专注于创造性的问题解决。