扣子对Agent Skills的定义

一、技能概述

技能（Skill）是用于扩展智能体功能的模块化能力，它包含了说明文件、元数据、代码脚本等，为智能体提供特定领域的专业知识、工作流程和最佳实践。扣子和扣子编程现已全面支持技能的开发与使用，通过扣子编程开发的技能可以在扣子对话任务中使用，让扣子 AI 按需加载不同的技能，从通用的智能体转化为垂直领域的专家。

I 什么是技能

技能可以将过去分散在提示词、代码片段或零散文档中的隐性知识，显性化、结构化地组织起来，让 AI Agent 按需、稳定地执行专业任务。你可以将技能看做是新员工的入职材料，将积累的工作经验和最佳实践打包为技能包，让扣子 AI 成为你专业领域的专家。

不同于一次性的提示词（Prompt），技能是可保存、复用、优化的任务解决方案，让 AI 从理解你的指令，变成掌握你的方法。如果一个任务的处理流程相对固定、可稳定重复操作，且需要一致、可靠的输出时，可以将其封装为技能，提供给通用智能体使用。

1 技能的工作机制

从本质上讲，每个技能都是一个结构固定的文件夹，它遵循统一的规范，清晰地描述了执行任务所需的标准作业流程（SOP）、方法论和参考模板。为保证对话效率，智能体并不会一次性加载技能的全部内容，而是通过“渐进式披露”机制，在对话中判断哪些技能与当前任务相关，然后仅加载完成任务所需的信息，从而避免上下文窗口过载。

一个标准的技能文件夹通常包含以下几个部分：

SKILL.md：技能的使用说明书和元数据文件，用于向智能体说明技能的名称和用途。智能体在启动时会始终加载元数据，以便决定何时以及如何调用该技能。
scripts/目录：存放可执行的代码文件，用于执行确定性的计算任务。
references/ 目录：存放技能相关的参考文档，例如第三方 API 文档、相关的规范和标准等参考资料、设计文档、测试报告等。
assets/ 目录：存放技能依赖的静态资源和模板，为智能体提供执行任务所需的额外信息，例如配置模板等模板文件、音视频文件等静态资源。

my-skill/
├── SKILL.md # 【必选】使用说明 + 元数据
├── scripts/ # 【可选】可执行代码
├── references/ # 【可选】参考文档
└── assets/ # 【可选】模板、资源文件

2 扣子中的技能

扣子编程和扣子现已全面支持技能的开发与使用，你可以：

① 在扣子编程开发你的技能：通过 AI 编程方式使用自然语言开发一个技能。例如：

1. 新人入职培训技能：企业 HR 提供新人入职培训的规则和 SOP，新员工入职时只需和扣子 AI 对话即可完成新人培训。
2. 视频生成技能：自动生成故事大纲、分集剧情、脚本制作和视频生成，短剧创作团队可以在扣子中直接上传素材、一键生成短剧。
3. 前端设计技能：沉淀独特的艺术风格与前端技术规范，UI 设计师可以在扣子编程中快速开发出风格类似的网页应用。

② 使用技能：发送你的具体指令，扣子 AI 会自动识别并加载任务相关的技能。一旦技能被触发，扣子 AI 无需通过大模型生成的方式去自主规划，而是通过技能中指定的操作流程和处理方式来完成任务。

1. 在扣子编程中使用技能：目前，所有扣子编程的集成服务均有配套的官方技能。在项目开发过程中，扣子 AI 会自行判断项目所需的集成服务，并加载对应的技能。同时，你也可以上传用于特定领域或流程的自定义技能。
2. 在扣子中使用技能：一个复杂的任务往往需要多个技能来协同完成，扣子提供了技能商店（https://www.coze.cn/skills）、虾评社区（https://xiaping.coze.com/），与开发者一起打造丰富完善的技能生态，解决技能的分发、消费、变现问题。企业旗舰版用户还可以构建企业专属的技能商店，实现企业内部的资源与经验共享。

II 技能和其他概念的区别

• 技能和提示词：系统提示词定义了智能体的全局人设和工作方式，例如智能体的身份、人设、语气或工作方式。这类设定通常对每一轮对话持续生效，用于约束整体输出风格；技能则提供特定领域的专业能力与方法支持，例如“基于指定模型进行财务数据分析”的能力。技能并非全程启用，而是根据用户的具体任务按需触发，仅在相关对话或任务场景中生效。

• 技能和工作流：技能是特定领域知识、方法和工具的集合，相当于一个“可复用的操作说明书”。它不强制规定具体的执行路径，而是为智能体提供判断依据与最佳实践，允许智能体在执行过程中保留一定的自主决策空间；工作流是预设好的流程编排，具有明确的步骤顺序与逻辑关系。每个环节的输入与输出都是确定的，执行路径固定，适用于强流程约束的自动化任务。

• 技能和插件：插件主要负责调用外部工具或服务的 API，负责能力的技术接入。 技能在此基础上进一步封装了使用策略与操作说明，不仅包含 API 调用脚本，还会明确说明在什么条件下、以何种方式调用这些能力，从而指导智能体合理地使用外部工具完成任务。

• 技能和 MCP：MCP 提供能力调用的接口，使智能体能够访问外部服务、系统或数据源； 技能则是围绕某一任务目标形成的完整解决方案，包含经验总结、流程说明与执行策略。在实际应用中，技能可以将 MCP 作为执行流程中的一部分：MCP 负责提供工具与数据能力，技能负责指导智能体如何获取、理解并使用这些能力来完成任务。

• 技能和 RAG 知识库：RAG 知识库主要用于为智能体提供已有文档与素材内容，适合信息检索与内容补充类场景。技能则侧重于针对具体问题总结出的标准操作流程（SOP）与最佳实践。在处理明确、聚焦的问题时，技能通常具备更高的针对性与执行效率；而 RAG 知识库在覆盖范围与信息完整性方面更具优势；技能可以将 RAG知识库 作为技能中的一部分。

