feat(cli): embed the difyctl skill in the binary and point agents at it

Offline install skills from the embedded copy (Bun 1.4 --asset). Adds a CI smoke check, a stderr notice on difyctl help, and a next-step line in all four installers.

Author: GareArc

.github/workflows/cli-edge.yml

@@ -57,7 +57,11 @@ jobs:
         run: CLI_VERSION="${{ steps.ver.outputs.version }}" scripts/release-write-checksums.sh
 
       - name: Smoke the runner-arch binary
-        run: ./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64 version
+        run: |
+          bin="./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64"
+          "$bin" version
+          "$bin" install skills "$RUNNER_TEMP/skill"
+          diff -r "$RUNNER_TEMP/skill/difyctl" ../skills/difyctl
 
       - name: Publish to R2
         env:

.github/workflows/cli-release.yml

@@ -121,6 +121,13 @@ jobs:
       - name: Generate sha256 checksum file
         run: scripts/release-write-checksums.sh
 
+      - name: Smoke the runner-arch binary
+        run: |
+          bin="./dist/bin/$(node scripts/release-naming.mjs asset "$version" linux-x64)"
+          "$bin" version
+          "$bin" install skills "$RUNNER_TEMP/skill"
+          diff -r "$RUNNER_TEMP/skill/difyctl" ../skills/difyctl
+
       - name: Attach difyctl assets to Dify release
         if: ${{ !inputs.dry_run }}
         env:

cli/.bun-version

@@ -1 +1 @@
-1.3.11
+1.4.2

cli/ARD.md

@@ -25,7 +25,7 @@ src/
   net/          fetch init and proxy dispatcher, shared by the http plugin and the pre-login device flow
   store/        config/session/token file and keychain persistence
   sys/          the process edges — env, argv, exit, platform paths; io/ holds streams.ts, color.ts and view.ts (a JSON value paired with its text form, the mode picks one)
-  skills/       reads skills from a GitHub folder or a local folder, and installs them
+  skills/       the one embedded difyctl skill (or a local folder) and its installer
 ```
 
 ---

cli/README.md

@@ -45,19 +45,18 @@ difyctl has no built-in business commands. Every operation the server publishes
 
 ## Commands
 
-| Command                    | Purpose                                                         |
-| -------------------------- | --------------------------------------------------------------- |
-| `login`                    | Log in via the OAuth device flow                                |
-| `logout`                   | Log out of the current session                                  |
-| `version`                  | Print the client and (if logged in) server versions             |
-| `use workspace <id>`       | Pin the local session to a workspace                            |
-| `get config [key]`         | Print the local config, or one key                              |
-| `set config <key> <value>` | Set a local config value                                        |
-| `unset config <key>`       | Remove a local config value, restoring its default              |
-| `refresh cache`            | Refetch the server catalog and replace the local cache          |
-| `delete cache`             | Delete the local server catalog cache                           |
-| `get skills`               | List the skills in the collection                               |
-| `install skills <dir>`     | Write skills from the collection into a skills root (`--skill`) |
+| Command                    | Purpose                                                |
+| -------------------------- | ------------------------------------------------------ |
+| `login`                    | Log in via the OAuth device flow                       |
+| `logout`                   | Log out of the current session                         |
+| `version`                  | Print the client and (if logged in) server versions    |
+| `use workspace <id>`       | Pin the local session to a workspace                   |
+| `get config [key]`         | Print the local config, or one key                     |
+| `set config <key> <value>` | Set a local config value                               |
+| `unset config <key>`       | Remove a local config value, restoring its default     |
+| `refresh cache`            | Refetch the server catalog and replace the local cache |
+| `delete cache`             | Delete the local server catalog cache                  |
+| `install skills <dir>`     | Write the difyctl skill into a skills root (`--from`)  |
 
 `login` blocks until the browser approval arrives. An agent runs it in the background, relays the `open <url>` and `code <code>` lines from its stderr to the user, and does not cancel the job. In a sandbox it adds `--no-keyring` and sets `DIFY_CONFIG_DIR` to persistent storage on every call, so the login survives the next session.
 
@@ -68,11 +67,9 @@ response in the error envelope instead of dropping it.
 
 ## Agent skills
 
-difyctl installs agent skills from [`skills/`] at the repo root. It downloads them from GitHub at install time, from the commit the binary was built from; the binary holds no copy and needs no git. The basic skill, `difyctl`, teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. Scenario skills add guidance for one kind of task and open by reading the basic one.
+difyctl ships one skill, `difyctl`, built into the binary. It teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. The skill is a tree of linked docs under [`skills/difyctl/`].
 
-- `difyctl get skills` — the collection: each skill's name and description. Writes nothing.
-- `difyctl install skills <dir>` — write every skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. Each skill's folder is replaced whole. `--skill <name>` (repeatable) writes only those skills; a scenario skill brings `difyctl` along.
-- `--from` on both reads skills from elsewhere: any GitHub folder in the standard layout (`https://github.com/<owner>/<repo>/tree/<ref>/<folder>`), or a local folder when GitHub is blocked. Set `GITHUB_TOKEN` if GitHub's rate limit (60 requests an hour per IP) gets in the way.
+- `difyctl install skills <dir> [--from <folder>]` — write the skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. The `difyctl` folder is replaced whole. It works offline. `--from` installs a local skill folder instead of the built-in one.
 
 difyctl does not detect agents. You name the root, and re-running the same command refreshes the copies.
 
