Skip to main content

Run difyctl skills install to write a skill file for the coding agents on your machine. The agent picks it up and onboards itself from there.

The installed SKILL.md is a bootstrap, not a manual. It walks the agent through discovery against the installed difyctl in two steps:

  1. The agent reads the compact command map with difyctl help -o json --compact and picks the one command that fits the request.
  2. Before running it, the agent reads that command’s descriptor with difyctl help <path> -o json, where <path> is the command as the map lists it, such as get app. The descriptor is its only source for the command’s arguments and flags.

The skill also sends the agent to difyctl help agent for exit codes, error output, paused workflows, and retry rules.

The descriptor’s effect label (read, write, or destructive) doubles as a confirmation gate: the skill has the agent confirm with you before it runs any write or destructive command.

When to Use the Skill#

  • Your agent runtime reads skills: Claude Code, Codex, OpenCode, Cursor, pi, or anything else that picks up SKILL.md files from a skill directory.
  • The agent can run shell commands. The skill drives difyctl through the agent’s shell tool.
  • You want zero maintenance: the skill never goes stale, because it lists no commands.

If your runtime doesn’t read skills, give the agent the same two commands in its own instructions. See Onboard Your Agent for the line to add.

Prerequisites#

  • Install difyctl and sign in on the machine the agent runs on, so it can reuse your session. For a server or container, see Authenticate Where Your Agent Runs.
  • Use a coding agent that reads skills and can run shell commands. A sandboxed agent with no shell access can’t use the skill.
  • Launch the agent at least once before installing, so its config directory exists for difyctl skills install to find.

Steps#

Preview where the skill will land

Without --yes, the command is a dry run:

Write the skill

--yes writes to every detected agent. Pass --agent <name> to write to just one.

Start a fresh agent session

Start a new session so the agent indexes the skill it just received.

Info

See the Skills reference page for detection, target paths per agent, and the --agent, --stdout, and explicit-directory forms.

Test#

The install prints the path it wrote; open that file to confirm the skill is there. Then check that the agent actually uses it:

  1. Discovery: In a fresh session, ask the agent: “What can you do with difyctl?” A correctly onboarded agent runs difyctl help -o json --compact and answers from its output rather than guessing commands.
  2. End to end: Ask the agent to list your Dify apps and run one. Watch for difyctl get app -o json followed by a describe/run sequence with real IDs from the list. Expect it to check with you before the run, since run app is a write command.
  3. Pause handling: If you have a Workflow or Chatflow app with a human-input step, ask the agent to run it. A paused run exits 0 and reports "status": "paused" on stdout. The agent should recognize the pause and offer to resume, not report a failure or retry the run.

Troubleshooting#

ProblemWhat to do
The agent isn’t detectedIts config directory (for example ~/.claude) doesn’t exist until the agent has run at least once. Launch it once, or target the directory explicitly with difyctl skills install <dir> --yes.
The skill is installed but the agent ignores itMost agents index skills at session start, so start a new session. If it still doesn’t load, point the installer at the directory your agent reads skills from.
Commands fail with exit code 4The agent has no session to reuse. Sign in on its machine first: see Authenticate Where Your Agent Runs.
The skill is older than the CLIThe skill carries a version stamp and tells the agent to compare it against difyctl version. If they differ, re-run difyctl skills install --yes to overwrite it.

For everything else, see the full Troubleshooting page.