III 技能的类型

根据技能的提供者和使用范围，技能可分为以下类型：

服务	技能类型	说明
扣子编程	官方编程技能	由扣子官方开发和维护的编程技能，不同编程项目能用的官方技能并不完全一样，系统会根据项目类型自动添加匹配的技能。
–	我的编程技能	手动上传的编程技能，这些技能仅限你个人使用。
扣子	官方技能	由扣子官方开发和维护的技能，通过技能商店面向所有用户开放。在对话中，扣子会按需自动调用官方技能完成任务。
–	第三方技能	扣子技能商店中，由其他第三方组织或扣子用户开发和维护的技能，同样面向所有用户开放。你需要先安装并开启第三方技能，扣子才会在对话中按需调用。需要注意的是，部分第三方技能是收费的，你可以在技能商店中看到收费技能的对应标识。
–	自定义技能	由你个人为特定领域或特定流程创建的技能，只有你本人才能编辑、发布、使用。你可以根据个人经验和工作需求来开发技能，例如某个工作场景的数据分析技能、文档编写和格式处理技能等。
–	企业技能	对于企业旗舰版套餐，员工开发的自定义技能可以发布到企业商店中，专供本企业内员工使用。通过企业商店，企业可以统一定制内部专属的工作流程，确保员工使用标准化的流程和最佳实践。

IV 如何开发技能

对于某个任务，如果你已经根据经验总结出了最佳操作路径和操作方式，那么可以考虑开发一个技能，将这些操作路径和操作方式固化在技能中，让智能体在遇到类似任务时，能够自动执行技能完成任务。

在扣子编程中开发技能的步骤如下：

① 在扣子编程首页，选择技能页签，并输入你的需求。

你可以描述技能的功能、用途、你希望的执行流程等，详细的描述可以帮助扣子 AI 更好地理解你的需求。另外，如果你有一些相关的材料、数据、文档等，可以同时上传，帮助扣子 AI 总结你的经验和工作流程。

② 2 扣子 AI 开发技能。
扣子 AI 会根据你的需求和材料，总结你的经验，并生成一个标准格式的技能文件包。如果你的需求比较复杂，扣子 AI 可能会通过多轮对话来询问你一些细节，例如你预期的流程、输出格式等。

③ 预览和测试技能。
你可以在右侧对话区通过对话来测试技能，查看扣子 AI 是否成功触发技能、按照你的预期执行工作流程。

④ 部署技能。
测试完成后需要部署技能，后续才能在扣子的对话任务中使用技能。

关于通过扣子编程开发技能的详细步骤，可参考开发技能。

V 如何使用技能

你可以在扣子编程中使用技能，辅助扣子 AI 开发项目；也可以在扣子中使用技能，协助扣子 AI 处理复杂任务。

1. 扣子编程：在扣子编程首页选择对应的项目后，你可以在对话框中输入任务指令，然后单击技能来添加技能。项目开发过程中，扣子 AI 会在已添加的技能中自动搜索并加载合适的技能。关于使用技能的详细说明，可参考在扣子编程中使用技能。

2. 扣子：部署技能之后，你可以在扣子中通过对话来触发技能。发送你的具体指令，扣子 AI 会自动识别任务相关的技能，并加载技能来完成任务。
   关于在扣子中使用技能的详细说明，可参考在扣子对话中使用技能。

二 开发技能

扣子编程现已支持通过 AI 编程的方式开发技能。本文档介绍如何在扣子编程中创建你的自定义技能，目前支持通过自然语言开发技能，或者将你上传的技能文件打包为技能。

I 功能概述

技能是用于扩展智能体功能的模块化能力，它包含了说明文件、元数据、代码脚本等，为智能体提供特定领域的专业知识、工作流程和最佳实践。在扣子编程中，你可以直接输入你想要的技能细节，例如技能的目标、执行流程、预期输出等，扣子 AI 会自动为你创建一个格式标准的技能文件包，并编写 skills.md 等对应的技能文件、打包需要的资源。

你无需手动编辑文件，扣子 AI 帮助你将专业流程知识封装为可复用的模块化资源，让通用模型快速变身垂直领域专家。

如果你已经准备了开发技能所需的相关资料，可以帮助扣子 AI 理解你的需求、你期望的工作流程、数据处理方式等，也可以在对话中提供给扣子 AI。例如，你可以输入以下要求，并上传术语表，让扣子编程为你开发一个文档翻译的技能：

请帮我开发一个中英文互译的技能，遵循通用的技术文档规范和风格指南，并使用指定的产品术语表。

说明

• 开发调试完成的技能需要部署到扣子，才能在扣子对话区中使用。
• 通过扣子编程开发的技能，暂不支持直接在扣子编程中使用。你需要先将技能的 .skill 文件下载到本地，再通过本地上传功能上传到编程技能列表中。
• 如果你已经通过扣子对话探索出了某个任务的最佳执行方式，可以直接将其制作为技能，详细说明可参考制作技能。
• 在团队版和企业版中，企业超级管理员可以通过功能访问控制和空间资源可见性，控制成员可见的功能入口和空间资源范围。如果你未看到预期的功能和资源，请联系企业超级管理员确认。更多信息，请参考功能访问控制和空间资源访问控制。

II 通过自然语言生成技能

参考以下流程，通过 AI 编程开发你的技能。

1 步骤一：需求澄清

① 输入你的需求。

1. 在扣子编程首页，单击技能选项卡。
2. 在文本框输入你的提示词。
   通过自然语言创建技能时，提示词的撰写直接决定技能的逻辑、交互效果和稳定性，核心要求是清晰、结构化、可执行。在提示词中，你可以提供：

