技能常见问题

技能开发技巧

我不会写代码，也能在扣子编程里开发技能吗？

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

• 设计技能结构；

• 生成 SKILL.md 等标准技能文件；

• 按需创建脚本、参考文档和资源文件；

• 将技能打包为可直接运行和部署的技能包。

  整个过程无需手动编辑文件。

用自然语言开发技能时，提示词应该怎么写，才不容易翻车？

核心原则是：清晰、结构化、可执行。
在提示词中，建议明确说明：

• 技能要解决什么问题、能处理哪些任务；

• 在什么场景下触发技能；

• 技能的输出形式（例如文档、HTML 文件、分析结果等）；

• 是否有脚本、规范、术语表、参考资料可供使用。

  如果关键信息不足，扣子 AI 会主动追问补充细节；你也可以在澄清阶段继续上传附件。

技能是如何被生成、预览和测试的？

通过自然语言提交需求后，扣子 AI 会自动完成以下流程：

1. 分析需求并规划技能文件结构；
2. 生成 SKILL.md、脚本和相关资源；
3. 自动创建测试用例并完成一轮单元测试；
4. 在右侧预览区提供可直接触发的技能体验。

你可以在预览区通过对话反复触发技能，验证是否稳定触发、稳定执行、覆盖真实业务场景。

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

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

• 解析技能结构；

• 检查安全性与规范性；

• 识别敏感信息并提示配置为环境变量；

• 重新打包，使其可在扣子对话中使用。

  即使格式不完全规范，扣子 AI 也会在上传过程中协助补全和改造。

技能生成后还能继续优化或回滚吗？

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

• 自然语言优化：直接在对话中告诉扣子 AI 如何修改技能逻辑或触发条件。

• 手动编辑文件：打开技能文件树，直接编辑 SKILL.md 或脚本文件，并让扣子 AI 重新打包。

  如果某次生成效果不理想，还可以通过版本历史功能回滚到之前的稳定版本。

使用相关

扣子智能体可以调用技能吗？

开发、部署好的技能目前仅支持在扣子对话中使用，你在扣子编程开发的智能体、工作流和应用暂不支持调用技能。

我在扣子编程里开发完技能后，如何在扣子对话中使用？

技能必须先部署，才能在扣子对话中使用。
基本流程是：

1. 在扣子编程中完成技能开发和调试；
2. 单击技能页面右上角的「部署」，按需设置部署参数，等待部署完成；
3. 部署成功后，即可在扣子对话中触发和使用该技能。

若未上架技能商店，部署后的技能仅技能所有者本人可用。

技能部署完成后，在哪里查看和管理我发布的技能？

你可以在以下位置查看已创建和发布的技能：

• 扣子技能商店 → 我的技能 → 我创建的技能

  在这里可以进行后续操作，例如上架、更新、下架或删除技能。

如何切换技能绑定的授权账号？

已授权的技能，如果授权的账号发生变更或授权失效，你可以重新授权。

1. 在扣子左侧导航栏选择技能市场。
2. 单击我的技能页签，选择目标技能。
3. 单击更多 (⋮) 按钮，选择重新授权。根据页面提示，完成新的授权流程。

重新部署技能之后，如何在扣子对话中使用最新版本？

扣子对话默认会使用技能的最新部署版本。如果你在更新技能后发现对话中调用的仍是旧版本，这通常是由于当前会话仍在持续使用旧版，尚未重新加载新版本。
要解决此问题，你可以尝试发送以下指令，让扣子重新加载最新版本：

帮我重新加载一下 xx 技能。

安全相关

技能需要调用外部 API ，如何安全管理密钥

当技能需要调用外部 API、第三方服务或受保护资源时，不应将 API Key、Secret 等敏感信息直接写入代码。此类场景应使用技能凭证变量来统一管理和使用敏感凭证。
在扣子编程中，凭证变量支持两种配置方式：

• 开发者变量：由开发者填写并维护密钥，技能运行时统一使用该 Key 发起请求，消费者无需感知。
• 消费者变量：由消费者在安装或运行技能时填写自己的 Key，不同用户的凭证相互隔离，技能会自动使用当前用户配置的凭证发起请求。

