1. 项目概述Agent Skills 技能库的深度解析与应用最近在折腾AI编程助手时发现了一个挺有意思的项目dortort/skills。这本质上是一个开源的“技能包”仓库专门用来教像Claude Code、Cursor这类AI编程代理如何执行特定的、复杂的任务。你可以把它理解为一个给AI用的“应用商店”或者“插件市场”只不过这里的“插件”是一套套标准化的指令集遵循一个叫Agent Skills的开放规范。这意味着你写好的一个技能理论上可以在支持这个规范的多个AI工具比如Claude Code、OpenAI Codex、Cursor、OpenCode里通用不用为每个平台重写一遍。这对于我们这些经常在不同AI助手间切换的开发者来说实用性直接拉满。这个仓库里目前包含了几个非常实用的技能覆盖了从学习研究、云基础设施到内容管理的多个场景。比如nlm-new-topic能帮你围绕一个主题自动生成一套完整的学习资料包包括研究摘要、幻灯片甚至视频脚本terraform技能则能指导AI按照严格的模块化原则和最佳实践来编写Terraform代码而youtube技能封装了YouTube Data API的复杂操作让AI能帮你处理视频上传、元数据更新这些繁琐工作。无论你是想提升学习效率、自动化运维流程还是管理数字内容这些技能都能显著降低使用AI完成复杂任务的门槛。接下来我会带你深入拆解这个技能库的运作机制、每个核心技能的具体玩法并分享如何从零开始编写和部署你自己的AI技能。如果你已经厌倦了每次都要给AI写长篇大论的提示词或者希望把一些重复性的复杂操作固化下来那么这个项目就是你一直在找的工具箱。2. Agent Skills 规范与生态深度解读2.1 什么是 Agent Skills 规范要理解dortort/skills的价值首先得弄明白它背后的Agent Skills 规范。这可不是某个厂商的私有协议而是一个由社区推动的开放标准旨在解决AI代理Agent能力扩展的碎片化问题。简单来说它定义了一种通用的、结构化的方式来“教”AI如何做事。你可以把每个Skill技能想象成一个高度特化的“工作说明书”或“标准作业程序”。它不仅仅是一段提示词而是一个包含元数据YAML Frontmatter和详细操作指南Markdown正文的完整包。元数据告诉AI这个技能叫什么、是干什么的而Markdown正文则用自然语言和示例一步步指导AI完成特定任务比如“如何提交ISC2 CPE学分”或“如何用Terraform创建符合最佳实践的AWS VPC”。这个规范的核心优势在于跨平台兼容性。一个遵循该规范编写的技能文件SKILL.md只要AI工具支持这个规范就能被识别和使用。这就好比写了一个遵循USB协议的U盘可以在电脑、电视、游戏机上即插即用无需为每个设备单独制作驱动。目前Claude Code、OpenAI Codex (Agent模式)、Cursor (部分版本) 和 OpenCode 都已宣布支持或兼容此规范形成了一个初具规模的生态。2.2 技能文件的结构解剖SKILL.md每个技能的核心都是一个名为SKILL.md的文件。它的结构非常清晰分为两部分第一部分YAML 前置元数据这部分用三个横线---包裹定义了技能的基本信息是AI工具识别和调用技能的关键。--- name: isc2-cpe-submission description: Submits ISC2 CPE credits on cpe.isc2.org for CISSP, CCSP, and other ISC2 certifications — single or batch submissions via Playwright user-invocable: true ---name(必需)技能的标识符通常使用短横线分隔的小写单词。它决定了在AI工具中调用的命令例如/dortort:isc2-cpe-submission。description(必需)对技能功能的简洁描述。这个描述至关重要因为它会帮助AI以及用户理解在什么场景下应该使用这个技能。好的描述应该包含目标、关键动作和可能的使用方式。user-invocable(可选)布尔值默认为true。如果设为true用户可以直接通过类似斜杠命令的方式触发这个技能如果设为false则这个技能可能仅作为其他技能的依赖或被AI内部调用。第二部分Markdown 指令正文元数据之后就是技能的“灵魂”——用Markdown编写的详细指令。这里才是真正“教学”发生的地方。高质量的技能正文会包含清晰的任务定义明确告诉AI要完成什么输入是什么期望的输出是什么。分步操作指南将复杂任务分解为逻辑清晰的步骤。例如对于提交CPE学分的技能步骤可能包括登录网站、定位提交表单、填写活动详情、上传证明文件、确认提交。上下文与约束说明执行任务所需的先决条件如需要已登录的会话、特定的环境变量、需要避免的错误如不要重复提交、以及输出格式的要求如生成JSON报告。示例与模板提供输入输出的具体例子这是降低AI理解偏差最有效的方法。比如提供一个CPE活动信息的JSON模板。错误处理与回退方案指导AI当遇到预期外情况如网页元素未加载、API返回错误时应该如何应对。注意编写技能指令时要假设AI是一个拥有强大执行能力但缺乏特定领域知识的新手。指令必须极度精确、无歧义并预见到各种边界情况。避免使用“可能”、“大概”这类模糊词汇。2.3 技能生态与相关资源dortort/skills并非孤例它处在一个正在快速成长的技能开发生态中。除了这个仓库还有几个重要的官方和社区资源anthropics/skills和openai/skills分别是Anthropic和OpenAI维护的官方技能示例库。它们是学习技能编写最佳实践的绝佳资料尤其是了解这两家巨头希望开发者如何为他们的AI构建能力。Agent Skills 官网 (agentskills.io)这是该规范的核心站点提供了完整的规范文档、集成指南以及“什么是技能”等概念性解释。对于想深入理解规范细节或为自己开发的AI工具添加技能支持的开发者来说这里是必读的。此外Anthropic发布的《The Complete Guide to Building Skills for Claude》是一份长达32页的详尽指南从技能规划、写作、测试到分发覆盖了全流程。它强烈建议在编写技能前进行“技能设计”明确技能的目标用户、使用场景、成功标准以及可能的失败模式这远比直接动手写Markdown要高效得多。3. 核心技能详解与实战应用场景dortort/skills仓库目前精选的技能都瞄准了真实、高频的需求。我们来逐一拆解它们的核心价值和使用方法。3.1 学习与知识管理技能nlm-new-topic 与 nlm-deepdive这两个技能是针对NotebookLMGoogle的实验性AI研究助手的强力扩展。NotebookLM本身允许你上传文档并与AI围绕其内容对话但这组技能将这个过程推向了自动化。nlm-new-topic一站式学习资料包生成器这个技能的野心很大。你只需要给它一个主题例如“量子计算基础”或“文艺复兴时期的艺术”它就能指挥AI代理完成以下全套工作研究自动搜索需结合网络搜索插件并筛选高质量的资料来源学术论文、权威文章、书籍章节。摘要与提炼将收集的资料导入NotebookLM并生成结构化的摘要、关键要点列表。多模态内容创作幻灯片生成一个可用于演示的PPT大纲或Markdown格式的幻灯片内容。视频脚本为制作解释性视频撰写分镜头脚本。信息图为每个学习单元Unit设计信息图的文字描述和数据结构。音频稿生成适合录制为播客或音频课程的文字稿。实战心得这个技能最适合需要快速构建某个新领域知识体系的场景比如准备一门内部培训课、制作一个科普视频系列或者为自己进入一个新赛道做学习规划。它的价值不在于替代深度阅读而在于高效搭建一个内容全面、结构清晰的“脚手架”极大节省了资料收集和初步整理的精力。nlm-deepdive专题深度挖掘工具如果说nlm-new-topic是搭建骨架那么nlm-deepdive就是填充血肉。它用于在一个已存在的NotebookLM笔记本中对某个子主题进行深度探索。例如你有一个关于“机器学习”的笔记本现在想深入研究“Transformer架构”。使用此技能AI会围绕“Transformer”进行专项研究补充新的资料到笔记本。生成该子主题的详细报告。并行创建针对该深度内容的衍生作品如专门的幻灯片、详细的图表说明。注意事项使用这两个技能需要你的AI代理具备文件读写权限以操作NotebookLM项目文件和网络搜索能力。首次运行可能会因为资料收集步骤而耗时较长。建议先在一个明确、范围适中的主题上测试以了解其输出质量和风格是否符合你的预期。3.2 开发与运维自动化技能terraform 与 cloudflare-iac这是面向开发者和运维工程师的“生产力核武器”。terraform基础设施即代码的AI协作者编写高质量的Terraform代码并不简单需要考虑模块化、版本兼容性、安全策略、状态管理等一系列问题。这个技能将一系列最佳实践固化成了AI的指令严格模块化指导AI将资源逻辑分组为可重用的模块而不是写成一个巨大的main.tf。版本锁定强调使用required_version锁定Terraform核心和Provider的版本确保可重复性。动态查询当AI不确定某个资源的正确参数时技能会指示它去查询最新的官方Provider文档而不是依赖可能过时的记忆。预提交检查在代码最终生成前会要求AI运行terraform fmt(格式化)、terraform init(初始化) 和terraform validate(验证) 来确保代码语法正确、配置有效。实操要点当你对AI说“帮我写一个在AWS上部署带有ALB和Auto Scaling组的ECS集群的Terraform代码”时激活此技能后AI产出的将不再是一堆堆砌的资源块而是一个结构清晰的目录包含modules/、environments/等代码风格统一并且开头就有版本约束。这能直接将代码质量从“能用”提升到“可维护”的级别。cloudflare-iacCloudflare环境的TerraformWrangler混合实践Cloudflare的生态比较特殊一部分配置如Worker、Pages用其命令行工具Wrangler管理更方便另一部分如DNS记录、防火墙规则用Terraform更强大。这个技能解决了如何将两者优雅结合的难题。资源桥接指导AI设计项目结构使Terraform管理的资源如DNS记录和Wrangler管理的资源如Worker脚本能相互引用和协作。CI/CD流水线设计提供如何设置GitHub Actions或GitLab CI的示例实现Terraform Plan/Apply和Wrangler部署的自动化编排。项目脚手架生成一个标准的项目目录结构清晰分离不同工具管理的部分降低后续维护的认知负担。踩坑记录在混合使用Terraform和Wrangler时最大的挑战是状态管理和密钥API Token的安全传递。这个技能会提醒你不要将Cloudflare API Token硬编码在Terraform代码或CI脚本里而应使用环境变量或秘密管理服务如Vault、GitHub Secrets。同时要明确划分职责避免Terraform和Wrangler尝试管理同一个资源导致冲突。3.3 实用工具类技能isc2-cpe-submission 与 youtube这两个技能解决了非常具体、且有些繁琐的日常事务。isc2-cpe-submission安全认证学分的自动化提交对于持有CISSP、CCSP等ISC2认证的专业人士每年需要积累和提交持续专业教育CPE学分。手动在cpe.isc2.org网站上提交尤其是批量提交非常耗时。这个技能利用Playwright一个浏览器自动化框架来模拟这一过程。单次提交指导AI编写Playwright脚本自动填写活动名称、日期、学时、描述等表单字段。批量提交更强大的功能是它可以读取一个结构化的数据文件如CSV或JSON然后循环处理自动提交所有条目。错误处理脚本会包含检查点例如确认登录成功、等待页面加载、捕获提交失败的情况并记录日志。重要警告使用此类自动化脚本提交官方学分需格外谨慎。务必在提交前仔细核对脚本填充的所有信息是否准确无误。首次使用建议在测试模式如果有下运行或先提交一个不重要的学分进行验证。确保你的活动确实符合ISC2的CPE政策。自动化工具不应对政策的理解负责。注意账号安全妥善保管用于自动登录的凭据。youtube频道与视频管理的API封装YouTube Data API功能强大但略显复杂。这个技能为AI提供了一个高级“控制器”使其能轻松执行一系列频道管理操作视频上传与元数据设置从本地上传视频并同时设置标题、描述、标签、分类、缩略图、播放列表、发布时间预定发布等。批量操作通过读取CSV文件批量更新多个视频的元数据这在做频道内容优化时非常有用。评论审核获取视频评论列表并根据简单规则如包含特定关键词进行删除或标记垃圾评论。内容搜索与分析在频道内搜索视频或获取视频的基本分析数据。应用场景对于内容创作者或频道运营者你可以让AI帮你完成以下工作将一周制作好的视频按计划定时发布在节日期间批量将旧视频标题和描述更新为节日相关关键词快速清理大量垃圾评论。这相当于为你配备了一个不知疲倦的YouTube运营助理。4. 技能的安装、管理与自定义开发4.1 多种安装方式详解根据你使用的AI代理工具安装技能的方式略有不同。首选方案Claude Code 插件市场最便捷如果你的主力工具是Claude Code这是最推荐的方式它实现了集中化的技能管理。# 1. 添加 dortort/skills 仓库作为插件市场源 claude plugin marketplace add https://github.com/dortort/skills # 2. 安装你需要的技能可一次安装多个 claude plugin install isc2-cpe-submission nlm-new-topic terraform安装后在Claude Code的聊天窗口中输入/就会看到dortort:开头的命令列表例如/dortort:terraform直接调用即可。手动安装通用方法对于其他支持Agent Skills规范的工具或者你想进行自定义修改可以采用手动复制的方式。关键在于将技能目录放到正确的路径下Claude Code:全局安装对所有项目生效:~/.claude/skills/项目本地安装仅当前项目:项目根目录/.claude/skills/OpenAI Codex (Agent):~/.agents/skills/或./.agents/skills/Cursor:./.cursor/skills/(通常只支持项目本地)OpenCode:~/.config/opencode/skills/它也能自动识别上述Claude和Codex的路径。操作示例# 为当前项目的Claude Code安装 terraform 技能 mkdir -p .claude/skills # 确保目录存在 cp -r /path/to/dortort-skills/skills/terraform .claude/skills/ # 或者从GitHub直接克隆到本地路径 git clone https://github.com/dortort/skills.git cp -r skills/terraform ~/.claude/skills/4.2 如何编写你自己的第一个技能当你发现某个重复性任务没有现成技能时就是自己动手的时候了。编写一个技能比想象中简单。步骤一规划与设计在动手写代码指令之前先回答几个问题技能目标这个技能最终要完成什么用一句话描述。目标用户是谁什么角色的AI使用这个技能需要它具备什么基础能力如文件访问、网络搜索、API调用输入与输出用户需要提供什么信息输入技能最终交付什么成果输出主要步骤将任务分解成AI可以顺序执行的、离散的步骤。潜在陷阱过程中最容易出错的地方是哪里如何让AI避免或处理这些错误步骤二创建技能目录与文件在你的技能仓库或本地测试目录中创建一个以技能名命名的文件夹并在其中创建SKILL.md文件。my-awesome-skill/ └── SKILL.md步骤三编写 SKILL.md 文件参考以下框架填充内容--- name: generate-api-client # 技能名使用短横线连接 description: Generates a type-safe API client SDK in TypeScript from an OpenAPI 3.0 specification file. Supports axios and fetch adapters, and includes error handling and request/response interceptors. user-invocable: true --- # Generate TypeScript API Client ## Goal Create a fully-featured, type-safe TypeScript client library from a provided OpenAPI 3.0 specification (YAML or JSON). The client should be ready for use in a modern frontend or Node.js project. ## Prerequisites - The user must provide the path to a valid OpenAPI 3.0 spec file (openapi.yaml or openapi.json). - Node.js and npm must be available in the environment to install the code generation tool. ## Steps 1. **Validate Input**: First, check if the provided file path exists and is a valid YAML/JSON file. If not, ask the user to provide the correct path. 2. **Choose Generator Setup**: - Recommend using openapi-typescript-codegen for its strong TypeScript support. - Check if its installed globally (npm list -g openapi-typescript-codegen). If not, install it using npm install -g openapi-typescript-codegen. 3. **Generate Client Code**: - Run the generation command. Provide the user with the exact command based on their input file and desired options. - **Example Command**: openapi -i ./openapi.yaml -o ./src/client --name ApiClient --client axios - **Key Parameters**: - -i: Input spec file path. - -o: Output directory for the generated client. - --name: The name of the exported client class. - --client: Choose axios or fetch as the HTTP client. 4. **Post-Generation Actions**: - Guide the user to check the generated src/client directory. - Suggest reviewing the main ApiClient.ts file and the generated models. - Recommend running npm install in the project root to add the required dependencies (axios if chosen). ## Example **User Input**: Generate a client from the ./api-spec.yaml file, use axios, and output to ./lib/api. **Your Action**: 1. Validate ./api-spec.yaml. 2. Ensure openapi-typescript-codegen is installed. 3. Execute: openapi -i ./api-spec.yaml -o ./lib/api --name ApiClient --client axios 4. Inform the user that generation is complete and remind them to install axios if not already present. ## Notes Warnings - Always generate the client into a **new or empty directory** to avoid overwriting existing files. - If the OpenAPI spec uses complex oneOf/anyOf schemas, the generated types might need manual adjustment. - For large specs, generation may take a minute. Be patient.这个示例技能展示了如何从OpenAPI规范生成TypeScript客户端。它明确了目标、前提条件、分步指令、示例以及重要注意事项。步骤四测试与迭代将你的技能目录放到对应的AI代理技能路径下如~/.claude/skills/generate-api-client然后在AI对话中尝试调用它如输入/generate-api-client或相关指令。观察AI的执行过程是否与预期相符根据结果反复调整SKILL.md中的指令使其更加清晰、健壮。4.3 技能开发的高级技巧与避坑指南模块化与组合复杂的技能可以拆分成多个子技能。例如一个“部署全栈应用”的技能可以调用“生成Dockerfile”、“编写K8s Manifest”、“配置CI/CD”等子技能。在技能指令中可以指导AI按顺序调用这些子技能。上下文感知优秀的技能应该能感知当前的工作环境。例如一个Git操作技能应该先检查当前目录是否是一个Git仓库而不是盲目执行git命令。提供逃生舱口在指令中告诉AI如果遇到无法解决的错误或不确定的情况应该停止并询问用户而不是继续执行可能导致破坏性后果的操作。测试驱动开发借鉴Anthropic和OpenAI指南中的建议可以为技能创建“评估Evals”。即准备一组标准的输入和期望的输出用来验证技能在不同场景下的表现是否稳定。这能极大提升技能的可靠性。版本控制你的技能将你的技能目录置于Git仓库中管理。这样你可以跟踪修改、创建分支尝试新想法并方便地与他人协作或分享。编写技能是一个与AI协作模式深度磨合的过程。一开始可能觉得约束AI的行为很困难但当你掌握了如何清晰、无歧义地表达指令和约束后你会发现AI的执行力和一致性远超预期真正成为一个得力的、可编程的合作伙伴。