• 技能的用途、可处理的任务类型、输出格式等。例如，“用于将指定图片切割为4×4 的拼图块并生成可交互的游戏”。
• 技能的使用场景，包括用户的触发方式等。例如，“当用户提及‘帮我做个拼图游戏’时，自动触发此技能”。
• 技能的输出格式。例如“输出一个可直接在浏览器中体验的 HTML 拼图游戏文件”。
• 技能相关的脚本、参考文档或资源文件。

你可以参考以下格式，输出你的需求：

我想创建一个[功能名称]的 Skill，用于[解决什么问题]，当用户[触发场景]时使用，输出[期望格式和内容]。

例如：

我想创建一个拼图游戏生成器的 Skill，用于将用户上传的图片自动切割成 4×4 的拼图块并生成可交互的游戏，当用户说"帮我做个拼图游戏"或上传图片要求生成拼图时使用，输出一个
可直接在浏览器中玩的 HTML 拼图游戏文件。

我想创建一个客户邮件助手的 Skill，用于快速撰写专业的商务邮件，当用户需要回复询价、跟进客户或处理投诉时使用，输出可直接发送的邮件正文。

我想创建一个合同风险审核的 Skill，用于识别合同中的风险条款并给出修改建议，当用户上传合同文件时使用，输出风险点清单和具体修改建议，合同风险条款可参考附件

3. （可选）进阶配置：通过上传附件、选择协作模式、选择编程模型，让扣子 AI 生成的结果更精准、更符合你的预期。

酌情上传一些图片或文件，作为附加信息提供给扣子 AI，以便扣子 AI 能更理解你的需求。例如对于技术文档翻译技能，可以上传一个术语表，以便模型使用技能翻译文档时能保证术语一致性和翻译准确性。

① 上传附件	② 选择协作模式	③ 选择编程模型

4. 在键盘中敲击回车，开始开发你的项目。
   扣子 AI 会根据你输入的提示词来开始设计技能、开发技能，并自动为项目设置名称。
   （可选）澄清你的需求。
   扣子 AI 收到你的提示词之后，如果判断提示词不明确、缺失关键信息，则会向你发送提示，请求补充缺失的关键信息。例如开发者要求“开发一个文档格式处理技能”，但未提及技能的使用场景和目标格式等背景信息，此时扣子 AI 会主动追问相关细节。
   澄清需求时，你同样可以上传附件，为扣子 AI 提供相关的脚本、参考文档或资源文件。

2 步骤二：AI 编程开发技能

扣子 AI 收到你的需求之后，将立即启动需求分析，并规划技能的文件结构，包括 SKILL.md 的文件内容、是否需要辅助的 references 文档、是否需要创建脚本等。创建文件结构、撰写技能并打包技能、验证结果之后，扣子 AI 会提示你任务已完成，你可以在右侧预览区域通过对话来触发技能、查看技能的执行效果。

Image

3 步骤三：预览与测试

初步生成后端代码后，扣子 AI 会自动生成测试用例并完成一轮单元测试。测试通过后扣子 AI 会提供后端代码的预览，同时提醒你验收，你可以在右侧预览页面通过发送消息来触发技能，测试技能的实际效果。

技能预览界面如下：

Image

在预览与测试的环节中，你可以通过以下操作预览并测试技能。

操作 说明
调用技能

技能打包完毕后，你可以在右侧预览页面体验技能的实际效果。

在预览页面输入你的要求，扣子 AI 会自动触发技能并执行。例如，对于一个查询天气的技能，你可以输入“今天北京天气怎么样”。

处理任务时，扣子 AI 会参考对话上下文判断你的意图和场景，你也可以在页面右上角单击图标清空上下文。

全面测试

使用实际场景全面测试你的技能。技能测试通常能发现指令中的疏漏、描述的模糊之处、业务处理的边界问题。通常建议关注以下问题：

是否稳定触发：验证技能的触发条件，是否能在预期的场景中稳定触发。如果扣子 AI 调用了技能，对话区域会展示“完成技能加载”的提示。
如果未触发，你可以让扣子 AI 约束触发条件，或者自行编辑 SKILL.md 的 description 部分，明确说明技能的触发条件。注意修改 SKILL.md 之后，你需要通知扣子 AI 重新打包，以体验这个最新版本的技能。
是否稳定执行：检查技能的处理流程，查看是否有跳过或遗漏执行的步骤、最终输出的结果是否符合要求。
是否能覆盖实际业务场景需求：丰富的测试案例能帮助你全面测试技能的表现，建议挑选一些常用的业务场景 query 来测试技能的处理效果。也可以增加一些技能能力之外的问题、边界案例来测试技能效果。例如用户指令模糊、文件格式不符合要求、数据缺失等情况下，技能是否能优化处理。

III 上传技能包

如果你已经拥有了一个技能包，可以通过扣子编程的“上传技能包”功能，将技能包上传到扣子，扣子 AI 会自动解析技能包、执行安全性检测、并重新打包，以便部署到扣子对话中使用。上传技能包功能适用于已完成技能开发的场景，例如已经通过第三方工具生成了技能文件、自己在本地编写了技能文件等等。

在扣子编程首页文本输入框中，选择技能页签。
单击“上传技能包”的图标，并上传本地技能包文件。
说明

你上传的技能包应符合以下格式要求：

必须是 .skill 或者 .ZIP 后缀的文件。
建议技能包应符合技能（Skill）的业界统一规范格式，例如至少包含 SKILL.md 文件，帮助扣子了解这个技能是什么、如何使用。如果不符合格式规范，扣子 AI 会自行改造为正确格式，这个过程中也可能会通过对话来向你收集技能的更多细节。
Image

扣子 AI 会自动解析和检测技能包，如果存在敏感信息的配置，会主动提示你配置为环境变量。
Image
完成技能包的适配之后，你可以在右侧预览区域通过对话来触发技能、查看技能的执行效果。
Image

IV 改造技能

