1. 项目概述一个面向AI智能体的技能库最近在折腾各种AI智能体从Claude、Antigravity到Opencode我发现一个挺普遍的需求如何让这些“聪明”的AI助手更精准、更稳定地执行一些特定任务比如让它帮我分析一张图片的Alt文本是否合格或者快速生成一个结构清晰的SWOT分析。直接给提示词Prompt当然可以但每次都要重新描述规则和格式效率太低而且效果还不稳定。于是我开始研究“Agent Skills”智能体技能这个概念。简单来说这就像给你的AI助手安装一个“插件”或“小程序”。你提前把一套完整的任务指令、输出格式、甚至背后的处理逻辑比如调用某个Python函数打包好形成一个标准化的“技能包”。下次需要时AI直接调用这个技能包输出结果就是结构化的、可预期的。这比每次现场编提示词要靠谱得多。我把自己常用的一些技能整理了一下开源在了GitHub上项目就叫marioluciofjr/skills。这个仓库目前包含了十几个实用的技能覆盖了内容分析、SEO优化、金融计算、创意生成等多个场景。更重要的是我详细记录了如何将这些技能部署到主流的AI智能体平台比如Claude.ai和Google的Antigravity。无论你是想直接使用这些现成的技能还是想了解如何从零开始构建自己的技能这个项目都能给你提供一个清晰的参考。2. 技能库的核心价值与设计思路2.1 为什么需要“技能”而不仅仅是“提示词”刚开始用大语言模型时我和很多人一样热衷于编写和收集各种“神奇提示词”。但很快我就遇到了瓶颈复杂任务的提示词又长又难维护。一个包含多步骤、特定输出格式的提示词动辄上千字放在对话上下文里占位置修改起来也麻烦。输出结果不稳定更是头疼同样的提示词AI今天可能给你一个完美的表格明天就变成了一段散文你需要不断在对话中纠正它。“技能”机制就是为了解决这些问题而生的。它通过一个标准化的文件包通常包含skill.yaml配置文件、prompt.md指令文件、files/资源目录等将任务定义、执行逻辑和输出规范固化下来。对AI来说调用一个技能就像运行一个封装好的函数输入参数得到格式确定的输出。这带来了几个核心优势标准化与复用性一次构建多处使用。同一个“图片Alt文本分析”技能可以在Claude、Antigravity等多个支持该标准的平台上运行无需重新适配。结果可预期技能中明确定义了输出格式如JSON、Markdown表格极大减少了AI“自由发挥”导致结果不可用的风险。功能扩展高级技能可以集成自定义代码Python函数让AI不仅能“想”还能“算”和“操作”比如我的calculadora-cdiCDI计算器技能就内置了金融计算逻辑。易于管理与分享技能以文件包形式存在可以像代码库一样进行版本管理、分叉和协作社区生态也由此建立起来。2.2 技能库的结构化设计我的技能库采用了清晰的分目录结构每个技能独立一个文件夹。这样设计主要是为了隔离性每个技能自包含互不干扰方便单独下载、测试和更新。可维护性问题定位和修复可以精确到单个技能不会牵一发而动全身。易于分发用户可以根据需要只下载他们感兴趣的那个技能的ZIP包而不是克隆整个仓库。一个典型的技能文件夹比如analise-swotSWOT分析内部结构通常如下analise-swot/ ├── skill.yaml # 技能的核心配置文件定义元数据、输入输出 ├── prompt.md # 给AI的核心指令描述任务和规则 ├── files/ # 可选存放技能所需的额外文件如图标、模板 │ └── swot_template.md └── ... # 其他可能的文件如Python脚本、README说明其中skill.yaml是这个技能的“身份证”和“说明书”。以SWOT分析技能为例其skill.yaml的关键部分可能长这样name: analise-swot description: Gera uma análise SWOT estruturada a partir de um tópico ou empresa fornecida. author: Mário Lúcio version: 1.0.0 input: parameters: - name: topico description: O tópico, nome da empresa ou ideia para a análise SWOT. required: true schema: type: string output: schema: type: object properties: pontos_fortes: type: array items: type: string description: Lista de pontos fortes (Strengths). pontos_fracos: type: array items: type: string description: Lista de pontos fracos (Weaknesses). oportunidades: type: array items: type: string description: Lista de oportunidades (Opportunities). ameacas: type: array items: type: string description: Lista de ameaças (Threats). resumo: type: string description: Um breve resumo interpretativo da análise. required: - pontos_fortes - pontos_fracos - oportunidades - ameacas - resumo这个配置文件清晰地告诉AI和用户这个技能叫analise-swot你需要给我一个topico字符串作为输入然后我会输出一个包含五个固定字段的JSON对象。这种强约束就是结果稳定的保证。注意不同AI平台对技能规范的支持程度可能略有不同。例如Claude Skills 和 Antigravity Skills 都遵循类似但可能不完全相同的规范。在构建技能时最好先查阅目标平台的官方文档。我的仓库中的技能主要兼容 Claude 的规范并在 Antigravity 上经过测试。3. 核心技能解析与使用场景我的技能库目前包含了十多个技能我将它们大致分为三类内容创作与优化、数据分析与计算、提示工程与代理管理。下面挑选几个有代表性的详细拆解。3.1 内容创作与优化类技能这类技能旨在辅助生成或优化文本、图像描述等内容。alt-textAlt文本生成器这是我最常用的技能之一。对于网站运营和内容创作者来说为图片添加高质量的Alt文本是SEO和可访问性的基本要求。这个技能接收一个图片URL或描述然后生成符合WCAG标准、包含关键词且描述准确的Alt文本。它的prompt.md里详细规定了Alt文本的长度、结构先核心对象再场景上下文和禁止事项如不能以“一张图片显示了...”开头。prompt-estruturado结构化提示生成器这是一个“元技能”用于帮助用户生成更有效的提示词。你告诉它你的模糊想法比如“我想写一篇关于咖啡历史的博客”它会通过一系列提问帮你梳理出角色、背景、任务、输出格式等要素最终输出一个清晰、可直接使用的复杂提示词。这相当于一个提示词教练。analise-semiotica符号学分析这是一个比较有趣的技能用于分析文本、广告语或品牌名称中的符号学意义。它能指出词语的文化隐喻、情感色彩和潜在联想。对于市场营销、品牌策划和内容创作来说这是一个独特的视角工具可以帮助避免文化误读或挖掘深层含义。3.2 数据分析与计算类技能这类技能通常涉及逻辑运算或数据处理展示了技能如何超越纯文本生成。calculadora-cdiCDI计算器这是技能集成自定义代码能力的典型例子。CDI是巴西金融市场的一个关键利率。这个技能内部包含一个Python脚本可以根据初始本金、投资期限和CDI历史数据计算投资收益。用户只需输入简单的参数AI在后台调用这个Python函数完成复杂计算最后以清晰的文本和表格形式呈现结果。这完全避免了AI在数学计算上可能出现的“幻觉”。bbb-estatisticasBBB统计数据这个技能展示了如何利用技能处理特定领域的数据查询。它内嵌了巴西热门真人秀《Big Brother Brasil》历届选手的数据库以结构化文件形式存放在files/目录下。用户可以询问诸如“哪一届的女性冠军最多”、“平均年龄是多少”等问题技能会检索本地数据并生成回答。这为构建垂直领域的知识问答助手提供了模板。trends-keywords趋势关键词分析该技能模拟了关键词研究的过程。输入一个核心主题它会基于内置的规则库可能结合常见的SEO策略模板生成一系列相关的长尾关键词、问题词并评估其搜索潜力和竞争难度。虽然它不直接连接Google Trends API但提供了一个结构化的分析框架。3.3 提示工程与代理管理类技能这类技能专注于提升你与AI交互的效率甚至管理其他AI智能体。gerador-de-agentes代理生成器在Antigravity、OpenClaw等多代理系统中经常需要配置具有不同专长的代理。这个技能可以根据你的需求如“需要一个擅长数据可视化的Python程序员代理”自动生成该代理的详细配置描述包括其系统指令、能力边界和协作方式。这大大简化了多代理工作流的搭建过程。prompt-skills技能提示词库这个技能本身就是一个可搜索的提示词库。它包含了数十个经过验证的、用于不同场景写作、编程、分析、创意的高效提示词模板。当你思路枯竭时可以让它根据你的任务推荐或直接提供适配后的提示词。contexto_sotaque语境与口音适配这是一个针对非英语用户的实用技能。它专门优化AI对于特定语言如葡萄牙语中不同地区口音、俚语和文化语境的理解与生成。例如你可以要求AI用“巴西东北部地区的口语风格”来改写一段文本使其听起来更地道。4. 技能部署实操以Claude和Antigravity为例拥有技能文件只是第一步让它们在AI平台上跑起来才是关键。下面我以最常用的两个平台——Claude.ai 和 Google Antigravity 为例详细说明部署步骤。4.1 在Claude.ai中部署技能Claude目前提供了最直观的图形化界面来管理技能。获取技能包进入我的GitHub仓库的skills项目页面。找到你需要的技能例如alt-text。你可以直接克隆整个仓库但更推荐使用每个技能下方的“Download ZIP”链接或借助DownGit这样的工具单独下载该技能文件夹的ZIP包。这样更干净。进入Claude技能管理界面登录 Claude.ai 在对话输入框的左侧或上方找到并点击“Personalizar”自定义或类似名称的图标。然后在弹出的菜单中选择“Habilidades”技能或“Criar novas habilidades”创建新技能。上传技能在技能管理页面点击“Adicionar nova habilidade”添加新技能或加号图标。选择“Fazer upload de uma nova habilidade”上传新技能。在弹出的文件选择器中找到并选中你刚刚下载的ZIP文件例如alt-text.zip。验证与使用上传成功后该技能会出现在你的技能列表中。通常技能图标和名称会基于skill.yaml中的定义自动显示。现在当你新建一个对话或使用已有的对话时在输入框附近应该能看到一个“技能”按钮或下拉菜单。点击它勾选你刚刚添加的alt-text技能。激活后你就可以在对话中直接使用了。例如你可以输入“使用alt-text技能分析这张图片[图片URL]”。Claude会识别到技能已被调用并按照技能内部的指令来执行任务。实操心得在Claude中一个常见的困惑是“如何触发技能”通常不需要特殊的命令只需在技能被激活的对话中用自然语言描述你的任务AI会自动匹配并调用最相关的技能。但为了更精确你可以在消息中提及技能名称如“请用analise-swot技能分析一下新能源汽车行业”。4.2 在Antigravity中部署技能Antigravity作为Google DeepMind推出的AI IDE更偏向开发者支持通过命令行安装社区技能。通过Antigravity Agent自动化安装推荐这是最酷的方式。Antigravity本身就是一个强大的AI代理你可以直接“命令”它去安装技能。复制我仓库中提供的专用安装提示词Prompt## contexto DIRETÓRIO PRINCIPAL .gemini\antigravity COMANDO npx skills add https://github.com/marioluciofjr/skills --skill NOME DA SKILL --agent antigravity --yes ## tarefa Pense passo a passo para executar a tarefa: 1 - Busque no computador o DIRETÓRIO PRINCIPAL definido no contexto. 2 - Use o COMANDO definido no contexto e dê enter. 3 - Verifique se a instalação deu certo, pois deve aparecer ◇ Installation complete. 4 - Verifique se no DIRETÓRIO PRINCIPAL já tem uma pasta chamada skills. Se tiver, pule para a próxima etapa. Se não tiver, crie para ficar assim .gemini\antigravity\skills 5 - Mova as skills deste diretório .gemini\antigravity\.agents\skills\ para este diretório .gemini\antigravity\skills 6 - Exclua as pastas .gemini\antigravity\.agents e .gemini\antigravity\.agent 7 - Finalize a tarefa将上述提示词中的NOME DA SKILL替换为你想要安装的具体技能文件夹名称例如--skill alt-text。然后将整个提示词发送给Antigravity Agent。它会像一名工程师一样在你的系统上找到Antigravity目录执行安装命令并完成文件整理。你会在它的思考过程中看到它执行npx命令。手动命令行安装如果你熟悉终端也可以手动操作。首先确保你的系统已安装Node.js和npm。然后打开终端使用npx运行 skills 工具进行安装# 安装特定技能如 alt-text npx skills add https://github.com/marioluciofjr/skills --skill alt-text --agent antigravity --yes安装后技能文件通常位于~/.gemini/antigravity/.agents/skills/目录下。根据我的经验有时需要手动将它们移动到~/.gemini/antigravity/skills/目录下Antigravity主界面才能正确识别。这就是为什么自动化提示词里包含了移动文件的步骤。在Antigravity中使用技能安装成功后重启Antigravity。在编辑区当你开始输入时Antigravity可能会在建议中提示可用的技能。你也可以在配置代理Agent时在其设置中关联特定的技能让该代理默认具备这些能力。注意事项Antigravity的生态和技能安装方式还在快速演进中。npx skills add是社区提供的工具并非Google官方命令。如果遇到安装问题首先检查网络连接其次确认Antigravity的安装目录是否正确。最可靠的方法是查阅项目仓库中Antigravity部分的说明或者直接克隆整个技能仓库手动将需要的技能文件夹复制到Antigravity的skills目录下。5. 从使用到创造如何构建你自己的技能如果你觉得现有的技能不够用或者想为自己独特的工作流定制技能那么自己动手构建是最好的选择。基于我维护这个技能库的经验我总结了一个清晰的五步构建法。5.1 第一步明确技能定义与边界动手写代码或提示词之前必须想清楚核心任务这个技能到底要解决什么问题例如“为电商产品图生成兼具营销性和可访问性的Alt文本”输入用户需要提供什么信息例如“产品图片URL、产品名称、核心卖点关键词”输出技能应该返回什么格式的结果例如“一段不超过125字符的Alt文本字符串以及一个JSON对象包含关键词密度分析”不做什么明确技能的边界避免功能臃肿。例如“本技能不负责图片内容审核不生成营销文案”把这些写成简单的文档这就是你后续编写skill.yaml和prompt.md的蓝图。5.2 第二步编写技能配置文件skill.yaml这是技能的“元数据”层决定了AI平台如何识别和调用它。一个最小化的skill.yaml应包含name: meu-novo-skill # 唯一标识符用小写字母和连字符 description: Uma breve descrição do que o skill faz. # 清晰的功能描述 author: Seu Nome version: 0.1.0 # 使用语义化版本控制 # 定义输入让用户知道该怎么用 input: parameters: - name: produto description: Nome do produto para análise. required: true schema: { type: string } - name: palavras_chave description: Lista de palavras-chave separadas por vírgula. required: false schema: { type: string } # 定义输出确保结果结构化 output: schema: type: object properties: alt_text: type: string description: O texto alternativo gerado. sugestoes: type: array items: { type: string } description: Sugestões de melhoria. required: [alt_text]关键细节output的schema部分至关重要。它使用JSON Schema来严格定义输出数据的结构。这不仅能指导AI生成正确的格式还能让下游程序如果你通过API调用技能可靠地解析结果。花时间学习一下JSON Schema的基本类型string,number,array,object和required属性会让你的技能专业很多。5.3 第三步撰写核心指令prompt.md这是技能的“大脑”是AI执行任务时所遵循的具体指令。prompt.md的质量直接决定技能效果。角色设定开篇明义告诉AI它在这个技能中扮演什么角色。“你是一个专业的SEO专家和内容策略师...”任务描述清晰、分步骤地描述任务流程。“你的任务是1. 分析以下产品信息2. 根据以下规则生成Alt文本...”规则与约束列出所有必须遵守的规则。这是保证输出稳定的关键。例如“Alt文本必须以产品名开头包含至少一个核心关键词长度在80-125字符之间避免使用‘图片显示了’等冗余短语...”输出格式示例提供一个甚至多个完美的输出样例。AI非常擅长模仿格式。例如“请严格按照以下JSON格式输出json { \alt_text\: \...\, \sugestoes\: [...] }”错误处理可以指导AI在输入不完整或不符合预期时如何响应。“如果未提供产品名称请询问用户并暂停任务。”我的建议是先在Chat界面用对话的方式反复调试你的提示词直到它能稳定输出你想要的结果。然后将这段调试好的对话内容精炼成结构清晰的prompt.md。5.4 第四步集成自定义代码可选但强大如果你的技能需要计算、数据转换或调用外部API就需要集成Python代码。在技能文件夹内创建一个files/目录。将你的Python脚本如calcular.py放在里面。在skill.yaml中通过files字段声明这些代码文件。在prompt.md中通过特定的“指令”不同平台语法不同告诉AI在何时以及如何调用这些函数。例如在Claude Skills中你可能会使用类似{{#file}}files/calcular.py{{/file}}的标签来引用代码并用自然语言说明“请使用calcular.py文件中的calcular_juros函数来处理利率数据”。避坑指南集成代码时务必注意安全性和简洁性。技能中的代码应在沙盒环境或受限权限下运行。避免引入复杂的第三方依赖尽量使用Python标准库。如果必须用外部库需要在技能文档中明确说明因为这可能会限制技能在特定平台上的兼容性。5.5 第五步本地测试与迭代不要直接上传到平台测试。先在本地进行模拟测试结构验证检查skill.yaml的语法是否正确可以使用在线YAML校验器。提示词模拟将prompt.md的内容结合一个示例输入粘贴到你常用的AI聊天界面如ChatGPT、Claude网页版看输出是否符合skill.yaml中定义的output schema。代码测试单独运行你的Python脚本确保逻辑正确。打包测试将整个技能文件夹压缩成ZIP然后在目标平台如Claude的测试环境上传试用观察实际行为。根据测试结果回头调整prompt.md的措辞、增加更具体的规则或者修改output schema。这个过程可能需要重复几次。6. 常见问题与排查技巧实录在创建、部署和使用技能的过程中我踩过不少坑。这里把一些典型问题和解决方法记录下来希望能帮你节省时间。6.1 技能上传失败或无法识别问题在Claude上传ZIP包后技能列表里没有出现或者显示为“无效技能”。排查检查ZIP包结构确保ZIP文件的根目录下直接就是skill.yaml和prompt.md等文件而不是外面还套了一层同名的文件夹。正确的结构alt-text.zip解压后得到skill.yaml, prompt.md, files/...。错误的结构alt-text.zip解压后得到alt-text/skill.yaml, alt-text/prompt.md...。在压缩时请选中技能文件夹内的所有文件进行压缩而不是压缩整个文件夹。检查YAML语法skill.yaml对缩进必须是空格不能是Tab和格式非常敏感。一个多余的冒号或缩进错误都会导致解析失败。使用在线的YAML解析器如yamlchecker.com验证你的文件。检查必需文件最基本的技能必须包含skill.yaml和prompt.md两个文件缺一不可。查看平台错误信息有些平台在上传失败时会给出简短的错误提示如“Invalid skill configuration”这是最重要的排查线索。6.2 技能被激活但输出不符合预期问题技能成功加载AI也似乎调用了它但生成的内容格式不对或者忽略了某些规则。排查强化prompt.md中的格式指令在prompt.md的末尾用非常明确和强硬的语气重申输出格式。例如“你必须且只能输出一个JSON对象其结构必须与下面定义的output schema完全一致。不要输出任何额外的解释、前缀或后缀。”提供更具体的示例在prompt.md中增加一个“示例对话”部分展示从用户输入到技能完美输出的完整过程。AI的模仿能力很强。简化输出模式如果最初定义的output schema太复杂例如嵌套过深的对象AI可能难以掌握。尝试先简化为扁平结构确保它能稳定输出后再逐步增加复杂度。检查技能冲突如果你同时激活了多个技能它们之间可能会产生干扰。尝试只激活当前需要的一个技能进行测试。6.3 在Antigravity中技能安装后不显示问题使用npx skills add命令安装成功但在Antigravity界面中找不到该技能。排查确认安装路径Antigravity的技能查找路径可能有多个。最常见的是~/.gemini/antigravity/skills/和~/.gemini/antigravity/.agents/skills/。使用命令行或文件管理器检查技能文件夹是否被正确安装到了其中一个目录下。手动移动正如我提供的自动化提示词中所做的那样尝试将技能文件夹从.agents/skills/手动复制或移动到顶层的skills/目录下。重启Antigravity有时需要完全关闭并重新启动Antigravity应用它才会重新扫描技能目录。检查技能兼容性Antigravity可能不完全兼容为Claude设计的技能规范。检查你的skill.yaml中是否有Antigravity不支持的字段。最稳妥的方法是参考Antigravity官方文档或示例技能。6.4 技能中的自定义代码不执行问题技能包含了Python文件但AI在响应中并没有调用或提及它计算结果也是错的可能是AI自己“算”的。排查平台支持度首先确认你使用的AI平台是否支持在技能中运行自定义代码。Claude的某些版本或配置可能禁用此功能。Antigravity作为IDE支持度通常更高。指令清晰度在prompt.md中你必须用非常清晰的指令告诉AI“现在去调用那个Python函数”。不能指望AI自动发现。例如“现在请使用files/calculadora.py文件中名为calcular的函数传入参数X和Y进行计算并将函数返回的结果填入最终输出的‘resultado’字段。”代码可访问性确保在skill.yaml中正确声明了代码文件并且AI有权限读取它。代码本身应该是自包含的避免复杂的系统调用。构建和维护这个技能库的过程让我对AI智能体的能力边界和扩展方式有了更深的理解。技能的本质是将人类模糊的、高层次的指令转化为AI可稳定执行的、低层次的标准化操作流程。它不仅是效率工具更是一种思维框架——逼迫我们去拆解任务、定义规则、明确产出。当你开始为自己构建技能时你会发现很多你原本以为需要“创造性”解决的任务其实都可以被结构化和自动化。这或许才是AI时代我们最需要掌握的新技能。