概述

SKILL.md示例，取自~/.cursor/skills-cursor/shell/SKILL.md：

---
name: shell
description: >-
  Runs the rest of a /shell request as a literal shell command. Use only when
  the user explicitly invokes /shell and wants the following text executed
  directly in the terminal.
disable-model-invocation: true
---
# Run Shell Commands

Use this skill only when the user explicitly invokes `/shell`.

## Behavior

1. Treat all user text after the `/shell` invocation as the literal shell command to run.
2. Execute that command immediately with the terminal tool.
3. Do not rewrite, explain, or "improve" the command before running it.
4. Do not inspect the repository first unless the command itself requires repository context.
5. If the user invokes `/shell` without any following text, ask them which command to run.

## Response

- Run the command first.
- Then briefly report the exit status and any important stdout or stderr.

都由两层组成：

• 元数据：yaml元数据，两个必填字段：name、description；后者写明触发条件。可选字段（无法穷尽列举）：
  • allowed-tools：允许使用哪些工具
  • context：需要加载的上下文文件
  • user-invocable：是否可被用户直接调用
  • disable-model-invocation：
• 正文

和系统提示词(System Prompt)的区别：提示词是全局的、永久加载；技能是模块化、按需加载。

和MCP区别：MCP是能力接口，Skill是知识和流程。

Skills利用LLM的三个底层特性：指令遵循、上下文学习、条件触发，所以效果比提示词好。

特性	作用	对应Skil的哪部分
指令遵循	AI会认真执行结构化指令	执行流程(Markdown正文)
上下文学习	AI通过示例理解你的标准	示例和约束条件
条件触发	在对的时间加载对的技能	description中的触发条件

SkillHub已经有几万条技能，如何找到满意的高质量技能，下面给出一些参考的挑选规则：

• 触发条件清晰：元数据里when字段或description里写得很明确：什么时候该被激活；
• 执行步骤可验证：Skil里写的每一步，你应该能看到AI确实在执行；
• 上下文占用合理：每个被加载的Skil都会占用AI的上下文窗口。500到2000字是最佳范围；
• 有用户确认环节：好的Skil在关键决策点会暂停，等你确认后再继续。比如选题Skil生成3个方向后让你选，而不是自己替你选一个直接开写。特别是涉及文件操作、发送消息这类不可逆的动作，没有确认环节的Skil不要用。
• 维护活跃：看最后更新时间和issue响应速度。AI工具的迭代非常快，一个半年没更新的Skil很可能已经和最新版的AI工具不兼容。在AgentSkill.sh上，star数和最近更新时间是两个最有参考价值的指标。

安装方式

• 手动安装：创建目录，放置文件
• 命令行安装：
  • 从市场安装：/learn @owner/skill-name
  • 从GitHub安装：git clone https://github.com/xxx/skill-name ~/.claude/skills/skill-name

不生效原因

• 路径、大小写、md格式、yaml格式
• 触发词不匹配、不精确、技能有待优化
• 互相冲突
• 上下文超限

触发机制有三种，优先级从高到低：

• 强制触发：用户显式调用，直接输入/weekly-report，Agent就加载对应Skill。最明确方式，零歧义；
• 显式触发：关键词匹配，基于description里写的触发词。用户需求命中某个技能里的description里声明的触发条件。匹配速度快，准确率高。
• 隐式触发：语义匹配，意图和某个Skill的description语义接近。Agent通过理解意图，判断加载某个Skill。匹配更智能，但偶尔会判断错。

执行流程：

• 触发识别：即上面的触发机制
• 加载SKILL.md：三种加载机制
• 理解指令：AI会解析整个SKILL.md，建立对任务的整体认知。先理解意图和约束，再规划行动
• 规划步骤：AI会把Skill里的流程拆解成可执行的步骤；
• 逐步执行
• 输出验证：AI会检查输出是否满足Skill里的约束，对质量要求高的任务很有用

Skill冲突：两个skill.md里的指令互相矛盾

解决思路：

• 设计不重叠的触发条件：不要让同一个关键词同时触发两个Skill；
• 在Skill里声明优先级：写明约束使AI遵守；
• 把流程拆成阶段：触发条件里加上阶段判断。

层级体系从最广到最窄：

