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

# 安装 difyctl 技能

> 安装一个技能文件，让你的编码 Agent 能够访问你的 Dify 应用

运行 [`difyctl skills install`](/zh/3.13.x/develop/cli/reference/skills#安装技能)，为本机上的编码 Agent 写入一个技能文件。Agent 会读取该文件，并据此自行完成接入。

安装的 `SKILL.md` 是引导文件，而非手册。它引导 Agent 对已安装的 `difyctl` 分两步完成发现：

1. Agent 运行 `difyctl help -o json --compact` 读取 [精简命令清单](/zh/3.13.x/develop/cli/reference/help#精简命令清单)，从中选出唯一符合请求的命令。
2. 执行前，Agent 运行 `difyctl help <path> -o json` 读取该命令的 [描述符](/zh/3.13.x/develop/cli/reference/help#单个命令的描述符)，其中 `<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](/zh/3.13.x/develop/cli/integrate-agents/overview#接入你的-agent)。

## 前提条件

* 在 Agent 运行的机器上 [安装](/zh/3.13.x/develop/cli/install) `difyctl` 并 [登录](/zh/3.13.x/develop/cli/integrate-agents/auth-for-agent-deployments)，使其能复用你的会话。
* 使用一个会读取技能且能运行 Shell 命令的编码 Agent。无 Shell 访问权限的沙箱 Agent 无法使用该技能。
* 安装前至少启动一次 Agent，使其配置目录存在，以便 `difyctl skills install` 能够找到它。

## 操作步骤

<Steps>
  <Step title="预览技能将写入的位置">
    不带 `--yes` 时，该命令为试运行：

    ```bash theme={null}
    difyctl skills install
    ```

    ```text theme={null}
    Detected 1 agent: claude-code

    would write to claude-code: /Users/you/.claude/skills/difyctl/SKILL.md

    Re-run with --yes to write.
    Agent not listed? Install into its directory with `difyctl skills install <dir>`.
    ```
  </Step>

  <Step title="写入技能">
    `--yes` 会写入每一个检测到的 Agent。传入 `--agent <name>` 则只写入其中一个。

    ```bash theme={null}
    difyctl skills install --yes
    ```

    ```text theme={null}
    wrote /Users/you/.claude/skills/difyctl/SKILL.md
    ```
  </Step>

  <Step title="启动一个全新的 Agent 会话">
    启动一个新会话，让 Agent 为新安装的技能建立索引。
  </Step>
</Steps>

<Info>
  detection、各 Agent 的目标路径，以及 `--agent`、`--stdout` 和显式目录写法，参见 [技能参考页](/zh/3.13.x/develop/cli/reference/skills)。
</Info>

## 测试

安装时会打印写入的路径；打开该文件，确认技能已写入。然后检查 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"`](/zh/3.13.x/develop/cli/reference/apps#工作流暂停时)。Agent 应当识别出该暂停并主动提出恢复，而不是报告失败或重试运行。

## 故障排查

| 问题 | 处理方法 |
| :- | :- |
| 未检测到 Agent | 在 Agent 至少运行一次之前，其配置目录（例如 `~/.claude`）并不存在。先启动一次，或用 `difyctl skills install <dir> --yes` 显式指定该目录。 |
| 技能已安装，但 Agent 忽略它 | 多数 Agent 在会话开始时为技能建立索引，因此启动一个新会话。如果仍未加载，将安装器指向 Agent 读取技能的那个目录。 |
| 命令失败并返回退出码 4 | Agent 没有可复用的会话。先在其机器上 [登录](/zh/3.13.x/develop/cli/integrate-agents/auth-for-agent-deployments)。 |
| 技能版本旧于 CLI | 技能带有版本戳，并会让 Agent 将其与 `difyctl version` 比对。若两者不一致，重新运行 `difyctl skills install --yes` 覆盖它。 |

其余情况，参见完整的 [故障排查](/zh/3.13.x/develop/cli/troubleshooting) 页面。