Skip to main content
本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
运行 difyctl skills install，为本机上的编码 Agent 写入一个技能文件。Agent 会读取该文件，并据此自行完成接入。 安装的 SKILL.md 是引导文件，而非手册。它引导 Agent 对已安装的 difyctl 分两步完成发现：
  1. Agent 运行 difyctl help -o json --compact 读取 精简命令清单，从中选出唯一符合请求的命令。
  2. 执行前，Agent 运行 difyctl help <path> -o json 读取该命令的 描述符，其中 <path> 就是清单中列出的命令，例如 get app。描述符是 Agent 获取该命令参数和标志的唯一来源。
该技能还会让 Agent 通过 difyctl help agent 了解退出码、错误输出、工作流暂停和重试规则。描述符中的 effect 标签（read、write 或 destructive）同时充当确认关卡：执行任何 write 或 destructive 命令前，技能都会让 Agent 先向你确认。

​
何时使用该技能

  • 你的 Agent 运行时会读取技能：Claude Code、Codex、OpenCode、Cursor、pi，或任何会从技能目录读取 SKILL.md 文件的工具。
  • Agent 能运行 Shell 命令。技能通过 Agent 的 Shell 工具来驱动 difyctl。
  • 你想要零维护：技能不列出任何命令，因此永远不会过时。
如果你的运行时不读取技能，可把同样的两条命令写进 Agent 自己的指令里。要添加的那一句，参见 接入你的 Agent。

​
前提条件

  • 在 Agent 运行的机器上 安装 difyctl 并 登录，使其能复用你的会话。对于服务器或容器，参见 在 Agent 运行的位置进行认证。
  • 使用一个会读取技能且能运行 Shell 命令的编码 Agent。无 Shell 访问权限的沙箱 Agent 无法使用该技能。
  • 安装前至少启动一次 Agent，使其配置目录存在，以便 difyctl skills install 能够找到它。

​
操作步骤

1

预览技能将写入的位置

不带 --yes 时，该命令为试运行：
2

写入技能

--yes 会写入每一个检测到的 Agent。传入 --agent <name> 则只写入其中一个。
3

启动一个全新的 Agent 会话

启动一个新会话，让 Agent 为新安装的技能建立索引。
detection、各 Agent 的目标路径，以及 --agent、--stdout 和显式目录写法，参见 技能参考页。

​
测试

安装时会打印写入的路径；打开该文件，确认技能已写入。然后检查 Agent 是否真正用到了它：
  1. 发现：在一个全新会话中，向 Agent 提问：「用 difyctl 能做些什么？」正确接入的 Agent 会运行 difyctl help -o json --compact，并依据其输出作答，而不是凭空猜测命令。
  2. 端到端：让 Agent 列出你的 Dify 应用并运行其中一个。留意它是否先执行 difyctl get app -o json，再用列表中的真实 ID 执行 describe/run 序列。run app 属于 write 命令，因此 Agent 应在运行前先向你确认。
  3. 暂停处理：如果你有一个带人工介入步骤的 Workflow 或 Chatflow 应用，让 Agent 运行它。暂停的运行会 以 0 退出，并在 stdout 上报告 "status": "paused"。Agent 应当识别出该暂停并主动提出恢复，而不是报告失败或重试运行。

​
故障排查

其余情况，参见完整的 故障排查 页面。
Last modified on September 10, 2026