1. 项目概述：一个面向AI智能体的技能库
最近在折腾各种AI智能体（Agent）工具，像Claude、Antigravity、OpenClaw这些，发现一个挺有意思的现象：虽然这些工具本身很强大，但很多时候我们想让它们完成一些特定任务时，比如生成结构化的提示词、做SWOT分析、甚至计算巴西的CDI利率，都需要反复输入复杂的指令。这就像每次开车去同一个地方都要重新设置导航一样，效率不高。
于是，我动手整理了一个开源项目——marioluciofjr/skills。简单来说，这是一个专门为各类AI智能体系统打造的“技能包”仓库。你可以把它理解为一个插件商店，里面存放了各种预先编写好的、可以直接导入到Claude、Antigravity等工具里使用的功能模块。有了这些技能，AI就能像安装了新APP一样，瞬间获得处理特定任务的能力，省去了你每次都要详细描述“怎么做”的麻烦。
这个项目特别适合两类朋友：一是经常使用Claude、Google Antigravity等AI智能体进行内容创作、数据分析或自动化流程的深度用户；二是对AI智能体开发感兴趣，想了解如何为其扩展自定义功能的开发者。无论你是想直接“开箱即用”提升效率，还是想学习技能（Skill）的构建原理来自行开发，这个仓库都能提供不错的起点和丰富的实例。
2. 技能库的核心价值与设计思路
2.1 为什么需要“技能”？
在AI智能体的语境下，“技能”是一个核心概念。它不同于简单的提示词（Prompt），而是一个封装了特定能力、包含执行逻辑和必要上下文的完整功能单元。你可以把它想象成智能手机上的一个独立应用。一个“计算器”应用（技能）内部包含了加减乘除的算法、界面布局和用户交互逻辑，你不需要知道它是怎么算的，点开就能用。
同理，一个“生成Mermaid图表”的技能，内部可能封装了将自然语言描述转换为Mermaid语法的规则、错误处理逻辑以及输出格式的模板。当你把这个技能加载到Claude中，只需要说“帮我画一个系统架构图”，Claude就能调用这个技能，输出标准的Mermaid代码，而不是仅仅给你一段文字描述。
这个项目的核心价值就在于“标准化”和“可复用性”。它把一些常见但复杂的任务流程固化下来，做成了即插即用的模块。这带来了几个明显的好处：
- 降低使用门槛：用户无需记忆复杂的指令语法或参数，直接调用技能名称即可。
- 保证输出质量：技能内部经过优化和测试，能确保输出结果的结构化和一致性。
- 促进生态共享：开源的形式让开发者可以贡献自己的技能，形成一个不断丰富的工具箱。
2.2 项目结构解析：模块化与清晰度
打开项目的GitHub仓库，你会发现它的结构非常清晰，完全遵循了“一个技能，一个文件夹”的原则。这种设计思路值得借鉴，因为它极大地提升了可维护性和可发现性。
skills/ ├── prompt-personagem/ # 角色提示词生成技能 ├── alt-text/ # 图片Alt文本生成技能 ├── prompt-estruturado/ # 结构化提示词生成技能 ├── analise-semiotica/ # 符号学分析技能 ├── calculadora-cdi/ # CDI利率计算器技能 ├── diagrama-mermaid/ # Mermaid图表生成技能 ├── analise-swot/ # SWOT分析技能 └── ... (其他技能文件夹)每个技能文件夹内部，通常包含以下几个核心文件（以prompt-estruturado为例）：
skill.yaml：这是技能的“身份证”和“说明书”，是每个技能必须的核心文件。它采用YAML格式，定义了技能的基本信息、触发方式、输入输出参数等元数据。prompt.md或main.py：这是技能的“大脑”。对于基于提示词（Prompt）的技能，通常是一个Markdown文件，里面包含了详细的系统指令、少样本示例（Few-shot Examples）和输出格式要求。对于需要执行代码的技能，则可能是一个Python脚本（.py文件）。README.md：技能的详细使用文档，解释这个技能是做什么的、怎么用、有什么参数。- 其他资源文件：如图标、示例数据、配置文件等。
这种结构化的设计，使得每个技能都是自包含的、独立的，方便单独下载、测试和集成到不同的AI智能体平台中。项目README中提供的DownGit链接，正是利用了这种结构，让用户可以精准下载单个技能的ZIP包，而不必克隆整个仓库。
实操心得：在设计自己的技能时，强烈建议遵循这种“一个技能一个文件夹”的约定。这不仅能让你自己的项目井井有条，更重要的是，它符合主流AI智能体平台（如Claude、Antigravity）对技能包的识别规范，能实现无缝导入。
3. 核心技能详解与使用场景
这个仓库里包含了十多个技能，覆盖了从内容创作到数据分析的多个场景。我们挑几个有代表性的，深入看看它们能解决什么问题，以及是怎么设计的。
3.1 结构化提示词生成 (prompt-estruturado)
这是我认为最实用的技能之一。很多人在使用大模型时，提示词写得过于随意，导致输出结果不稳定。这个技能的作用，就是引导你或AI本身，生成一个高质量、结构化的提示词。
它的核心逻辑是提供一个填空模板。当你调用这个技能时，它会要求你提供几个关键信息：
- 角色：你希望AI扮演什么？（例如：资深SEO专家、经验丰富的Python程序员）
- 任务：你要AI完成的具体目标是什么？（例如：为一篇关于云计算的博客撰写引言）
- 上下文：相关的背景信息。（例如：目标读者是技术主管，文章风格需专业但易懂）
- 约束：必须遵守的规则或限制。（例如：字数在300字以内，避免使用术语“数字化转型”）
- 输出格式：你希望得到什么形式的结果。（例如：Markdown格式的段落，包含三个要点）
技能内部预设的提示词模板会将这些零散的信息，组织成一个符合“角色-任务-上下文-约束-格式”框架的完整、清晰的指令。这能显著提升AI理解你意图的准确度，从而得到更符合预期的输出。
使用场景：任何需要AI进行复杂内容生成的任务之前，都可以先用这个技能打磨你的指令。特别适合文案创作、报告撰写、代码生成等场景。
3.2 Mermaid图表生成 (diagrama-mermaid)
Mermaid是一种用文本描述生成图表的标记语言，非常适合在文档中嵌入流程图、时序图、类图等。但对于不熟悉其语法的人来说，手写Mermaid代码是个门槛。
这个技能充当了一个“翻译官”。你只需要用自然语言描述你想要图表，比如：“画一个用户登录网站的流程图，包括输入用户名密码、验证、成功跳转主页和失败提示错误几个步骤。” 技能内部封装了将这类描述转化为标准Mermaid语法的逻辑和示例。
它的实现关键在于“少样本学习”。在技能的prompt.md文件中，通常会包含多个“自然语言描述 -> Mermaid代码”的配对示例。当AI加载这个技能后，它就学会了这种转换模式。这比单纯告诉AI“请用Mermaid画图”要有效得多，因为技能提供了具体的、可模仿的范例。
使用场景：撰写技术文档、设计系统架构、规划业务流程时，快速生成可视化图表代码，直接嵌入到Markdown或文档工具中。
3.3 SWOT分析 (analise-swot)
SWOT分析是商业和战略规划中常用的工具。这个技能将这一分析框架标准化、流程化。
你向AI提供一家公司、一个产品或一个项目的基本信息，然后调用SWOT分析技能。AI会基于技能内嵌的分析框架和提问逻辑，引导性地帮你梳理出：
- 优势：内部的有利条件。
- 劣势：内部的不利条件。
- 机会：外部的有利因素。
- 威胁：外部的不利因素。
最终，技能会输出一个结构清晰的表格或列表，有时还会附带简要的分析建议。这相当于让AI扮演了一个商业分析顾问的角色，确保了分析过程的全面性和结构化，避免了手动分析时可能出现的遗漏或逻辑混乱。
使用场景：产品经理进行竞品分析、创业者评估商业计划、项目经理评估项目风险时，快速获得一个结构化的分析草案。
3.4 CDI计算器 (calculadora-cdi)
这个技能展示了AI技能如何与专业领域知识结合。CDI是巴西金融市场的基准利率，相关计算涉及特定公式和日期惯例。
对于不熟悉巴西金融规则的用户，手动计算非常容易出错。这个技能将计算逻辑封装起来。你只需要提供本金、利率周期、起止日期等基本参数，技能就能调用内部预设的公式（可能是通过一段内联的Python逻辑或精确的提示词描述），准确计算出利息、累计因子或最终金额。
这揭示了一个重要方向：垂直领域技能。未来，会有越来越多针对法律、医疗、金融、科研等特定领域的技能出现，它们封装了领域内的专业知识和计算逻辑，让通用AI具备了解决专业问题的能力。
4. 如何在主流AI智能体中安装与使用技能
技能再好，也得装得上、用得了。这个项目贴心地提供了在Claude和Antigravity这两个主流平台上安装技能的详细指南。我们来一步步拆解，并补充一些关键的实操细节。
4.1 在Claude中安装技能（图形化操作）
Claude目前提供了相对友好的图形界面来管理技能。根据项目指南，步骤如下：
- 获取技能包：在项目README的“Estrutura do projeto”部分，找到你想要的技能，点击对应的DownGit链接。这会生成一个该技能文件夹的ZIP压缩包，下载到本地。
- 进入Claude技能管理：在Claude的Web界面或桌面应用中，找到“Personalizar”（自定义）或类似设置图标，点击进入。然后寻找“Habilidades”（技能）或“Criar novas habilidades”（创建新技能）的选项。
- 上传技能：点击“添加新技能”或类似按钮，选择“上传一个技能”（Upload a skill）选项。在弹出的文件选择器中，找到并选中你刚刚下载的ZIP文件。
- 验证与启用：上传后，Claude通常会解析这个技能包，并显示技能的名称、描述和触发方式。确认无误后，启用该技能。
注意事项：
- 网络环境：由于Claude的服务特性，确保你的网络连接稳定。整个操作过程在浏览器中完成，对本地环境无特殊要求。
- 技能冲突：如果你从不同来源上传了同名技能，可能会产生冲突。建议在安装前，检查一下Claude现有技能列表。
- 权限问题：技能中的
skill.yaml文件定义了技能所需的权限（如是否可访问网络、读写文件等）。首次启用时，Claude可能会请求你的确认，请根据技能的可信度审慎授权。
使用技巧：技能安装成功后，如何在对话中调用呢？这取决于技能的定义。通常有两种方式：
- 显式调用：有些技能有明确的触发词或命令，比如你可以说“请使用SWOT分析技能来分析一下特斯拉公司。”
- 隐式触发：更智能的技能会被Claude自动识别场景并调用。例如，当你提到“画个流程图”时，Claude可能会自动启用Mermaid图表技能来响应。具体调用方式需要查看每个技能的
README.md或skill.yaml中的描述。
4.2 在Antigravity中安装技能（命令行操作）
Antigravity作为Google DeepMind推出的AI智能体IDE，更偏向开发者，支持通过命令行进行技能管理。项目提供了一个非常实用的自动化提示（Prompt）来指导安装。
其核心命令是：
npx skills add https://github.com/marioluciofjr/skills --skill NOME_DA_SKILL --agent antigravity --yes你需要将NOME_DA_SKILL替换为具体的技能文件夹名，例如prompt-estruturado。
项目提供的长提示（Prompt）本质上是一个给Antigravity Agent的详细指令清单，让它自动执行以下操作：
- 定位Antigravity的安装目录（通常是
.gemini\antigravity）。 - 执行上述
npx skills add命令从GitHub拉取指定技能。 - 检查安装是否成功（提示
◇ Installation complete）。 - 整理技能文件，将其移动到统一的
skills目录下，并清理临时文件。
实操心得与避坑指南：
- 环境准备：确保你的系统已经安装了Node.js和npm（或yarn、pnpm），因为
npx是Node.js的包执行工具。这是命令能运行的前提。- 路径确认：Antigravity的默认安装路径可能因操作系统而异。在Windows上通常是
C:\Users\[你的用户名]\.gemini\antigravity，在macOS/Linux上是~/.gemini/antigravity。如果提示中的路径不对，Agent可能会报错。你可以先手动检查这个目录是否存在。- 网络问题：
npx命令会从网络下载技能包，如果遇到GitHub访问缓慢或超时，可以尝试配置命令行代理或使用国内镜像源（注意，此处仅讨论技术层面的网络配置优化，不涉及任何违规内容）。- 权限问题：在Windows系统上，移动或删除系统目录下的文件（如
.agents文件夹）可能需要管理员权限。如果Agent执行失败，可以尝试以管理员身份运行Antigravity或终端。
更手动但可控的方法：如果你不放心完全自动化，也可以手动操作：
- 打开终端（命令行），进入Antigravity的安装目录：
cd ~/.gemini/antigravity(Linux/macOS) 或cd C:\Users\[你的用户名]\.gemini\antigravity(Windows)。 - 直接运行安装命令，例如：
npx skills add https://github.com/marioluciofjr/skills --skill prompt-estruturado --agent antigravity --yes。 - 安装完成后，技能文件通常会出现在
.agents/skills/或项目提示中指定的skills/目录下。你可以在Antigravity IDE中刷新或重新扫描技能目录来加载它。
5. 技能开发入门：从使用到创造
如果你不满足于只是使用别人写的技能，想自己动手为Claude或Antigravity创建一个，那么了解技能的基本构成是第一步。虽然不同平台对技能的规范略有差异，但核心思想相通。
5.1 技能的核心文件：skill.yaml
这是技能的“元数据”文件，采用YAML格式，定义了技能如何与AI智能体交互。一个最基础的skill.yaml可能长这样：
name: gerador-de-titulos # 技能名称，唯一标识 description: Gera títulos criativos e atraentes para artigos de blog. # 技能描述 version: 1.0.0 # 版本号 author: Seu Nome # 作者 # 输入参数定义：告诉AI用户需要提供什么信息 inputs: - name: topico # 参数名 description: O tópico principal do artigo. # 参数描述 type: string # 参数类型（字符串） required: true # 是否必填 - name: tom description: O tom desejado (ex: profissional, descontraído, urgente). type: string required: false # 可选参数 default: profissional # 默认值 # 输出定义：告诉AI技能会输出什么 outputs: - name: titulos description: Uma lista de 5 títulos sugeridos. type: array # 输出类型为数组 # 执行指令：技能的核心逻辑在哪里 run: # 如果是基于提示词的技能，指向一个.md文件 prompt: ./prompt.md # 如果是基于代码的技能，可以指向一个.py文件并指定解释器 # code: ./main.py # runtime: python关键字段解析：
inputs：这是你与技能交互的“接口”。定义清晰、具体的输入参数，能极大提升技能的易用性。尽量为每个参数提供description和default值。run：指定技能的“大脑”。prompt方式更常见，它指向一个包含详细系统指令和示例的Markdown文件。code方式则赋予技能执行Python等代码的能力，更强大但也更复杂。
5.2 技能的“大脑”：prompt.md或代码文件
对于大多数技能，prompt.md是其灵魂。这个文件里写的是给AI看的“剧本”，告诉它当这个技能被调用时，应该如何思考、如何行动。
一个有效的prompt.md通常包含以下部分：
- 系统角色设定：明确告诉AI在本次任务中扮演什么角色。
- 任务目标：清晰定义技能要完成的具体工作。
- 思考过程（可选但推荐）：引导AI分步骤思考，例如“首先，理解用户输入的主题；其次，分析该主题的关键词；然后，结合不同标题公式进行创作...”。
- 少样本示例：提供2-3个完整的“用户输入 -> 技能输出”的例子。这是让AI学会技能模式的关键。
- 输出格式约束：严格规定输出的格式，如“请以JSON格式输出，包含
titulos字段，该字段是一个字符串数组。”
示例片段 (prompt.md)：
# 角色 你是一个资深的内容营销专家，尤其擅长创作高点击率的文章标题。 # 任务 根据用户提供的文章主题和期望的语调，生成5个吸引人的文章标题。 # 思考步骤 1. 仔细分析用户提供的`topico`（主题）核心关键词。 2. 根据`tom`（语调）参数，决定标题的语言风格（如正式、亲切、悬念式等）。 3. 应用经典的标题公式，如“如何体”、“数字列表体”、“疑问体”、“颠覆认知体”等。 4. 确保每个标题都独特、相关，并包含核心关键词。 # 示例 用户输入: {"topico": "aprender Python em 30 dias", "tom": "motivacional"} 输出: {"titulos": ["De Iniciante a Programador em Python: Seu Guia de 30 Dias", "5 Projetos Práticos para Dominar Python em um Mês", "Aprenda Python Rápido: Um Plano de Estudos Intensivo de 30 Dias", "Desmistificando o Python: Sua Jornada de um Mês para a Automação", "30 Dias, 30 Desafios: Transforme sua Carreira com Python"]} 用户输入: {"topico": "segurança cibernética para pequenas empresas", "tom": "profissional"} 输出: {"titulos": ["Proteção Essencial: Um Guia de Segurança Cibernética para PMEs", "Os 7 Pilares da Segurança Digital para sua Pequena Empresa", "Como Evitar Ataques Cibernéticos: Estratégias Acessíveis para Negócios Locais", "Orçamento Limitado? Implemente Estas 5 Medidas de Segurança Críticas Agora", "A Auditoria de Segurança que Toda Pequena Empresa Deve Fazer"]} # 输出格式 你必须严格以以下JSON格式输出，且仅包含此JSON对象： { "titulos": ["标题1", "标题2", "标题3", "标题4", "标题5"] } 现在，请处理用户的请求。5.3 本地测试与调试技巧
在将技能上传到Claude或Antigravity之前，强烈建议先在本地进行测试和调试。
- 使用文本编辑器或IDE：用VSCode、Sublime Text等编辑器创建和编辑你的
skill.yaml和prompt.md文件。利用YAML和Markdown的语法高亮和校验插件，可以减少格式错误。 - 模拟对话测试：你可以手动扮演AI和用户。复制
prompt.md中的全部内容，粘贴到Claude的Web界面（新建一个对话），然后在最后附上你的测试输入（如用户输入: {"topico": "teste"}），观察AI的回复是否符合预期。这是检验提示词效果最直接的方法。 - 使用本地测试工具：一些AI开发框架或命令行工具允许你加载本地的技能文件进行测试。例如，你可以搭建一个简单的脚本，使用OpenAI API或Anthropic API，并将你的
prompt.md内容作为系统消息发送，来验证技能逻辑。 - 迭代优化：根据测试结果，反复修改
prompt.md中的指令、示例和格式约束。通常需要几轮迭代才能让技能稳定可靠。重点关注AI是否理解了任务、是否遵循了格式、输出的质量是否达标。
6. 进阶探讨：技能生态与最佳实践
6.1 技能的分发与共享
marioluciofjr/skills项目采用GitHub仓库的形式分发，这是一种非常高效和开放的方式。对于技能开发者来说，这意味着：
- 版本控制：你可以使用Git来管理技能的迭代更新，用户可以通过关注仓库或Release来获取最新版本。
- 协作开发：通过GitHub的Issues、Pull Requests功能，可以收集用户反馈，接受社区贡献。
- 易于集成：像DownGit这样的服务，使得用户无需Git知识就能下载单个技能，降低了使用门槛。
除了自建仓库，也可以考虑将技能提交到官方的或第三方的技能市场，如skills.sh（项目链接中已提及），以获得更大的曝光度。
6.2 设计高质量技能的准则
根据这个开源项目和我的实践经验，总结出几条设计技能的最佳实践：
- 单一职责原则：一个技能只做好一件事。不要设计一个“万能文案生成器”，而是拆分成“标题生成器”、“摘要生成器”、“广告语生成器”等多个精细化的技能。这样更专注，效果也更好。
- 输入明确，输出结构化：在
skill.yaml中清晰定义所有输入参数及其类型、是否必填、默认值。输出务必要求结构化格式（如JSON、特定Markdown表格），方便后续程序化处理。 - 提供丰富的少样本示例：在
prompt.md中，2-3个高质量、覆盖不同场景的示例，远比一段冗长的描述性指令更有效。示例是AI学习的主要途径。 - 包含详尽的文档：每个技能文件夹内的
README.md非常重要。它应该说明技能的用途、输入输出格式的详细解释、使用示例以及任何已知的限制或依赖。 - 考虑错误处理：在提示词中预判用户可能提供的无效输入，并指导AI如何友好地回应或要求澄清。例如，“如果用户未提供
topico参数，请礼貌地提示用户输入文章主题。”
6.3 常见问题与排查
在安装和使用技能时，你可能会遇到以下问题：
问题1：在Claude上传ZIP后，技能没有出现或无法启用。
- 排查：首先检查ZIP包的结构。正确的结构应该是解压后直接看到
skill.yaml等文件，而不是外层还有一个同名的文件夹包裹着。错误的打包方式是常见原因。 - 解决：确保你打包的是技能文件夹内的内容，而不是文件夹本身。在Mac上，可以选中文件夹内的所有文件，右键“压缩”；在Windows上，进入技能文件夹，全选文件，右键“发送到” -> “压缩(zipped)文件夹”。
问题2：技能被启用，但AI似乎没有调用它，或者输出不符合预期。
- 排查：检查技能的触发方式。有些技能需要你明确说出“使用XX技能”，而有些是自动触发的。查看技能的
skill.yaml或README.md确认。 - 解决：在对话中更明确地指令。如果输出格式不对，很可能是
prompt.md中的输出格式约束不够严格，需要你强化指令，例如使用“你必须”、“只能”、“严格遵循”等词语，并提供一个无可挑剔的示例。
问题3：在Antigravity中使用npx命令安装失败，提示网络错误或命令未找到。
- 排查：
命令未找到：检查Node.js和npm是否已正确安装并加入系统PATH。在终端输入node --version和npm --version确认。网络错误：可能是网络连接问题，或者npx在首次运行时下载包超时。
- 解决：
- 对于Node.js问题，去官网重新下载安装。
- 对于网络问题，可以尝试设置npm镜像源（例如使用淘宝镜像），或者稍后重试。命令如
npm config set registry https://registry.npmmirror.com。
问题4：自己开发的技能效果不稳定，有时好有时坏。
- 排查：这通常是由于提示词（
prompt.md）不够精确或示例覆盖度不足导致的。大模型具有随机性，模糊的指令会导致输出波动。 - 解决：回归到“少样本示例”的设计上。确保你的示例能代表各种典型的输入情况。在指令中，将复杂的任务分解成清晰的步骤（思考链），并严格限定输出格式。进行多轮测试，用不同的边缘案例（如空输入、极端值、模糊描述）来测试技能的鲁棒性，并据此优化提示词。
这个开源技能库就像打开了一扇窗，让我们看到了AI智能体应用生态的一种可行路径。通过将复杂任务封装成可复用的技能，我们不仅能提升自己使用AI的效率，还能为整个社区贡献价值。从使用现成技能，到理解其原理，再到动手创造自己的技能，这个过程本身就是一次深刻的学习。