• Enterprise级：公司统一管理，公司IT部门统一下发的Skills，所有员工的AI工具自动加载。如公司统一的代码规范、安全审查Skil。个人用户一般接触不到这个层级。
• Personal级：个人全局，存放在~/.claude/skills/目录，对所有项目生效，适合放通用型Skill：代码review标准、周报格式、写作审校规则。
• Project级：项目专属，存放在项目根目录的.claude/skills/下，只在当前项目生效。适合放项目特定的东西：部署流程、API规范、测试标准。团队协作时，把Skills提交到Git，团队共享。
• Plugin级：IDE插件提供，由IDE插件自动注入。如某些VSCode扩展会自带一些Skills。一般不需要手动管理。

设计

写一个能用的Skill不难，写一个好用的Skill，需要一些经验原则：

• 先确认再动手
• 边做边存
• 模块化可组合
• 给选择不给答案
• 放大你，而不是替代你

自动化脚本是：输入→处理→输出，人不参与。
Skill是：输入→提案→人决策→执行→人确认。

人在每个关键节点都在场。

Skill不是写完就一劳永逸的。

6种Skill设计模式分别是：

• 检查清单型
• 多方案选择型
• 多阶段流水线型
• 外部API集成型
• 多Agent协作型
• 思维蒸馏型

模式	适用场景	核心结构
检查清单型	审校、review、质量验证	输入→逐项检查→标记问题→修改建议
多方案选择	选题、设计方向、策略选择	需求→生成N个方案→展示优劣→等待选择
流水线型	端到端工作流、复杂任务	阶段1→检查点→阶段2…产出
API集成型	调用外部服务	需求→调用API→处理结果→格式化输出
多Agent协作型	大规模并行任务	拆分→分配→并行执行→合并
思维蒸馏型	人物视角、领域方法论	多维采集→三重验证→框架提炼→Skil生成

平台

汇总几个高质量Skill仓库/平台：

• Anthropic Skills：下面章节
• skills.sh：Vercel Labs推出，用npx skills add安装
• AgentSkill.sh：Skill社区
• SkillsMP：Skill市场
• SkillHub：亮点是AI评审机制
• 腾讯SkillHub：国内最大的Skills聚合平台，亮点是安全审计和本地化适配

Anthropic Skills

2025年12月，Anthropic发布Agent Skills并开源（GitHub，144K Star，17K Fork）

目录解读：

• ./skills：示例，包括创新性和设计、开发和技术、企业、文档等
• ./spec：规范
• ./template：模板

架构：渐进式披露（Progressive Disclosure）​。分三个层级：

• 预加载：只读元数据
• 按需加载：完整正文
• 深度加载：Bundled Resources(脚本/引用文件/素材)。有些Skil会附带外部资源：scripts/目录下的脚本、references/目录下的参考文件、assets/目录下的素材。只有在AI真正需要用到这些资源时，才会去读取。

skill-creator

一个meta-skill，用Skill来创建、评估和改进Skill。核心理念是：把软件工程的严谨性引入Skill创作。

有四种工作模式，分别解决Skill生命周期中的不同问题：

• Create模式：从描述到成品
• Eval模式：给Skill打分
• Improve模式：自动改进
• Benchmark模式：统计验证

Vercel Agent Skills

Vercel官方开源（GitHub，29.6K Star，2.7K Fork）代理技能合集，项目主页。

Agent Skills

Agent Skills得到众多公司和社区支持，成为开放标准，官网，
开源（GitHub，23.7K Star，1.6K Fork）代理技能规范和文档。

OpenAI Skills

OpenAI开源（GitHub，20.9K Star，1.4K Fork）为Codex设计的Skill目录。

Skill Seeker

官网，开源（GitHub，13.8K Star，1.4K Fork）的自动化工具，专门解决手动创建Claude Skills的痛点，旨在帮助开发者将各种文档和代码资源转化为AI（特别是Claude AI，支持Gemini和ChatGPT）可理解和使用的技能。

支持三类资源：

• 文档网站：自动抓取官方文档（支持llms.txt标准和通用网页抓取），并按主题智能分类
• GitHub仓库：深入分析代码库（使用AST语法树解析），提取API、函数、类、README以及Issue和PR信息
• PDF文件：提取PDF中的文本、代码、表格、OCR识别

原理：

• 抓取（Scrape）：从文档中提取所有页面内容
• 分类（Categorize）：将内容按主题组织，如API、指南、教程等
• 增强（Enhance）：AI分析文档并自动生成完整SKILL.md
• 打包（Package）：把所有内容打包成可在Claude中直接使用的.zip文件

冲突检测，对比文档和代码，确认是否有出入，从而生成更准确的知识库。

解决痛点：