测试并调优技能之后，这个技能就已经可以发布到扣子，在对话中使用了。但优秀的技能是不断完善和优化的，如果你认为这个技能在功能或者用途上仍有可改进之处，你也可以在扣子编程中通过自然语言或编写文件的方式，和扣子 AI 一起迭代你的技能。

1 编辑并更新技能

你可以和扣子 AI 一起持续优化技能，也可以自行编辑技能文件包，直到实现预期的效果。

编辑方式 说明 示例
扣子 AI 对话

在对话区中通过自然语言描述你的修改建议，和扣子 AI 一起优化你的技能。例如输入以下提示词：

Plain Text
扩大一下触发条件，如果用户提及“翻译文档”，就调用这个技能处理。
Image

手动编辑技能包

在页面右上角单击文件夹图标，打开文件树，找到技能包文件夹（通常以技能名称命名），直接编辑你想修改的文件。例如，修改 SKILL.md 文件，自行约束触发规则。

说明

修改文件之后，必须重新打包技能，才能体验修改后的技能，同时扣子 AI 会自动生成一个开发版本供你追溯。修改方式如下：

通过对话方式，通知扣子 AI 重新打包以供你体验、使用。
在预览页签右上角单击更新技能图标。
编辑文件：
Image

更新技能：
Image

2 调用外部 API

扣子技能暂时不支持集成能力。如果你的技能需要调用外部 API、使用自定义模型完成特定功能，可以将 API 接口文档（Markdown 格式）提供给扣子 AI，让智能体自行调用 API 实现对应的能力。

其中，API Key 等鉴权信息可以通过环境变量传入，也可以让智能体在调用技能时要求用户输入自己的 API Key。

3 开发“按次付费”技能

如果你希望上架的技能支持按次付费模式，那么你的技能需要满足如下条件：

技能需调用 API 来提供服务。
在开发提示词中，明确基于 API 开发技能。
通过环境变量，提供调用该 API 所需的凭证（如 API Key 或 Token）。
当用户按次购买此技能时，系统将通过该凭证来识别和计量用户的每一次调用，并根据你指定的价格，收取对应的积分。按次付费说明，请参考付费设置。
例如调用火山方舟的生图 API 开发生图技能，你可以输入如下指令，并上传 API 接口文档。

指令

Plain Text
这是图片生成的接口文档，请参考这份接口文档帮我创建图片生成skill
附件

图片生成集成.md

Image

在开发过程中，扣子 AI 会自动识别出需要的 API Key，并创建一个对应的环境变量。此时，你需要输入对应的 API Key，并单击设置为开发者变量。

Image

4 回滚开发版本

扣子 AI 使用当前的先进模型来完成任务，但由于模型生成代码的随机性，有时可能无法完全满足你的需求，生成了不符合预期的技能，或者出现了反复修复失败的故障，此时你可以使用回滚版本功能，将技能恢复到之前正常的版本状态。

在对话区顶部单击版本历史图标，找到要恢复的版本，在其右侧单击回滚图标。

Image

V 后续操作

1 部署技能

完成技能的开发与调试之后，你需要部署技能，才能在扣子对话中使用。在技能的开发页面右上角单击打包，根据页面提示确认技能的部署配置之后，单击开始打包即可。详细操作步骤可参考发布技能。

Image

扣子编程会自动执行技能的打包、构建和部署，部署成功后，你可以根据页面提示单击立即体验，在扣子对话中触发技能，体验技能的效果。

Image

2 下载技能包

通过扣子编程开发的技能，你可以下载其技能包到本地，再重新上传到编程技能中，辅助扣子 AI 开发项目。即在技能开发的目录树中，找到 .skill 文件下载到本地。

Image

3 使用技能

扣子编程：在扣子编程中使用技能，辅助扣子 AI 开发项目。具体操作，请参考在扣子编程中使用技能。
Image
扣子：在扣子中使用技能，协助扣子 AI 处理复杂任务。具体操作，请参考在扣子对话中使用技能。
Image

发布技能

在扣子编程创建了自己的技能之后，你可以将技能发布到扣子对话中，供你个人使用。对于企业版套餐，员工可以在企业范围内共享技能。对于技能的开发者，你也可以将自己开发的优秀技能发布到扣子技能商店，以供其他扣子用户付费使用，将你的技能变现。

说明

在团队版和企业版中，企业超级管理员可以通过功能访问控制​和空间资源可见性，控制成员可见的功能入口和空间资源范围。如果你未看到预期的功能和资源，请联系企业超级管理员确认。更多信息，请参考功能访问控制和空间资源访问控制。

发布技能
在扣子编程中创建的自定义技能，必须部署之后才能在扣子对话中使用。默认情况下，自定义技能只能被所有者本人使用。

参考以下步骤发布技能：

登录扣子编程，并在主页左上角选择工作空间。
在左侧导航栏中单击项目管理，找到自己已经调试好的技能。
打开技能，在页面右上角单击打包。
（可选）配置生产环境变量。
在生产环境中为项目配置特定的环境变量，例如 API Key、数据库连接字符串、飞书文档地址等敏感信息，以免将这些信息硬编码在代码中导致安全风险。
你可以新建环境变量、查看本次部署新增和变更的环境变量。关于环境变量的具体说明请参考技能环境变量。
说明

打包时新建的变量，仅在生产环境生效，不会被添加至开发环境。

（可选）开启加密部署。
加密部署后，模型在运行技能时，无法读取脚本文件内容，会直接执行脚本文件。这种方式可以有效保障脚本文件的隐私性和安全性，但是也会牺牲一定灵活度，因为模型无法按需优化脚本、在执行失败时自动排障和修复。
说明

如果你计划将技能发布为技能商店的非开源技能，则建议开启加密部署，以免脚本内容泄露。同时，开发者也需要保证脚本文件的代码质量，以免脚本执行失败影响用户体验。

