> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

## 技能开发技巧 {#b5211c78}
### 我不会写代码，也能在扣子编程里开发技能吗？ {#2beb8634}
可以。
扣子编程支持**通过自然语言直接开发技能**。你只需要描述技能的目标、使用场景、执行流程和预期输出，扣子 AI 会自动：

* 设计技能结构；
* 生成 `SKILL.md` 等标准技能文件；
* 按需创建脚本、参考文档和资源文件；
* 将技能打包为可直接运行和部署的技能包。

  整个过程无需手动编辑文件。
### 用自然语言开发技能时，提示词应该怎么写，才不容易翻车？ {#aad3b83d}
  核心原则是：**清晰、结构化、可执行**。
  在提示词中，建议明确说明：

* 技能要解决什么问题、能处理哪些任务；
* 在什么场景下触发技能；
* 技能的输出形式（例如文档、HTML 文件、分析结果等）；
* 是否有脚本、规范、术语表、参考资料可供使用。

  如果关键信息不足，扣子 AI 会主动追问补充细节；你也可以在澄清阶段继续上传附件。
### 技能是如何被生成、预览和测试的？ {#920d3467}
  通过自然语言提交需求后，扣子 AI 会自动完成以下流程：

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

  你可以在预览区通过对话反复触发技能，验证是否**稳定触发、稳定执行、覆盖真实业务场景**。
### 如果我已经有一个技能文件包，能直接用吗？ {#8cac5095}
可以。
你可以使用「上传技能包」功能，将本地已有的技能包（`.skill` 或 `.zip`）上传到扣子编程。
系统会自动：

* 解析技能结构；
* 检查安全性与规范性；
* 识别敏感信息并提示配置为环境变量；
* 重新打包，使其可在扣子对话中使用。

  即使格式不完全规范，扣子 AI 也会在上传过程中协助补全和改造。
### 技能生成后还能继续优化或回滚吗？ {#e22e0650}
  可以。
  你可以通过两种方式持续迭代技能：

* **自然语言优化**：直接在对话中告诉扣子 AI 如何修改技能逻辑或触发条件。
* **手动编辑文件**：打开技能文件树，直接编辑 `SKILL.md` 或脚本文件，**并让扣子 AI 重新打包**。

  如果某次生成效果不理想，还可以通过**版本历史**功能回滚到之前的稳定版本。
## 使用相关 {#b45938c0}
### 扣子智能体可以调用技能吗？ {#1d894f90}
开发、部署好的技能目前仅支持在[扣子对话](https://www.coze.cn/)中使用，你在扣子编程开发的智能体、工作流和应用暂不支持调用技能。
### 我在扣子编程里开发完技能后，如何在扣子对话中使用？ {#38d7afd5}
  技能必须**先部署**，才能在扣子对话中使用。
  基本流程是：

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

  若未上架技能商店，部署后的技能**仅技能所有者本人可用**。
### 技能部署完成后，在哪里查看和管理我发布的技能？ {#aa7c14f4}
  你可以在以下位置查看已创建和发布的技能：

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

  在这里可以进行后续操作，例如上架、更新、下架或删除技能。
### 如何切换技能绑定的授权账号？ {#561fa3b2}
已授权的技能，如果授权的账号发生变更或授权失效，你可以重新授权。

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

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

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

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

在开发过程中，扣子编程会自动识别代码或接口文档中的敏感凭证信息，并提示将其封装为凭证变量；对已完成的技能，也可主动要求系统进行敏感信息识别和加密处理。
所有凭证变量均可在「环境变量」中统一管理，支持在部署前或部署后进行修改。通过这一机制，开发者无需自行处理加解密逻辑，即可在保障安全性的同时，灵活支持不同的凭证使用模式。
### 调用技能时，报错环境变量问题 {#62555c95}
通过扣子编程开发技能时，如果在预览页面调用技能失败，页面报错环境变量相关的问题，你可以通过以下步骤排查问题，也可以直接告知 agent 引导其协助排查。

1. 打开对应的脚本文件，检查是否已引入 coze 的 `request` 包。
   ![Image=451x149](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4cb0bb16c77d4b3786687b07e3dee442~tplv-goo7wpa0wc-image.image)
2. 定位到实际的请求代码位置，确认敏感信息是否已被正确替换为环境变量。
   ![Image=457x124](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2d801fd2720e4a5a97723e9517d6ea90~tplv-goo7wpa0wc-image.image)
3. 如果以上两步没有问题，则检查环境变量中填写的凭证信息是否正确。

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

   ![Image=439x228](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/cb7fc5922ba34198ae1d70598279213c~tplv-goo7wpa0wc-image.image)
* **如果脚本执行成功**：说明环境变量配置无误。问题可能出在技能的 `SKILL.md` 引导话术里， 你可以通过自然语言指令让扣子 AI 修改引导内容。
* **如果脚本执行失败**：说明脚本可能存在其他运行问题，需要进一步检查脚本逻辑。

### 如何将开发者环境变量转换为消费者环境变量 {#0110b612}
对于已经配置的环境变量，目前暂不支持直接在**环境变量**页签中可视化转换变量类型，但是你可以通过自然语言指令让扣子 AI 重新配置脚本的环境变量，再重新配置凭证信息即可。
![Image=326x225](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/3a0f1bf266fc4849bb883919335d291d~tplv-goo7wpa0wc-image.image)
### 模型重新配置环境变量后，部署页面出现重复的变量 {#3043570c}
可以手动删除已在开发环境中移除的冗余凭证变量。
![Image=513x208](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2ff81f28b0a94697a271eab302e43c77~tplv-goo7wpa0wc-image.image)
### 上架商店时提示「skill内的敏感信息校验未通过，请求域名为空」 {#d43c511d}
进入扣子编程对应的技能项目，直接向 agent 发送指令，要求其更新凭证即可。
### 使用技能时提示授权失败，如何解决？ {#cbfda041}
授权失败通常是由于 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=478x448](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b90d6bb2891e4ccda650208212d7b6d8~tplv-goo7wpa0wc-image.image)
## 上架相关 {#79bbde35}
### 将技能上架到技能商店，需要满足哪些条件？ {#fc481cf1}
  在上架前，请确保：

* 技能已创建并完成部署；
* 如果是付费技能，已开通收款账户；
* 你是技能的所有者。

  上架时需要填写技能名称、简介、封面图、详细介绍、分类、精选案例、付费设置等信息，并同意开发者协议。
  提交后，技能将进入审核流程，审核结果会通过站内信通知。
### 技能上架后，还能更新、下架或删除吗？ {#003564ee}
  可以。

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

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

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

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


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

### 是否可以更改技能收费模式？  {#6a29c4b5}
技能开发者可以更改技能收费模式，例如将免费技能变更为收费技能，需更新上架信息并等待审核。 
### 企业管理员能上架其他员工的技能吗？ {#3f508656}
暂时只支持上架本人创建的技能。
### 下架技能对已购买技能有影响吗？ {#123fe281}
技能开发者从商店下架技能后，已订阅该技能的用户在有效期内仍可以正常使用。技能到期后将自动失效，无法继续使用，同时不可续费，系统会自动停止该技能的自动续费服务。
## 购买相关 {#3e97f28a}
### 购买的技能支持退订吗？ {#ffafdd38}
已购买的技能不支持退订、退款。请你在选购技能前，仔细查看技能详情页的功能介绍、使用说明，确认符合自身需求后再进行购买。