• 节省时间：将原本需要数小时的手动整理工作缩短到20-40分钟。
• 文档+代码：很多时候文档是滞后的，能同时分析代码库，找出文档中没有提到的最新特性或变更。
• 统一真理源：对于团队来说，可将内部文档和实际代码库结合，生成一个既包含理论又包含实现的单一知识源。
• 填补文档空白：开源维护者可以用它来发现哪些代码功能还没有编写文档。

核心功能

文档网站抓取

• llms.txt支持：自动检测和使用LLM就绪的文档文件（速度提升10倍）
• 通用抓取器：适用于任何文档网站
• 智能分类：自动按主题组织内容
• 代码语言检测：识别Python、JS、C++、GDScript等
• 8个即用预设：Godot、React、Vue、Django、FastAPI等

PDF支持

• 基础PDF提取：从PDF文件中提取文本、代码和图像
• OCR扫描PDF：从扫描文档中提取文本
• 密码保护PDF：处理加密的PDF
• 表格提取：从PDF中提取复杂表格
• 并行处理：大型PDF速度提升3倍
• 智能缓存：重新运行时速度提升50%

GitHub仓库抓取

• 深度代码分析：对Python、JS、TS、Java、C++、Go进行AST解析
• API提取：提取函数、类、方法及其参数和类型
• 仓库元数据：README、文件树、语言分布、星标/分叉数
• Issues和PR：取带标签和里程碑的开放/关闭问题
• CHANGELOG和发布：自动提取版本历史
• 冲突检测：比较文档化的 API 与实际代码实现
• MCP集成：自然语言：“抓取 GitHub 仓库 facebook/react”

统一多源抓取

• 组合多个源：在一个技能中混合文档、GitHub、PDF
• 冲突检测：自动发现文档和代码之间的差异
• 智能合并：基于规则或 AI 驱动的冲突解决
• 透明报告：并排比较，带有⚠️警告
• 文档差距分析：识别过时的文档和未记录的功能
• 单一真理源：一个技能同时显示意图（文档）和现实（代码）

优势

1. 多源融合与冲突检测：可同时读取文档网站和GitHub仓库，并自动检测二者差异，并在生成的技能包中标记出来。
2. 深度代码分析：通过AST（抽象语法树）解析Python、JavaScript、C++、Go等语言的代码结构，提取出具体的API定义、类型和参数。
3. 多LLM平台支持：支持导出为适合Google Gemini、OpenAI ChatGPT的格式，或Markdown格式。
4. 三流分析架构：采用代码（Code）、文档（Docs）和洞察（Insights，如 Issue 和 Stars）三条流进行分析，不仅知道代码怎么写，还知道社区常见的问题是什么（通过分析 GitHub Issues）。
5. 智能化增强：具备AI增强功能，可以自动提取最佳代码示例，生成"How-to"指南，并优化配置文件的解释。
6. 企业级特性：支持私有GitHub仓库、GitLab、Bitbucket，支持多Token配置以应对API速率限制，以及支持CI/CD集成。

支持4个LLM平台

平台	格式	自动上传	AI增强	API密钥
ClaudeAI	ZIP+YAML	✅	✅	ANTHROPIC_API_KEY
GoogleGemini	tar.gz	✅	✅	GOOGLE_API_KEY
OpenAIChatGPT	ZIP+VectorStore	✅	✅	OPENAI_API_KEY
GenericMarkdown	ZIP	❌手动	❌	无

特点

• 通用抓取：相同的文档适用于所有平台
• 平台特定打包：为每个LLM优化的格式
• 一键导出：--target标志选择平台
• 可选依赖：只安装需要
• 100%向后兼容：现有Claude工作流程不变

实战

安装方式：

• pip
• 源码

先看看基于pip方式：

pip install skill-seekers[gemini]
pip install skill-seekers[openai]
pip install skill-seekers[all-llms]
# Claude
skill-seekers package output/react/
skill-seekers upload react.zip
# Gemini
pip install skill-seekers[gemini]
skill-seekers package output/react/ --target gemini
skill-seekers upload react-gemini.tar.gz --target gemini
# ChatGPT
pip install skill-seekers[openai]
skill-seekers package output/react/ --target openai
skill-seekers upload react-openai.zip --target openai
# Generic Markdown
skill-seekers package output/react/ --target markdown

基于源码安装：

pip install skill-seekers
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
cd Skill_Seekers
# 将Skill Seeker注册为Claude的MCP工具
./setup_mcp.sh