单击打包技能。
扣子编程将自动进行打包操作。你可以在部署页面查看部署的进展和部署日志。部署过程可能需要几秒钟到几分钟，请耐心等待。部署过程中，你可以随时取消部署。
Image
扣子编程会自动执行技能的打包、构建和部署，部署成功后，你可以根据页面提示单击立即体验，在扣子对话中触发技能，体验技能的效果。

查看我的技能：

在扣子技能商店 -> 我的技能 -> 我创建的技能中，查看你已经创建并发布的自定义技能。

Image

使用技能：

Image

相关操作
将技能上架到扣子商店
扣子官方制作了一批常用技能，已发布至扣子商店供所有用户使用。作为技能开发者，你也可以将自己开发的优秀技能设置为付费模式、设置合理的价格，并上架到技能商店，将你的技能变现。

详细操作步骤可参考将技能上架到技能商店。如果上架付费技能，你需要先开通支付渠道，详细步骤可参考开通收款账户。

将技能上架到企业
企业市场是扣子专为企业组织打造的内部技能分发中心。对于涉及核心业务逻辑或仅限内部使用的技能，上架到企业市场既能保护知识产权，又能提升内部协作效率。

详细操作步骤可参考将技能上架到企业市场。

说明

仅团队尊享版、企业旗舰版支持在企业范围内分享技能。其他版本用户请使用扣子商店中的公开技能。

使用技能

使用技能
技能是一个专为特定领域设计的知识库和工具包，用于指导智能体如何完成指定的任务。使用技能后，扣子 AI 会在处理专业任务上有更好的表现，例如根据指定的风格指南与格式撰写文档、根据指定的设计风格开发一个应用等。本文档介绍如何在扣子编程、扣子中使用技能。

说明

在团队版和企业版中，企业超级管理员可以通过功能访问控制​和空间资源可见性，控制成员可见的功能入口和空间资源范围。如果你未看到预期的功能和资源，请联系企业超级管理员确认。更多信息，请参考功能访问控制和空间资源访问控制。

使用场景
扣子 AI 会加载技能的介绍信息，如果判断技能与当前任务有关，将自动安装并触发技能来完成任务。通过技能的渐进式披露机制，扣子 AI 可以在节约上下文窗口的同时访问专业领域的知识。

在不同使用环境下，技能对应不同的使用场景，例如：

在扣子编程中辅助开发
使用前端设计类技能，让扣子 AI 根据指定的设计风格开发网页应用。
使用流程类技能，让扣子 AI 根据指定的提取流程开发发票提取工作流。
在扣子中协助处理复杂任务
使用写作类技能，让扣子 AI 根据指定的风格指南与格式撰写文档。
使用审核类技能，让扣子 AI 依据公司的法务标准审查合同文件。
在扣子编程中使用技能
在扣子编程中开发智能体、工作流或应用等项目时，扣子 AI 会在已添加的技能中自动搜索并加载合适的技能，然后读取技能的使用指南，并遵循该指南来完成开发任务。

说明

最多添加 50 个编程技能。
存在同名技能时，扣子 AI 会根据技能的功能描述，选择最贴合当前任务的技能。如果功能描述类似，则遵循“自定义技能 > 官方技能”以及“最新上传 > 早期上传”的选择原则。
技能类型
在扣子编程中，扣子 AI 可以加载已添加的官方技能和我的技能。

官方技能：由扣子官方开发和维护的编程技能。不同项目能用的官方技能并不完全一样，系统会根据项目类型自动添加匹配的技能。目前，所有扣子编程的集成服务均有配套的官方技能。如果要使用外部集成相关的技能，需要先完成集成配置。关于集成服务的更多信息，请参考集成服务概述。
说明

请勿随意移除官方技能，以免扣子 AI 在开发过程中因无法加载所需技能而报错。

我的技能：由开发者自行维护的自定义技能。你可以根据个人经验和工作需求来开发技能并使用。自定义的编程技能仅限你本人使用。
步骤一：上传你的技能
如果你要使用自定义技能，包括通过扣子编程以及通过其他渠道开发的技能，均需要通过本地上传方式，将技能包上传到扣子编程。

说明

通过扣子编程开发的技能，暂不支持直接在扣子编程中使用。你需要先将技能的 .skill 文件下载到本地，再通过本地上传功能上传到编程技能列表中。具体操作，请参考下载技能包。
技能商店中的技能不支持在扣子编程中使用。
在开发项目对话框中，单击技能。
在编程技能面板中，选择创建技能 > 本地上传。
选择待上传的技能包。
Image

Image

步骤二：添加技能
上传技能包后， 你在当前账号下均可以使用该自定义技能。但为扣子 AI 添加自定义技能是单次生效的，每次开启新任务时，你都需要重新添加所需的自定义技能。

在开发项目对话框中，单击技能。
在我的技能中，单击目标技能对应的添加。
Image
步骤三：扣子 AI 加载技能
添加技能后，扣子 AI 会在项目开发过程中，根据当前任务和上下文，自动搜索并加载合适的技能，然后读取技能的使用指南，并遵循该指南来完成开发任务。此外，你也可以在对话中通过自然语言明确指定需要使用的技能。

在任务开发过程中，你也可以随时单击对话框中的技能来添加更多技能，新添加的技能将在下一轮对话中生效。

例如，当你需要开发一个视觉风格鲜明的网页应用时，可以上传并添加一个前端设计类技能，扣子 AI 会加载该技能及其他所需官方技能来完成开发任务。

Image

在扣子中使用技能
说明

技能数量限制：每个用户最多只能启用 30 个第三方技能，其他类型的技能无数量限制。
企业技能商店限制：
套餐限制：仅团队尊享版、企业旗舰版支持企业技能商店。
角色限制：企业技能商店不面向企业访客开放；仅企业员工可发布、查看和使用企业市场中的技能。
在扣子首页的对话框中输入你的任务指令，敲击回车键即可发起一个对话任务。扣子 AI 会根据你的任务指令，自动在技能商店中查找相关的技能。扣子 AI 会加载技能的介绍信息，如果判断技能与当前任务有关，将自动安装并触发技能来完成任务。更多信息，请参考使用技能。