@@ -131,4 +128,4 @@ Apache-2.0.
 [Agent skill]: #agent-skills
 [Dify]: https://dify.ai
 [`ARD.md`]: ARD.md
-[`skills/`]: ../skills
+[`skills/difyctl/`]: ../skills/difyctl

cli/scripts/install-cli.sh

@@ -28,6 +28,10 @@ err() { printf '%s\n' "install-cli: $*" >&2; }
 die() { err "$*"; rm -f "$FETCH_ERR_FILE"; exit 1; }
 need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
 re_escape() { printf '%s' "$1" | sed 's/[][\\.^$*+?(){}|/]/\\&/g'; }
+print_skill_hint() {
+  printf '%s\n' 'AI agents: run `difyctl install skills <your skills root>` to load the difyctl skill.'
+  printf '%s\n' 'Run it again after each difyctl upgrade; the skill ships inside the binary.'
+}
 
 detect_target() {
     case "$(uname -s)" in
@@ -238,6 +242,7 @@ main() {
             printf '  export PATH="%s:$PATH"\n' "$bin_dir"
             ;;
     esac
+    print_skill_hint
 }
 
 if [ "${DIFYCTL_INSTALL_LIB:-0}" != "1" ]; then

cli/scripts/install-r2.ps1

@@ -38,6 +38,11 @@ function Get-ChecksumTarget([string]$text, [string]$target) {
   return $null
 }
 
+function Write-SkillHint {
+  Write-Host 'AI agents: run `difyctl install skills <your skills root>` to load the difyctl skill.'
+  Write-Host 'Run it again after each difyctl upgrade; the skill ships inside the binary.'
+}
+
 # Download, sha256-verify, place. Returns nothing; throws on mismatch.
 function Install-DifyctlBinary([string]$dlUrl, [string]$sha, [string]$version, [string]$channel, [string]$installDir) {
   $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetFileName($dlUrl))
@@ -55,6 +60,7 @@ function Install-DifyctlBinary([string]$dlUrl, [string]$sha, [string]$version, [
     Write-Host "$installDir is not on your PATH. Add it with:"
     Write-Host "  [Environment]::SetEnvironmentVariable('PATH', `"$installDir;`$env:PATH`", 'User')"
   }
+  Write-SkillHint
 }
 
 function Install-DifyctlR2 {

cli/scripts/install-r2.sh

@@ -21,6 +21,10 @@ trap 'rm -f "$tmp_m" "${tmp_c:-}" "${tmp_b:-}"' EXIT INT TERM
 err() { printf '%s\n' "install-r2: $*" >&2; }
 die() { err "$*"; exit 1; }
 need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
+print_skill_hint() {
+  printf '%s\n' 'AI agents: run `difyctl install skills <your skills root>` to load the difyctl skill.'
+  printf '%s\n' 'Run it again after each difyctl upgrade; the skill ships inside the binary.'
+}
 
 detect_target() {
   case "$(uname -s)" in
@@ -98,6 +102,7 @@ fetch_verify_install() {
     *":${install_dir}:"*) ;;
     *) printf 'note: add %s to your PATH\n' "$install_dir" ;;
   esac
+  print_skill_hint
 }
 
 # Resolve a pinned build into download url + sha. Sets: version, dl_url, dl_sha.

cli/scripts/install.ps1

@@ -115,6 +115,11 @@ function Resolve-Release {
     }
 }
 
+function Write-SkillHint {
+    Write-Host 'AI agents: run `difyctl install skills <your skills root>` to load the difyctl skill.'
+    Write-Host 'Run it again after each difyctl upgrade; the skill ships inside the binary.'
+}
+
 function Invoke-Main {
     $release = Resolve-Release
     $difyTag = $release.tag_name
@@ -158,6 +163,7 @@ function Invoke-Main {
         else {
             Write-Host 'verify: run "difyctl version"'
         }
+        Write-SkillHint
     }
     finally {
         Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue

cli/scripts/release-build.sh

@@ -41,6 +41,10 @@ DIFYCTL_BUILD_DATE="${DIFYCTL_BUILD_DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
 
 [[ "$CLI_VERSION" != "undefined" ]] || die "CLI_VERSION could not be derived from package.json"
 
+repo_root="$(cd "${cli_root}/.." && pwd)"
+skill_dir="${repo_root}/skills/difyctl"
+[[ -f "${skill_dir}/SKILL.md" ]] || die "skill not found: ${skill_dir}"
+
 [[ -f "$entry" ]] || die "entry not found: $entry"
 
 rm -rf "$out_dir"
@@ -60,12 +64,13 @@ defines=(
 while IFS=$'\t' read -r bun_target asset_target _exe; do
     out="${out_dir}/$(naming asset "$CLI_VERSION" "$asset_target")"
     log::info "compiling ${asset_target} -> $(basename "$out")..."
-    bun build "$entry" \
+    (cd "$repo_root" && bun build "$entry" \
+        --asset "$skill_dir" \
         --target="$bun_target" \
         --compile \
         --minify \
         "${defines[@]}" \
-        --outfile="$out" >/dev/null
+        --outfile="$out") >/dev/null
 done < <(naming targets)
 
 log::info "built $(find "$out_dir" -type f | wc -l | tr -d ' ') binaries:"