OpenSkills

论文，开源（GitHub，10.3K Star，654 Fork）.

官方定位

Universal skills loader for AI coding agents

instavm

此外，在GitHub上还有另外一个项目：https://github.com/instavm/open-skills，379 Star，31 Fork。

实战

npm i -g openskills
openskills install anthropics/skills
openskills sync

MiniMax Office Skills

MiniMax开源（GitHub，12.2K Star，1K Fork），覆盖Word、Excel、PDF、PPT四种格式：

• Word：没有选用Python生态最常用的Word生成库python-docx，而是选用.NET OpenXML SDK；微软官方的Office文档底层库，对ECMA-376（Word格式的国际标准）有最完整的实现；需部署.NET运行时；
• Excel：没有使用openpyxl，而是直接操作XML；.xlsx文件本质是XML文件的zip压缩包。所有衍生值必须保持真实的Excel公式（如SUM(B2:B9)），而不是预先算好的数字。改了源头，所有引用自动联动更新。为此构建13个独立的Python工具脚本，一份34000字的财务格式规范，对齐投行级的数字格式和布局标准。
• PDF：主要是封面和正文；封面要好看，需要渐变、网格、混合模式、自定义字体；正文要稳定，需要对分页、段落流、页眉页脚精确控制。用两套引擎，封面用HTML+CSS，通过Playwright渲染成PDF，CSS原生处理视觉效果；正文用ReportLab，提供工程层面稳定可预期的控制。
• PPT：难点是视觉一致性，做法：先把约束系统定义清楚，再在约束里生成内容。

核心功能

• PDF文档生成与编辑：通过模型推理能力和XML处理逻辑，将业务数据直接生成结构化高质量PDF文档，支持字段填充、样式重组以及排版美化等操作；在实际任务中可自动生成带封面、目录与规范版式的报告文档。
• PPTX演示创建与修改：利用pptx‑generator插件结合MiniMax模型内容推理，实现从自然语言输入到完整演示文稿的生成，支持从封面页布局到图表填充的自动处理，提高商务演示制作效率。
• Excel表格处理：借助minimax‑xlsx技能实现表格解析、公式计算、格式一致性检查及财务模型输出，开发者可输入数据说明或模板路径，自动生成复杂财务表格或分析报告。
• DOCX文档智能操作：结合minimax‑docx模块，用户可创建新文档、填充内容、格式化文本结构并根据模板执行自动化格式设置，适合生成标准合同、计划书或报告。
• 技能集扩展支持：仓库设计的结构允许开发者扩展新技能，例如流程任务、业务文档解析等，通过定义技能元数据即可加入新的办公自动化能力，实现灵活生态发展。

技术原理

• M2.5模型语义推理：依赖MiniMax M2.5作为核心语义推理引擎，MoE架构，并通过强化学习优化任务分解能力，在读取自然语言指令后生成上下文相关的办公任务执行指令。
• 插件层 XML 操作：技能集通过针对 PPTX/Excel/PDF/DOCX 等格式的底层 XML 处理实现文件结构化操作，将模型的内容输出映射到具体的文件格式元素，从而实现自动化 Office 文档生成和修改。
• 上下文管理：依赖模型的长上下文窗口（约200K Token），可在单次会话中处理大规模输入文本、任务说明及历史修改记录，使得复杂工作流中的任务逻辑保持连贯且可追踪。
• 多步骤Agent任务拆解：调用M2.5的推理和任务分解能力，在执行复杂任务时会将任务拆分为多个子步骤，如表格分析、公式执行、文本摘要等，有效提升专业性和结构化输出质量。
• 输入参数智能映射：开发者在集成时可以通过参数配置控制输出格式和细节，例如指定模板路径、字段映射规则、语言风格等，使得技能在业务场景中更易适配和调优，提升实际应用效果。

对比

维度	MiniMaxOfficeSkills	OpenAIGPT‑4Tools	Claude4.6Suite
模型依赖	基于MiniMaxM2.5模型推理	依赖GPT‑4/5系列	基于Claude4.6/5
上下文长度	约200K Token	约32k–128kToken	约100kToken
办公技能集成	集中XML插件处理PPTX/Excel/PDF/DOCX	工具调用需额外插件	集成插件生态较成熟
扩展性	开源仓库可自定义技能	依赖商业SDK	部分开源插件
成本	运行成本较低	高运行成本	中等
实际输出质量	面向可交付文档	生成准确性高但需后处理	支持业务集成