Image

你也可以在对话中指定要使用的技能：

在商店中选用技能：在技能商店中选择感兴趣的技能，安装之后再单击使用，页面会自动跳转至扣子首页，输入你的任务要求即可。
选择商店技能：

Image

使用商店技能：

Image

在对话框中指定技能：
在 Agent 对话输入框中输入 /，并在技能页签中选择要使用的技能。

Image

在 Agent 对话输入框中单击➕，选择技能。

Image

技能环境变量

技能环境变量
为避免技能（Skill）在运行过程中泄露 API Key、鉴权秘钥、OAuth Token 等敏感信息，你可以使用环境变量来安全地存储和管理这些凭证。

根据加载方式，我们将环境变量分为以下类型：

常规变量：Agent 加载技能时，会直接将这类变量加载到运行环境中。由于使用者在查看智能体的思考和规划过程时可能会看到变量的值，因此常规变量适合存储非敏感信息，例如 API 的 Base URL。
凭证变量：为了保障凭证安全，当 Agent 加载技能时，系统使用占位符来代替凭证变量。只有在技能实际发起 API 调用时，系统才会通过服务端代理加载真实凭证。
说明

在团队版和企业版中，企业超级管理员可以通过功能访问控制​和空间资源可见性，控制成员可见的功能入口和空间资源范围。如果你未看到预期的功能和资源，请联系企业超级管理员确认。更多信息，请参考功能访问控制和空间资源访问控制。

凭证变量
认证方式
凭证变量支持以下两种认证方式：

API Key：适用于通过 API 密钥进行鉴权的场景，例如调用火山方舟模型 API。
OAuth：适用于需要 OAuth 协议授权的场景。授权方式包括：
平台授权：扣子官方已集成的常用第三方平台（如飞书、Notion 等），开发者无需自行配置 OAuth 参数。
自建授权：对于扣子未支持的平台，或者开发者希望使用自己的授权参数，可以手动配置 OAuth 授权所需的所有参数。
赋值方式
根据由谁提供凭证，凭证变量分为以下两种：

开发者变量：由技能开发者填写变量值，Agent 调用技能时，使用开发者的密钥等敏感信息发送请求。开发者变量通常是全局固定参数，不因用户的变化而改变，例如第三方服务的密钥。
消费者变量：技能安装时将提醒用户填写变量值，使用消费者的秘钥，例如用户自己的公众号 AppID、secret 等。不同用户的变量值相互隔离，互不干扰。
使用场景
技能环境变量目前支持以下典型场景：

存储常规配置：用于存放非敏感、但不希望硬编码在代码中的信息，例如 API 的 Base URL。
API Key 鉴权：在调用需 API Key 作为凭证的接口时使用，例如火山方舟模型 API。
微信公众号消息鉴权：配置微信公众号凭证后，所有请求将通过固定出口 IP (115.190.189.7) 发送。你可以将此 IP 添加到微信公众号的 IP 白名单中。
OAuth 授权：支持平台授权和自建授权两种方式，用于需要 OAuth 认证的服务集成。
注意事项
创建方式：在扣子编程中通过 AI 编程来创建技能时，支持使用凭证变量；在扣子对话中制作的技能不支持此功能。
安全提醒：关于如何安全开发与使用技能的更多信息，可参考技能安全指南。
域名配置：每个凭证变量都会关联一个域名列表。为防止凭证泄漏，当 Agent 使用该凭证调用外部 API 时，扣子平台会强制校验请求的域名是否在该列表中，以防止攻击者将凭证恶意发送到未授权的服务器。
对于官方托管的凭证（例如火山方舟、微信公众号、OAuth 平台授权），其关联域名由扣子平台维护，不支持修改。
对于扣子编程提示你自行设置的请求域名，请谨慎配置。
设置常规变量
技能常规变量的创建方式和普通环境变量一致，你可以参考管理环境变量文档查看详细说明。

创建环境变量：
Image

请扣子 AI 设置环境变量：
Plain Text
将 baseurl 设置为环境变量
Image

设置凭证变量
步骤一：创建凭证变量
在 AI 编程中，你可以通过以下方式创建凭证变量：

自动识别：对于需要使用秘钥等敏感信息的 AI 编程任务，扣子 AI 会自动识别并提示你将敏感字段封装为变量。例如要求调用火山方舟模型，扣子 AI 将提示你将 API Key 配置为凭证变量。
主动指令：对于已开发完成的技能，你可以直接向 AI 发送指令，例如：“请帮我识别代码中的敏感凭证信息，并进行加密。”
Image

步骤二：设置凭证变量
扣子 AI 识别到敏感凭证后，会根据凭证变量的类型（API Key 或 OAuth），弹出对应的设置卡片。

API Key 类型
对于 API Key 类型的变量，你需要选择配置方式。例如某个技能需要调用火山方舟模型 API，则需要设置：

开发者变量：直接填写变量值，并单击继续。技能运行时将使用你填写的值发起请求。
Image
消费者变量：单击设为消费侧变量，无需填写具体值，技能安装和运行时将由最终消费者自行填写凭证内容。
Image
OAuth 类型
对于 OAuth 类型的变量，你需要选择授权方式，再设置配置方式。以下操作以创建一个“查询飞书云文档”的技能为例，扣子 AI 识别出需要编写脚本调用飞书 API，而飞书平台支持 OAuth 授权，因此提示用户选择授权方式。

