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 tells the agent the one thing that matters: run difyctl help -o json and treat that output as the source of truth. At runtime, the agent reads the full command surface from the installed difyctl.

​
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, your agent can still drive difyctl directly by reading difyctl help -o json at runtime.

​
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

1

Preview where the skill will land

Without --yes, the command is a dry run:
difyctl skills install

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>`.
2

Write the skill

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

wrote /Users/you/.claude/skills/difyctl/SKILL.md
3

Start a fresh agent session

Start a new session so the agent indexes the skill it just received.
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 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.
  3. Pause handling: If you have a Workflow 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.
Last modified on June 25, 2026