在开发过程中，扣子编程会自动识别代码或接口文档中的敏感凭证信息，并提示将其封装为凭证变量；对已完成的技能，也可主动要求系统进行敏感信息识别和加密处理。
所有凭证变量均可在「环境变量」中统一管理，支持在部署前或部署后进行修改。通过这一机制，开发者无需自行处理加解密逻辑，即可在保障安全性的同时，灵活支持不同的凭证使用模式。

调用技能时，报错环境变量问题

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

1. 打开对应的脚本文件，检查是否已引入 coze 的 request 包。
   
2. 定位到实际的请求代码位置，确认敏感信息是否已被正确替换为环境变量。
   
3. 如果以上两步没有问题，则检查环境变量中填写的凭证信息是否正确。

配置开发者变量，但使用技能时智能体要求提供凭证

如果已配置环境变量且脚本无问题，但预览或使用技能时扣子 AI 仍要求提供凭证，可直接在扣子或预览页面告知扣子 AI 已配置环境变量，并让其直接执行相关脚本：

• 如果脚本执行成功：说明环境变量配置无误。问题可能出在技能的 SKILL.md 引导话术里， 你可以通过自然语言指令让扣子 AI 修改引导内容。
• 如果脚本执行失败：说明脚本可能存在其他运行问题，需要进一步检查脚本逻辑。

如何将开发者环境变量转换为消费者环境变量

对于已经配置的环境变量，目前暂不支持直接在环境变量页签中可视化转换变量类型，但是你可以通过自然语言指令让扣子 AI 重新配置脚本的环境变量，再重新配置凭证信息即可。

模型重新配置环境变量后，部署页面出现重复的变量

可以手动删除已在开发环境中移除的冗余凭证变量。

上架商店时提示「skill内的敏感信息校验未通过，请求域名为空」

进入扣子编程对应的技能项目，直接向 agent 发送指令，要求其更新凭证即可。

使用技能时提示授权失败，如何解决？

授权失败通常是由于 API Key 等授权信息填写错误。请首先检查凭证变量的配置是否正确。
如果你是基于扣子商店的技能进行复制和改造，或者是直接复制自己的技能，则可能是由于变量配置中 {skill_id} 不正确导致授权失败。

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

请帮我重新设置下代码中的凭证 Key，{skill_id} 应该是 7611011370737418****

上架相关

将技能上架到技能商店，需要满足哪些条件？

在上架前，请确保：

• 技能已创建并完成部署；

• 如果是付费技能，已开通收款账户；

• 你是技能的所有者。

  上架时需要填写技能名称、简介、封面图、详细介绍、分类、精选案例、付费设置等信息，并同意开发者协议。
  提交后，技能将进入审核流程，审核结果会通过站内信通知。

技能上架后，还能更新、下架或删除吗？

可以。

• 更新上架：技能更新后需重新申请上架，等待审核通过，通过后已安装用户将自动升级到最新版本。
• 下架技能：下架后新用户无法安装，已安装用户仍可使用（付费技能在订阅期内有效）。
• 移除技能：可将已下架技能从“我的技能”列表中移除，不影响扣子编程侧的技能文件。

开发者需要满足什么条件才能上架付费技能到技能商店？

• 申请商户入驻：签署服务协议并开通收款账户，成为扣子的入驻商户。

申请入口：https://code.coze.cn/merchant-management
说明文档：https://docs.coze.cn/cozespace/skill_revenue_settlement

• 申请上架付费技能：提交付费技能的上架申请，通过平台的内容质量审核后，即可上架付费技能到商店。

是否可以更改技能收费模式？

技能开发者可以更改技能收费模式，例如将免费技能变更为收费技能，需更新上架信息并等待审核。

企业管理员能上架其他员工的技能吗？

暂时只支持上架本人创建的技能。

下架技能对已购买技能有影响吗？

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

购买相关

购买的技能支持退订吗？

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