选择授权方式。
平台授权：扣子官方已集成的常用第三方平台（如飞书、Notion 等），开发者无需自行配置 OAuth 参数。
自建授权：如果平台未被官方集成，选择此项并手动配置所有 OAuth 参数。
Image
选择赋值方式，即使用开发者还是消费者的秘钥。
Image
平台授权
自建授权
如果选择平台授权，扣子 AI 会进一步提示选择凭证变量的赋值方式。

消费者授权：无需填写具体值，技能安装和运行时将由最终消费者自行完成 OAuth 授权。
开发者授权：根据页面提示，登录你的飞书账号，完成 OAuth 授权。技能运行时将使用你的账号权限发起 API 请求，查阅飞书文档。
Image
完成设置之后，扣子 AI 将自动编写代码，完成技能的开发。
步骤三：调试技能
技能开发完成后，扣子 AI 会提醒你调试技能，你可以输入简单的问题，查看凭证变量的设置是否符合预期。

开发者变量：技能运行时将自动使用开发者设置的变量值来发起请求，消费者对此无感知。
消费者变量：调试技能时，系统会弹出凭证填写窗口，填写完成后将独立保存用户的凭证信息，技能运行时将使用该用户配置的变量值来发起请求。
Image

Image

相关操作
查看环境变量
添加环境变量后，你可以新建标签页，打开环境变量标签查看所有已配置的环境变量。

打开环境变量页面。
Image

查看环境变量。
Image

修改环境变量
修改变量类型：直接和扣子 AI 对话，要求修改变量类型。例如：
Plain Text
帮我把 API_KEY 改成消费者变量
修改变量名称或值（开发者变量）：
打开 环境变量 标签页。
找到您想修改的变量，在其右侧的折叠菜单中单击 编辑。
Image
修改已配置的凭证（消费者变量）：
技能的消费者可以按以下步骤修改他们自己配置的凭证：
前往 扣子技能商店。
在 我安装的 或 我创建的 列表中找到对应的技能。
点击授权/配置按钮，即可重新配置变量值。
Image
部署时设置凭证变量
在开发环境完成凭证变量配置后，所有凭证变量将跟随技能一同部署到生产环境。 你也可以直接在部署页面修改凭证变量的值。

Image

如果在开发环境修改了环境变量，部署时你将能看到修改前后的差异，以便最终确认。

部署提醒：

Image

查看差异：

Image

常见问题
调用技能时，报错环境变量问题
配置开发者变量，但使用技能时智能体要求提供凭证
如何将开发者环境变量转换为消费者环境变量
模型重新配置环境变量后，部署页面出现重复的变量
上架商店时提示「skill内的敏感信息校验未通过，请求域名为空」
使用技能时提示授权失败，如何解决？

技能常见问题

技能常见问题
技能开发技巧
我不会写代码，也能在扣子编程里开发技能吗？
可以。

扣子编程支持通过自然语言直接开发技能。你只需要描述技能的目标、使用场景、执行流程和预期输出，扣子 AI 会自动：

设计技能结构；
生成 SKILL.md 等标准技能文件；
按需创建脚本、参考文档和资源文件；
将技能打包为可直接运行和部署的技能包。
整个过程无需手动编辑文件。
用自然语言开发技能时，提示词应该怎么写，才不容易翻车？
核心原则是：清晰、结构化、可执行。

在提示词中，建议明确说明：

技能要解决什么问题、能处理哪些任务；
在什么场景下触发技能；
技能的输出形式（例如文档、HTML 文件、分析结果等）；
是否有脚本、规范、术语表、参考资料可供使用。
如果关键信息不足，扣子 AI 会主动追问补充细节；你也可以在澄清阶段继续上传附件。
技能是如何被生成、预览和测试的？
通过自然语言提交需求后，扣子 AI 会自动完成以下流程：

分析需求并规划技能文件结构；
生成 SKILL.md、脚本和相关资源；
自动创建测试用例并完成一轮单元测试；
在右侧预览区提供可直接触发的技能体验。
你可以在预览区通过对话反复触发技能，验证是否稳定触发、稳定执行、覆盖真实业务场景。

如果我已经有一个技能文件包，能直接用吗？
可以。

你可以使用「上传技能包」功能，将本地已有的技能包（.skill 或 .zip）上传到扣子编程。

系统会自动：

解析技能结构；
检查安全性与规范性；
识别敏感信息并提示配置为环境变量；
重新打包，使其可在扣子对话中使用。
即使格式不完全规范，扣子 AI 也会在上传过程中协助补全和改造。
技能生成后还能继续优化或回滚吗？
可以。

你可以通过两种方式持续迭代技能：

自然语言优化：直接在对话中告诉扣子 AI 如何修改技能逻辑或触发条件。
手动编辑文件：打开技能文件树，直接编辑 SKILL.md 或脚本文件，并让扣子 AI 重新打包。
如果某次生成效果不理想，还可以通过版本历史功能回滚到之前的稳定版本。
使用相关
扣子智能体可以调用技能吗？
开发、部署好的技能目前仅支持在扣子对话中使用，你在扣子编程开发的智能体、工作流和应用暂不支持调用技能。

我在扣子编程里开发完技能后，如何在扣子对话中使用？
技能必须先部署，才能在扣子对话中使用。

基本流程是：

在扣子编程中完成技能开发和调试；
单击技能页面右上角的「部署」，按需设置部署参数，等待部署完成；
部署成功后，即可在扣子对话中触发和使用该技能。
若未上架技能商店，部署后的技能仅技能所有者本人可用。

技能部署完成后，在哪里查看和管理我发布的技能？
你可以在以下位置查看已创建和发布的技能：

扣子技能商店 → 我的技能 → 我创建的技能
在这里可以进行后续操作，例如上架、更新、下架或删除技能。
如何切换技能绑定的授权账号？
已授权的技能，如果授权的账号发生变更或授权失效，你可以重新授权。

