本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
运行 difyctl skills install，为本机上的编码 Agent 写入一个技能文件。Agent 会读取该文件，并据此自行完成接入。
安装的 SKILL.md 是引导文件，而非手册。它引导 Agent 对已安装的 difyctl 分两步完成发现：
- Agent 运行
difyctl help -o json --compact读取 精简命令清单，从中选出唯一符合请求的命令。 - 执行前，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能够找到它。
操作步骤#
预览技能将写入的位置
不带 --yes 时，该命令为试运行：
写入技能
--yes 会写入每一个检测到的 Agent。传入 --agent <name> 则只写入其中一个。
启动一个全新的 Agent 会话
启动一个新会话，让 Agent 为新安装的技能建立索引。
Info
detection、各 Agent 的目标路径，以及 --agent、--stdout 和显式目录写法，参见 技能参考页。
测试#
安装时会打印写入的路径；打开该文件，确认技能已写入。然后检查 Agent 是否真正用到了它：
- 发现：在一个全新会话中，向 Agent 提问：「用
difyctl能做些什么？」正确接入的 Agent 会运行difyctl help -o json --compact，并依据其输出作答，而不是凭空猜测命令。 - 端到端：让 Agent 列出你的 Dify 应用并运行其中一个。留意它是否先执行
difyctl get app -o json，再用列表中的真实 ID 执行describe/run序列。run app属于write命令，因此 Agent 应在运行前先向你确认。 - 暂停处理：如果你有一个带人工介入步骤的 Workflow 或 Chatflow 应用，让 Agent 运行它。暂停的运行会 以 0 退出，并在 stdout 上报告
"status": "paused"。Agent 应当识别出该暂停并主动提出恢复，而不是报告失败或重试运行。
故障排查#
| 问题 | 处理方法 |
|---|---|
| 未检测到 Agent | 在 Agent 至少运行一次之前，其配置目录（例如 ~/.claude）并不存在。先启动一次，或用 difyctl skills install <dir> --yes 显式指定该目录。 |
| 技能已安装，但 Agent 忽略它 | 多数 Agent 在会话开始时为技能建立索引，因此启动一个新会话。如果仍未加载，将安装器指向 Agent 读取技能的那个目录。 |
| 命令失败并返回退出码 4 | Agent 没有可复用的会话。先在其机器上登录：参见 在 Agent 运行的位置进行认证。 |
| 技能版本旧于 CLI | 技能带有版本戳，并会让 Agent 将其与 difyctl version 比对。若两者不一致，重新运行 difyctl skills install --yes 覆盖它。 |
其余情况，参见完整的 故障排查 页面。