在扣子左侧导航栏选择技能市场。
单击我的技能页签，选择目标技能。
单击更多 (⋮) 按钮，选择重新授权。根据页面提示，完成新的授权流程。
重新部署技能之后，如何在扣子对话中使用最新版本？
扣子对话默认会使用技能的最新部署版本。如果你在更新技能后发现对话中调用的仍是旧版本，这通常是由于当前会话仍在持续使用旧版，尚未重新加载新版本。

要解决此问题，你可以尝试发送以下指令，让扣子重新加载最新版本：

Plain Text
帮我重新加载一下 xx 技能。
安全相关
技能需要调用外部 API ，如何安全管理密钥
当技能需要调用外部 API、第三方服务或受保护资源时，不应将 API Key、Secret 等敏感信息直接写入代码。此类场景应使用技能凭证变量来统一管理和使用敏感凭证。

在扣子编程中，凭证变量支持两种配置方式：

开发者变量：由开发者填写并维护密钥，技能运行时统一使用该 Key 发起请求，消费者无需感知。
消费者变量：由消费者在安装或运行技能时填写自己的 Key，不同用户的凭证相互隔离，技能会自动使用当前用户配置的凭证发起请求。
在开发过程中，扣子编程会自动识别代码或接口文档中的敏感凭证信息，并提示将其封装为凭证变量；对已完成的技能，也可主动要求系统进行敏感信息识别和加密处理。

所有凭证变量均可在「环境变量」中统一管理，支持在部署前或部署后进行修改。通过这一机制，开发者无需自行处理加解密逻辑，即可在保障安全性的同时，灵活支持不同的凭证使用模式。

调用技能时，报错环境变量问题
通过扣子编程开发技能时，如果在预览页面调用技能失败，页面报错环境变量相关的问题，你可以通过以下步骤排查问题，也可以直接告知 agent 引导其协助排查。

打开对应的脚本文件，检查是否已引入 coze 的 request 包。
Image
定位到实际的请求代码位置，确认敏感信息是否已被正确替换为环境变量。
Image
如果以上两步没有问题，则检查环境变量中填写的凭证信息是否正确。
配置开发者变量，但使用技能时智能体要求提供凭证
如果已配置环境变量且脚本无问题，但预览或使用技能时扣子 AI 仍要求提供凭证，可直接在扣子或预览页面告知扣子 AI 已配置环境变量，并让其直接执行相关脚本：

Image

如果脚本执行成功：说明环境变量配置无误。问题可能出在技能的 SKILL.md 引导话术里， 你可以通过自然语言指令让扣子 AI 修改引导内容。
如果脚本执行失败：说明脚本可能存在其他运行问题，需要进一步检查脚本逻辑。
如何将开发者环境变量转换为消费者环境变量
对于已经配置的环境变量，目前暂不支持直接在环境变量页签中可视化转换变量类型，但是你可以通过自然语言指令让扣子 AI 重新配置脚本的环境变量，再重新配置凭证信息即可。

Image

模型重新配置环境变量后，部署页面出现重复的变量
可以手动删除已在开发环境中移除的冗余凭证变量。

Image

上架商店时提示「skill内的敏感信息校验未通过，请求域名为空」
进入扣子编程对应的技能项目，直接向 agent 发送指令，要求其更新凭证即可。

使用技能时提示授权失败，如何解决？
授权失败通常是由于 API Key 等授权信息填写错误。请首先检查凭证变量的配置是否正确。

如果你是基于扣子商店的技能进行复制和改造，或者是直接复制自己的技能，则可能是由于变量配置中 {skill_id} 不正确导致授权失败。

问题原因：扣子 AI 会在代码中使用 COZE{凭证Name}{skill_id} 格式的占位符。在复制技能时，AI 可能没有更新代码中的 {skill_id} 部分，导致其与新技能的 ID 不匹配。
解决方法：在这种情况下，你需要从技能开发页面的 URL 中获取正确的 {skill_id}，然后与扣子 AI 对话，要求它在代码中重新配置该 ID。例如：
Plain Text
请帮我重新设置下代码中的凭证 Key，{skill_id} 应该是 7611011370737418****
Image

上架相关
将技能上架到技能商店，需要满足哪些条件？
在上架前，请确保：

技能已创建并完成部署；
如果是付费技能，已开通收款账户；
你是技能的所有者。
上架时需要填写技能名称、简介、封面图、详细介绍、分类、精选案例、付费设置等信息，并同意开发者协议。
提交后，技能将进入审核流程，审核结果会通过站内信通知。
技能上架后，还能更新、下架或删除吗？
可以。

更新上架：技能更新后需重新申请上架，等待审核通过，通过后已安装用户将自动升级到最新版本。
下架技能：下架后新用户无法安装，已安装用户仍可使用（付费技能在订阅期内有效）。
移除技能：可将已下架技能从“我的技能”列表中移除，不影响扣子编程侧的技能文件。
开发者需要满足什么条件才能上架付费技能到技能商店？
申请商户入驻：签署服务协议并开通收款账户，成为扣子的入驻商户。
申请入口：https://code.coze.cn/merchant-management
说明文档：https://docs.coze.cn/cozespace/skill_revenue_settlement

申请上架付费技能：提交付费技能的上架申请，通过平台的内容质量审核后，即可上架付费技能到商店。
是否可以更改技能收费模式？
技能开发者可以更改技能收费模式，例如将免费技能变更为收费技能，需更新上架信息并等待审核。

企业管理员能上架其他员工的技能吗？
暂时只支持上架本人创建的技能。

下架技能对已购买技能有影响吗？
技能开发者从商店下架技能后，已订阅该技能的用户在有效期内仍可以正常使用。技能到期后将自动失效，无法继续使用，同时不可续费，系统会自动停止该技能的自动续费服务。

购买相关
购买的技能支持退订吗？
已购买的技能不支持退订、退款。请你在选购技能前，仔细查看技能详情页的功能介绍、使用说明，确认符合自身需求后再进行购买。