From f9c91a2754912b291ffc0d3e3b9b8969bcd5ecc0 Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 29 Jul 2026 14:50:04 +0800 Subject: [PATCH 01/20] docs: add skills overview and skill library guides Co-Authored-By: Claude Fable 5 --- docs.json | 8 +++ .../use-dify/build/new-agent/build.mdx | 11 +-- .../use-dify/build/skills/library.mdx | 68 +++++++++++++++++++ .../use-dify/build/skills/overview.mdx | 25 +++++++ 4 files changed, 107 insertions(+), 5 deletions(-) create mode 100644 en/self-host/use-dify/build/skills/library.mdx create mode 100644 en/self-host/use-dify/build/skills/overview.mdx diff --git a/docs.json b/docs.json index 9e944edcf..264ea0330 100644 --- a/docs.json +++ b/docs.json @@ -828,6 +828,14 @@ ], "expanded": false }, + { + "group": "Skills", + "pages": [ + "en/self-host/use-dify/build/skills/overview", + "en/self-host/use-dify/build/skills/library" + ], + "expanded": false + }, { "group": "Basic Apps", "pages": [ diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 5bce3ebd2..438704135 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -49,7 +49,7 @@ A few things worth covering: - **Tool and file use**: when to reach for each, named explicitly. - **Output**: the format, length, or tone you want back. -You can point the agent at a specific skill, file, tool, or knowledge source, or leave the choice to the agent: +You can point the agent at a specific embedded skill, file, tool, or knowledge source, or leave the choice to the agent: - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. @@ -57,13 +57,14 @@ You can point the agent at a specific skill, file, tool, or knowledge source, or ### Skills -A *skill* is a self-contained procedure you package for the agent: instructions, reference materials, and any scripts for one specialized task, bundled together so you define it once and reuse it. +Add skills to hand the agent your procedures for recurring tasks. For what a skill is and when to reach for one, see [Skills](/en/self-host/use-dify/build/skills/overview). -Where the prompt sets the agent's overall role, a skill is a job aid it pulls in only when a particular task calls for it—an SOP you hand a capable hire. The agent brings the general ability; the skill gives it your exact steps, materials, and tools for that job, so the work comes out the way you expect. +Click **Add** and choose where the skill comes from: -For instance, a `marketing-copy` skill might bundle your style guide, brand assets, and a checklist, so you don't re-explain them every time. +- Choose **From skill library** to attach a *library skill* shared across your agents. The agent follows the skill's latest published version. To create and manage library skills, see [Skill Library](/en/self-host/use-dify/build/skills/library). +- Choose **Upload package** to add an *embedded skill*, one the agent keeps to itself: a `.zip` or `.skill` file no larger than 50 MB, with a `SKILL.md` inside, in the [Agent Skills](https://agentskills.io/home) format. To share it with other agents, import its package into the [Skill Library](/en/self-host/use-dify/build/skills/library#import-a-skill). -A skill package needs to be a `.zip` or `.skill` file no larger than 50 MB, with a `SKILL.md` inside. To learn more about the format and how to build one, see [Agent Skills](https://agentskills.io/home). You can also have the agent create skills for you in [Build mode](#build-by-chatting). +You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). ### Files diff --git a/en/self-host/use-dify/build/skills/library.mdx b/en/self-host/use-dify/build/skills/library.mdx new file mode 100644 index 000000000..6280c106b --- /dev/null +++ b/en/self-host/use-dify/build/skills/library.mdx @@ -0,0 +1,68 @@ +--- +title: Manage the Skill Library +sidebarTitle: Skill Library +description: Create, edit, publish, and share library skills for your agents +--- + +## Create a Skill + +From **Skills**, click **Create**. A new skill opens in the editor with a starter `SKILL.md`, and the **Skill Builder** panel opens beside it. To start from an existing skill instead, choose **Duplicate** from its **⋯** menu; the copy is a new draft of the latest published content. + + +Creating and managing skills requires the Editor role or above. + + +Write the skill by hand, or draft it with the **Skill Builder**: describe the scenario or attach an existing process doc, and it suggests content in the chat. The builder doesn't edit your files; applying its suggestions is up to you. + +Either way, the skill takes shape in `SKILL.md`: the frontmatter carries its `name`, `description`, and other metadata, and the body holds the procedure itself. + +```markdown +--- +name: refund-requests +description: Handle customer refund requests the standard way. Use when a customer asks for a refund or reports a billing issue. +metadata: + display-name: Refund requests +--- + +Check the order status before promising anything. +Offer a refund only within the 30-day window. +Keep the tone warm, and close with a help-center link. +``` + +The following settings shape how the skill is found and used: + +- **Names**: after a skill is published, renaming it changes only the `display-name`; the internal `name` keeps its value until you edit it yourself. +- **Description**: state what the skill does and when an agent should use it. +- **Metadata**: to keep extra information with the skill, add custom frontmatter fields. +- **Supporting files**: if the task needs more than instructions, add templates, scripts, or reference docs through the file tree. +- **Tags**: add them from the editor sidebar, then filter by tag on the **Skills** page. They're for organizing the library only. Changes to tags take effect without publishing. + +When the skill is ready, publish it to make it available to agents. + +## Publish and Versions + +Your edits autosave as a draft, and agents keep using the last published version until you publish again. + +Each publish is saved as a version. Open the version history anytime to revisit or restore an earlier version. + + +Restoring a version publishes it immediately as the newest version. + + +## Add to Agents + +In the agent's **Configure** page, under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. The same works for an agent you configure inside a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). + +## Import a Skill + +To bring in a skill built elsewhere, click **Import** on the **Skills** page and choose a `.zip` or `.skill` package in the [Agent Skills](https://agentskills.io/home) format. The package arrives as a draft for you to review and publish. + +To turn an agent's embedded skill into a library skill, import its package here. + +## Export a Skill + +To take a skill beyond this workspace, choose **Export** from the **⋯** menu on its card in **Skills**. You get the skill's latest published version as a `.zip` package in the Agent Skills format. + +## Delete a Skill + +Deleting a skill removes it from the workspace and from every agent that uses it, along with all of its versions. A deleted skill can't be recovered; export a copy first if you may need it again. diff --git a/en/self-host/use-dify/build/skills/overview.mdx b/en/self-host/use-dify/build/skills/overview.mdx new file mode 100644 index 000000000..52c977a86 --- /dev/null +++ b/en/self-host/use-dify/build/skills/overview.mdx @@ -0,0 +1,25 @@ +--- +title: Skills +sidebarTitle: Overview +description: Package a task's instructions once as a reusable skill, then share it across your agents +--- + +A *skill* is a self-contained procedure you package for an agent: the instructions for one task, plus any reference materials and scripts, bundled together so you define it once and reuse it. + +Where the prompt sets an agent's overall role, a skill is a job aid it pulls in only when a particular task calls for it. The agent brings the general ability; the skill gives it your exact steps for that job, so the work comes out the way you expect. + +Skills follow the open [Agent Skills](https://agentskills.io/home) format, which puts the instructions in a `SKILL.md` file, so you can move a skill in and out of Dify as a single `.zip` package. + +## How a Skill Fits + +Suppose your agent handles customer support. A knowledge base or file gives the agent facts to read, like your refund policy. A tool gives it actions to take, like looking up an order or issuing a refund through a workflow. A skill gives it a method to follow: check the order status first, offer a refund only within the 30-day window, keep the tone warm, and close with a help-center link. + +When the agent has those resources configured, you can name them in a skill in plain language and say when the agent should draw on each. The method and the resources complement each other. + +## Where a Skill Lives + +A skill can live in two places, and the place decides how far it reaches. + +A *library skill* is a procedure you share across your agents. It lives in your library, the **Skills** page in your workspace. Revise and publish once, and every agent that uses it picks up the latest change. See [Skill Library](/en/self-host/use-dify/build/skills/library) to create, publish, and add them to your agents. + +An *embedded skill* is a procedure you keep to [a single agent](/en/self-host/use-dify/build/new-agent/build#skills). You create or upload one there, and it becomes part of the agent's own setup. From ad6be8204e41b6f97ed758080284dc9f95798f36 Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 29 Jul 2026 17:08:26 +0800 Subject: [PATCH 02/20] docs: clarify skill-resource pairing sentence in skills overview Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/skills/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/self-host/use-dify/build/skills/overview.mdx b/en/self-host/use-dify/build/skills/overview.mdx index 52c977a86..aad700d44 100644 --- a/en/self-host/use-dify/build/skills/overview.mdx +++ b/en/self-host/use-dify/build/skills/overview.mdx @@ -14,7 +14,7 @@ Skills follow the open [Agent Skills](https://agentskills.io/home) format, which Suppose your agent handles customer support. A knowledge base or file gives the agent facts to read, like your refund policy. A tool gives it actions to take, like looking up an order or issuing a refund through a workflow. A skill gives it a method to follow: check the order status first, offer a refund only within the 30-day window, keep the tone warm, and close with a help-center link. -When the agent has those resources configured, you can name them in a skill in plain language and say when the agent should draw on each. The method and the resources complement each other. +When the agent has those resources configured, you can name them in a skill in plain language and say when the agent should draw on each. The skill and the resources complement each other. ## Where a Skill Lives From ff9fa01917c981dc58b052c4069f9085912f103f Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 29 Jul 2026 23:16:18 +0800 Subject: [PATCH 03/20] docs: streamline skills guides wording after review Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/new-agent/build.mdx | 4 ++-- en/self-host/use-dify/build/skills/library.mdx | 12 +++++------- en/self-host/use-dify/build/skills/overview.mdx | 2 +- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 438704135..f6ccbddb5 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -57,12 +57,12 @@ You can point the agent at a specific embedded skill, file, tool, or knowledge s ### Skills -Add skills to hand the agent your procedures for recurring tasks. For what a skill is and when to reach for one, see [Skills](/en/self-host/use-dify/build/skills/overview). +Add skills to hand the agent your standard procedures. For what a skill is and when to reach for one, see [Skills](/en/self-host/use-dify/build/skills/overview). Click **Add** and choose where the skill comes from: - Choose **From skill library** to attach a *library skill* shared across your agents. The agent follows the skill's latest published version. To create and manage library skills, see [Skill Library](/en/self-host/use-dify/build/skills/library). -- Choose **Upload package** to add an *embedded skill*, one the agent keeps to itself: a `.zip` or `.skill` file no larger than 50 MB, with a `SKILL.md` inside, in the [Agent Skills](https://agentskills.io/home) format. To share it with other agents, import its package into the [Skill Library](/en/self-host/use-dify/build/skills/library#import-a-skill). +- Choose **Upload package** to add an *embedded skill*, one the agent keeps to itself: a `.zip` or `.skill` package no larger than 50 MB, in the [Agent Skills](https://agentskills.io/home) format. To share it with other agents, import its package into the [Skill Library](/en/self-host/use-dify/build/skills/library#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). diff --git a/en/self-host/use-dify/build/skills/library.mdx b/en/self-host/use-dify/build/skills/library.mdx index 6280c106b..0c9fec415 100644 --- a/en/self-host/use-dify/build/skills/library.mdx +++ b/en/self-host/use-dify/build/skills/library.mdx @@ -6,13 +6,13 @@ description: Create, edit, publish, and share library skills for your agents ## Create a Skill -From **Skills**, click **Create**. A new skill opens in the editor with a starter `SKILL.md`, and the **Skill Builder** panel opens beside it. To start from an existing skill instead, choose **Duplicate** from its **⋯** menu; the copy is a new draft of the latest published content. +From **Skills**, click **Create**. To start from an existing skill instead, choose **Duplicate** from its **⋯** menu; the copy starts as a draft. Creating and managing skills requires the Editor role or above. -Write the skill by hand, or draft it with the **Skill Builder**: describe the scenario or attach an existing process doc, and it suggests content in the chat. The builder doesn't edit your files; applying its suggestions is up to you. +Write the skill by hand, or draft it with the **Skill Builder**: describe the scenario or attach an existing process doc, and it suggests content in the chat; applying it is up to you. Either way, the skill takes shape in `SKILL.md`: the frontmatter carries its `name`, `description`, and other metadata, and the body holds the procedure itself. @@ -31,7 +31,7 @@ Keep the tone warm, and close with a help-center link. The following settings shape how the skill is found and used: -- **Names**: after a skill is published, renaming it changes only the `display-name`; the internal `name` keeps its value until you edit it yourself. +- **Names**: after a skill is published, renaming it changes only the `display-name`. - **Description**: state what the skill does and when an agent should use it. - **Metadata**: to keep extra information with the skill, add custom frontmatter fields. - **Supporting files**: if the task needs more than instructions, add templates, scripts, or reference docs through the file tree. @@ -41,9 +41,7 @@ When the skill is ready, publish it to make it available to agents. ## Publish and Versions -Your edits autosave as a draft, and agents keep using the last published version until you publish again. - -Each publish is saved as a version. Open the version history anytime to revisit or restore an earlier version. +Your edits autosave as a draft and reach agents only when you publish. Each publish is saved as a version you can revisit or restore later. Restoring a version publishes it immediately as the newest version. @@ -51,7 +49,7 @@ Restoring a version publishes it immediately as the newest version. ## Add to Agents -In the agent's **Configure** page, under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. The same works for an agent you configure inside a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). +From **Agents**, open the agent's **Configure** page. Under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. You can also add skills in a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). ## Import a Skill diff --git a/en/self-host/use-dify/build/skills/overview.mdx b/en/self-host/use-dify/build/skills/overview.mdx index aad700d44..8db899241 100644 --- a/en/self-host/use-dify/build/skills/overview.mdx +++ b/en/self-host/use-dify/build/skills/overview.mdx @@ -12,7 +12,7 @@ Skills follow the open [Agent Skills](https://agentskills.io/home) format, which ## How a Skill Fits -Suppose your agent handles customer support. A knowledge base or file gives the agent facts to read, like your refund policy. A tool gives it actions to take, like looking up an order or issuing a refund through a workflow. A skill gives it a method to follow: check the order status first, offer a refund only within the 30-day window, keep the tone warm, and close with a help-center link. +Suppose your agent handles customer support. Each resource you add to its setup helps in a different way. A knowledge base or file gives the agent facts to read, like your refund policy. A tool gives it an action to take, like looking up an order or issuing a refund through a workflow. A skill gives it a method to follow: check the order status first, offer a refund only within the 30-day window, keep the tone warm, and close with a help-center link. When the agent has those resources configured, you can name them in a skill in plain language and say when the agent should draw on each. The skill and the resources complement each other. From 41ba845543a493b60c6fba5a4262448192da614e Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 30 Jul 2026 13:28:49 +0800 Subject: [PATCH 04/20] docs: skills can be referenced in prompt regardless of source Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/new-agent/build.mdx | 2 +- en/self-host/use-dify/build/skills/library.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index f6ccbddb5..1c50e2bcf 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -49,7 +49,7 @@ A few things worth covering: - **Tool and file use**: when to reach for each, named explicitly. - **Output**: the format, length, or tone you want back. -You can point the agent at a specific embedded skill, file, tool, or knowledge source, or leave the choice to the agent: +You can point the agent at a specific skill, file, tool, or knowledge source, or leave the choice to the agent: - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. diff --git a/en/self-host/use-dify/build/skills/library.mdx b/en/self-host/use-dify/build/skills/library.mdx index 0c9fec415..4eb615645 100644 --- a/en/self-host/use-dify/build/skills/library.mdx +++ b/en/self-host/use-dify/build/skills/library.mdx @@ -49,7 +49,7 @@ Restoring a version publishes it immediately as the newest version. ## Add to Agents -From **Agents**, open the agent's **Configure** page. Under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. You can also add skills in a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). +From **Agents**, open the agent's **Configure** page. Under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. To point the agent at the skill for a specific step, reference it in the prompt with `/`. You can also add skills in a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). ## Import a Skill From 5d8f5bf1c0730d48be67fc02d4b7f9464b79eba4 Mon Sep 17 00:00:00 2001 From: yajing Date: Mon, 3 Aug 2026 19:34:36 +0800 Subject: [PATCH 05/20] docs: merge skills guides into one page and refine agent skills section Co-Authored-By: Claude Opus 4.8 --- docs.json | 9 +-- .../use-dify/build/new-agent/build.mdx | 13 ++- en/self-host/use-dify/build/skills.mdx | 80 +++++++++++++++++++ .../use-dify/build/skills/library.mdx | 66 --------------- .../use-dify/build/skills/overview.mdx | 25 ------ 5 files changed, 90 insertions(+), 103 deletions(-) create mode 100644 en/self-host/use-dify/build/skills.mdx delete mode 100644 en/self-host/use-dify/build/skills/library.mdx delete mode 100644 en/self-host/use-dify/build/skills/overview.mdx diff --git a/docs.json b/docs.json index 264ea0330..9c55892f2 100644 --- a/docs.json +++ b/docs.json @@ -828,14 +828,7 @@ ], "expanded": false }, - { - "group": "Skills", - "pages": [ - "en/self-host/use-dify/build/skills/overview", - "en/self-host/use-dify/build/skills/library" - ], - "expanded": false - }, + "en/self-host/use-dify/build/skills", { "group": "Basic Apps", "pages": [ diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 1c50e2bcf..1aaf0dd6e 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -52,20 +52,25 @@ A few things worth covering: You can point the agent at a specific skill, file, tool, or knowledge source, or leave the choice to the agent: - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. - - **Just add it to its section** and let the agent decide on its own when to use it. Best when you'd rather trust the agent's judgment than script every move. +You can reference a library skill or tool with `/` right away, since they're shared across your workspace. As for files, knowledge sources, or embedded skills, add them to their respective sections first, then reference them with `/`. + ### Skills -Add skills to hand the agent your standard procedures. For what a skill is and when to reach for one, see [Skills](/en/self-host/use-dify/build/skills/overview). +A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers a single job. For example, a support agent's prompt might keep it warm and careful to verify accounts, while its `refund-requests` skill handles that one job: look up the order, refund only within 30 days, and end with a help-center link. Click **Add** and choose where the skill comes from: -- Choose **From skill library** to attach a *library skill* shared across your agents. The agent follows the skill's latest published version. To create and manage library skills, see [Skill Library](/en/self-host/use-dify/build/skills/library). -- Choose **Upload package** to add an *embedded skill*, one the agent keeps to itself: a `.zip` or `.skill` package no larger than 50 MB, in the [Agent Skills](https://agentskills.io/home) format. To share it with other agents, import its package into the [Skill Library](/en/self-host/use-dify/build/skills/library#import-a-skill). +- Choose **From skill library** to attach a *library skill* shared workspace-wide. The agent follows the skill's latest published version. To create and manage library skills, see [Skills](/en/self-host/use-dify/build/skills). +- Choose **Upload package** to add a `.zip` or `.skill` package no larger than 50 MB as an *embedded skill*, one the agent keeps to itself. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). + +If your skill relies on a tool, file, or knowledge source, add it to the agent, and the agent uses it when the work calls for it. Referencing it in the skill alone won't call it. + + ### Files Files are reference documents the agent can read while it works, like specs, templates, or guidelines. Unlike a skill, a file is just material to read, not a procedure to run. diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx new file mode 100644 index 000000000..b0e9782c3 --- /dev/null +++ b/en/self-host/use-dify/build/skills.mdx @@ -0,0 +1,80 @@ +--- +title: Skills +sidebarTitle: Skills +description: Package a task and its supporting files into a reusable skill, then share it workspace-wide +--- + +A *skill* is a self-contained procedure you package for an agent: the instructions for one task, plus any reference materials and scripts, bundled together so you define it once and reuse it. Each skill contains at least a `SKILL.md`. For the full format, see [Agent Skills](https://agentskills.io/home). + +You keep a *library skill* in your workspace, where it's shared workspace-wide. Publish it once, and every agent that uses it picks up your latest change. + +Use a skill in: + +- a [New Agent](/en/self-host/use-dify/build/new-agent/build#skills) app +- a [New Agent node](/en/self-host/use-dify/nodes/agent) in a [Workflow app](/en/self-host/use-dify/build/workflow-chatflow) + +Create, import, and manage your skills on the **Skills** page in your workspace. + +## Create a Skill + +From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu. Either way you land in the editor, where you build the skill by hand or with the **Skill Builder**. + + +Creating and managing skills requires the Editor role or above. + + +### Draft with the Skill Builder + +You can build a skill just by chatting. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates any supporting files in your draft for you to review and refine. It accepts the following file types as context: + +| Type | Examples | +|:-----|:---------| +| PDF | `.pdf` | +| Word | `.doc`, `.docx` | +| Excel | `.xls`, `.xlsx` | +| PowerPoint | `.ppt`, `.pptx` | +| RTF | `.rtf` | +| Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | + +Attach up to 3 files per message, up to 20 MB each. To include a script, add it to the skill's `scripts/` folder through the file tree. + +### Write it by hand + +You can also write the skill yourself, or refine what the Skill Builder drafted. `SKILL.md` holds the skill itself: the body is the procedure the agent follows, and the frontmatter shapes how it finds and uses the skill. + +- **Name**: the skill's unique ID, like `refund-requests`. The agent reads it and the description to decide when to use the skill. +- **Description**: the main factor in the agent's decision. Make it specific. +- **Display name**: the name you see and pick wherever the skill appears. Make it easy to recognize. +- **Metadata**: custom fields for your own reference details, like `owner: payments-team` or `source: https://wiki.example.com/refund-policy`. + +Add scripts, references, and other files that the task needs through the file tree. What you can do with each one depends on its type: + +- **Text and code** (Markdown, scripts, JSON, YAML, CSV, and the like): edit in place. +- **Images and PDFs**: preview in place. +- **Other files**: download to view. + +Each file can be up to 100 MB. To allow larger uploads, raise the size limit in your [environment variables](/en/self-host/deploy/configuration/environments). To point to a supporting file from your instructions, type `/` in `SKILL.md` and pick the file. + +To tag a skill, hover its card and click **Add tag**. You can then filter skills by tags. + +## Import a Skill + +To bring in a skill built elsewhere, click **Import** and choose a `.zip` or `.skill` package. It must contain a `SKILL.md`. Once imported, it arrives as a draft for you to review and publish. + +To turn an agent's embedded skill into a library skill, import its package here. + +## Publish and Versions + +Your edits autosave as a draft. Publish the draft so you can add it to agents. Each publish is saved as a version you can revisit or restore later. + + +Restoring a version publishes it immediately as the newest version. + + +## Export a Skill + +To take a skill beyond this workspace, choose **Export** from the **⋯** menu on its card. You get the skill's latest published version as a `.zip`. + +## Delete a Skill + +Deleting a skill removes it from the workspace and from every agent that uses it, along with all of its versions. A deleted skill can't be recovered; export a copy first if you may need it again. diff --git a/en/self-host/use-dify/build/skills/library.mdx b/en/self-host/use-dify/build/skills/library.mdx deleted file mode 100644 index 4eb615645..000000000 --- a/en/self-host/use-dify/build/skills/library.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Manage the Skill Library -sidebarTitle: Skill Library -description: Create, edit, publish, and share library skills for your agents ---- - -## Create a Skill - -From **Skills**, click **Create**. To start from an existing skill instead, choose **Duplicate** from its **⋯** menu; the copy starts as a draft. - - -Creating and managing skills requires the Editor role or above. - - -Write the skill by hand, or draft it with the **Skill Builder**: describe the scenario or attach an existing process doc, and it suggests content in the chat; applying it is up to you. - -Either way, the skill takes shape in `SKILL.md`: the frontmatter carries its `name`, `description`, and other metadata, and the body holds the procedure itself. - -```markdown ---- -name: refund-requests -description: Handle customer refund requests the standard way. Use when a customer asks for a refund or reports a billing issue. -metadata: - display-name: Refund requests ---- - -Check the order status before promising anything. -Offer a refund only within the 30-day window. -Keep the tone warm, and close with a help-center link. -``` - -The following settings shape how the skill is found and used: - -- **Names**: after a skill is published, renaming it changes only the `display-name`. -- **Description**: state what the skill does and when an agent should use it. -- **Metadata**: to keep extra information with the skill, add custom frontmatter fields. -- **Supporting files**: if the task needs more than instructions, add templates, scripts, or reference docs through the file tree. -- **Tags**: add them from the editor sidebar, then filter by tag on the **Skills** page. They're for organizing the library only. Changes to tags take effect without publishing. - -When the skill is ready, publish it to make it available to agents. - -## Publish and Versions - -Your edits autosave as a draft and reach agents only when you publish. Each publish is saved as a version you can revisit or restore later. - - -Restoring a version publishes it immediately as the newest version. - - -## Add to Agents - -From **Agents**, open the agent's **Configure** page. Under **SKILLS**, click **Add** and choose **From skill library**. The agent follows the skill's latest published version from then on, and decides when to use it by its name and description. To point the agent at the skill for a specific step, reference it in the prompt with `/`. You can also add skills in a workflow's [Agent node](/en/self-host/use-dify/nodes/agent). - -## Import a Skill - -To bring in a skill built elsewhere, click **Import** on the **Skills** page and choose a `.zip` or `.skill` package in the [Agent Skills](https://agentskills.io/home) format. The package arrives as a draft for you to review and publish. - -To turn an agent's embedded skill into a library skill, import its package here. - -## Export a Skill - -To take a skill beyond this workspace, choose **Export** from the **⋯** menu on its card in **Skills**. You get the skill's latest published version as a `.zip` package in the Agent Skills format. - -## Delete a Skill - -Deleting a skill removes it from the workspace and from every agent that uses it, along with all of its versions. A deleted skill can't be recovered; export a copy first if you may need it again. diff --git a/en/self-host/use-dify/build/skills/overview.mdx b/en/self-host/use-dify/build/skills/overview.mdx deleted file mode 100644 index 8db899241..000000000 --- a/en/self-host/use-dify/build/skills/overview.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Skills -sidebarTitle: Overview -description: Package a task's instructions once as a reusable skill, then share it across your agents ---- - -A *skill* is a self-contained procedure you package for an agent: the instructions for one task, plus any reference materials and scripts, bundled together so you define it once and reuse it. - -Where the prompt sets an agent's overall role, a skill is a job aid it pulls in only when a particular task calls for it. The agent brings the general ability; the skill gives it your exact steps for that job, so the work comes out the way you expect. - -Skills follow the open [Agent Skills](https://agentskills.io/home) format, which puts the instructions in a `SKILL.md` file, so you can move a skill in and out of Dify as a single `.zip` package. - -## How a Skill Fits - -Suppose your agent handles customer support. Each resource you add to its setup helps in a different way. A knowledge base or file gives the agent facts to read, like your refund policy. A tool gives it an action to take, like looking up an order or issuing a refund through a workflow. A skill gives it a method to follow: check the order status first, offer a refund only within the 30-day window, keep the tone warm, and close with a help-center link. - -When the agent has those resources configured, you can name them in a skill in plain language and say when the agent should draw on each. The skill and the resources complement each other. - -## Where a Skill Lives - -A skill can live in two places, and the place decides how far it reaches. - -A *library skill* is a procedure you share across your agents. It lives in your library, the **Skills** page in your workspace. Revise and publish once, and every agent that uses it picks up the latest change. See [Skill Library](/en/self-host/use-dify/build/skills/library) to create, publish, and add them to your agents. - -An *embedded skill* is a procedure you keep to [a single agent](/en/self-host/use-dify/build/new-agent/build#skills). You create or upload one there, and it becomes part of the agent's own setup. From 8912e135656b193557806532920b9133833637ef Mon Sep 17 00:00:00 2001 From: yajing Date: Mon, 3 Aug 2026 23:28:23 +0800 Subject: [PATCH 06/20] docs: refine skills create-flow structure and agent skills notes Co-Authored-By: Claude Opus 4.8 --- .../use-dify/build/new-agent/build.mdx | 8 +-- en/self-host/use-dify/build/skills.mdx | 52 +++++++++++-------- 2 files changed, 35 insertions(+), 25 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 1aaf0dd6e..f5134a6e6 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -54,11 +54,13 @@ You can point the agent at a specific skill, file, tool, or knowledge source, or - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. - **Just add it to its section** and let the agent decide on its own when to use it. Best when you'd rather trust the agent's judgment than script every move. -You can reference a library skill or tool with `/` right away, since they're shared across your workspace. As for files, knowledge sources, or embedded skills, add them to their respective sections first, then reference them with `/`. + +You can reference a library skill or tool with `/` right away, since they're shared across your workspace. You can do the same for a file, knowledge source, or embedded skill once it's in its section. + ### Skills -A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers a single job. For example, a support agent's prompt might keep it warm and careful to verify accounts, while its `refund-requests` skill handles that one job: look up the order, refund only within 30 days, and end with a help-center link. +A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers just that task. For example, a support agent's prompt might keep it warm and careful to verify accounts, while its `refund-requests` skill handles only one job: look up the order, refund only within 30 days, and end with a help-center link. Click **Add** and choose where the skill comes from: @@ -68,7 +70,7 @@ Click **Add** and choose where the skill comes from: You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). -If your skill relies on a tool, file, or knowledge source, add it to the agent, and the agent uses it when the work calls for it. Referencing it in the skill alone won't call it. +Referencing a tool, file, or knowledge source in a skill doesn't call it. To use one, add it to the agent. ### Files diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index b0e9782c3..a850a55fa 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -4,7 +4,7 @@ sidebarTitle: Skills description: Package a task and its supporting files into a reusable skill, then share it workspace-wide --- -A *skill* is a self-contained procedure you package for an agent: the instructions for one task, plus any reference materials and scripts, bundled together so you define it once and reuse it. Each skill contains at least a `SKILL.md`. For the full format, see [Agent Skills](https://agentskills.io/home). +A *skill* is a self-contained package you build once and reuse: a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials to consult and scripts to run as the agent works. For the full format, see [Agent Skills](https://agentskills.io/home). You keep a *library skill* in your workspace, where it's shared workspace-wide. Publish it once, and every agent that uses it picks up your latest change. @@ -23,45 +23,53 @@ From **Skills**, click **Create**. To start from a copy instead, choose **Duplic Creating and managing skills requires the Editor role or above. -### Draft with the Skill Builder - -You can build a skill just by chatting. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates any supporting files in your draft for you to review and refine. It accepts the following file types as context: - -| Type | Examples | -|:-----|:---------| -| PDF | `.pdf` | -| Word | `.doc`, `.docx` | -| Excel | `.xls`, `.xlsx` | -| PowerPoint | `.ppt`, `.pptx` | -| RTF | `.rtf` | -| Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | - -Attach up to 3 files per message, up to 20 MB each. To include a script, add it to the skill's `scripts/` folder through the file tree. - ### Write it by hand -You can also write the skill yourself, or refine what the Skill Builder drafted. `SKILL.md` holds the skill itself: the body is the procedure the agent follows, and the frontmatter shapes how it finds and uses the skill. +Build the skill yourself in the editor: write the `SKILL.md` and add any supporting files it needs. + +`SKILL.md` holds the skill itself. The body is the procedure the agent follows, and the frontmatter sets: - **Name**: the skill's unique ID, like `refund-requests`. The agent reads it and the description to decide when to use the skill. - **Description**: the main factor in the agent's decision. Make it specific. - **Display name**: the name you see and pick wherever the skill appears. Make it easy to recognize. - **Metadata**: custom fields for your own reference details, like `owner: payments-team` or `source: https://wiki.example.com/refund-policy`. -Add scripts, references, and other files that the task needs through the file tree. What you can do with each one depends on its type: +Add scripts, references, and other supporting files through the file tree. What you can do with each depends on its type: - **Text and code** (Markdown, scripts, JSON, YAML, CSV, and the like): edit in place. - **Images and PDFs**: preview in place. - **Other files**: download to view. -Each file can be up to 100 MB. To allow larger uploads, raise the size limit in your [environment variables](/en/self-host/deploy/configuration/environments). To point to a supporting file from your instructions, type `/` in `SKILL.md` and pick the file. +Each file can be up to 100 MB. To allow larger uploads, raise the size limit in your [environment variables](/en/self-host/deploy/configuration/environments). -To tag a skill, hover its card and click **Add tag**. You can then filter skills by tags. +### Draft with the Skill Builder + +Instead of writing the skill yourself, chat with the Skill Builder. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates supporting files for you to review and refine. + +It accepts the following file types as context: + +| Type | Examples | +|:-----|:---------| +| PDF | `.pdf` | +| Word | `.doc`, `.docx` | +| Excel | `.xls`, `.xlsx` | +| PowerPoint | `.ppt`, `.pptx` | +| RTF | `.rtf` | +| Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | + +Attach up to 3 files per message, up to 20 MB each. + + +Files you attach here are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. + ## Import a Skill -To bring in a skill built elsewhere, click **Import** and choose a `.zip` or `.skill` package. It must contain a `SKILL.md`. Once imported, it arrives as a draft for you to review and publish. +To bring in a skill built elsewhere as a library skill, click **Import** and choose a `.zip` or `.skill` package. It must contain a `SKILL.md`. Once imported, it arrives as a draft for you to review and publish. -To turn an agent's embedded skill into a library skill, import its package here. +## Tag a Skill + +To tag a skill, hover its card and click **Add tag**. You can then filter skills by tags. ## Publish and Versions From 7ed6f0c82b751b012ced5eb15072c905d278d8ea Mon Sep 17 00:00:00 2001 From: yajing Date: Tue, 4 Aug 2026 10:46:01 +0800 Subject: [PATCH 07/20] docs: align skills page with style conventions and tidy wording Co-Authored-By: Claude Opus 4.8 --- .../use-dify/build/new-agent/build.mdx | 4 ++-- en/self-host/use-dify/build/skills.mdx | 18 +++++++----------- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index f5134a6e6..8b4ac1023 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -54,9 +54,9 @@ You can point the agent at a specific skill, file, tool, or knowledge source, or - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. - **Just add it to its section** and let the agent decide on its own when to use it. Best when you'd rather trust the agent's judgment than script every move. - + You can reference a library skill or tool with `/` right away, since they're shared across your workspace. You can do the same for a file, knowledge source, or embedded skill once it's in its section. - + ### Skills diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index a850a55fa..f4578830f 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -4,16 +4,16 @@ sidebarTitle: Skills description: Package a task and its supporting files into a reusable skill, then share it workspace-wide --- -A *skill* is a self-contained package you build once and reuse: a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials to consult and scripts to run as the agent works. For the full format, see [Agent Skills](https://agentskills.io/home). +A *skill* is a self-contained package you build once and reuse. It includes a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials to consult and scripts to run as the agent works. For the full format, see [Agent Skills](https://agentskills.io/home). -You keep a *library skill* in your workspace, where it's shared workspace-wide. Publish it once, and every agent that uses it picks up your latest change. +You can keep a skill in the library to share it workspace-wide. Publish it once, and every agent that uses it picks up your latest change. Use a skill in: - a [New Agent](/en/self-host/use-dify/build/new-agent/build#skills) app - a [New Agent node](/en/self-host/use-dify/nodes/agent) in a [Workflow app](/en/self-host/use-dify/build/workflow-chatflow) -Create, import, and manage your skills on the **Skills** page in your workspace. +Create, import, and manage your library skills on the **Skills** page in your workspace. ## Create a Skill @@ -23,7 +23,7 @@ From **Skills**, click **Create**. To start from a copy instead, choose **Duplic Creating and managing skills requires the Editor role or above. -### Write it by hand +### Write It by Hand Build the skill yourself in the editor: write the `SKILL.md` and add any supporting files it needs. @@ -40,7 +40,7 @@ Add scripts, references, and other supporting files through the file tree. What - **Images and PDFs**: preview in place. - **Other files**: download to view. -Each file can be up to 100 MB. To allow larger uploads, raise the size limit in your [environment variables](/en/self-host/deploy/configuration/environments). +Each file can be up to 100 MB. To allow larger uploads, raise `NGINX_CLIENT_MAX_BODY_SIZE` in your [environment variables](/en/self-host/deploy/configuration/environments). ### Draft with the Skill Builder @@ -57,11 +57,7 @@ It accepts the following file types as context: | RTF | `.rtf` | | Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | -Attach up to 3 files per message, up to 20 MB each. - - -Files you attach here are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. - +Attach up to 3 files per message, up to 20 MB each. They are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. ## Import a Skill @@ -69,7 +65,7 @@ To bring in a skill built elsewhere as a library skill, click **Import** and cho ## Tag a Skill -To tag a skill, hover its card and click **Add tag**. You can then filter skills by tags. +Hover a skill's card and click **Add tag**. You can then filter skills by tags. ## Publish and Versions From 82c228b4abe7cb47102af7f5b2d41773a5218a19 Mon Sep 17 00:00:00 2001 From: yajing Date: Tue, 4 Aug 2026 10:52:46 +0800 Subject: [PATCH 08/20] docs: drop redundant "as context" from skill builder file-types line Co-Authored-By: Claude Opus 4.8 --- en/self-host/use-dify/build/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index f4578830f..2efbe3ec8 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -46,7 +46,7 @@ Each file can be up to 100 MB. To allow larger uploads, raise `NGINX_CLIENT_MAX_ Instead of writing the skill yourself, chat with the Skill Builder. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates supporting files for you to review and refine. -It accepts the following file types as context: +It accepts the following file types: | Type | Examples | |:-----|:---------| From 88d95c008ca70156e308d18f3b3243ee29c7ecc9 Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 5 Aug 2026 18:02:44 +0800 Subject: [PATCH 09/20] docs: document skill upload limit env var and tidy skills sections Co-Authored-By: Claude Fable 5 --- .../deploy/configuration/environments.mdx | 8 +++++++ .../use-dify/build/new-agent/build.mdx | 18 +++++++------- en/self-host/use-dify/build/skills.mdx | 24 ++++++++----------- 3 files changed, 28 insertions(+), 22 deletions(-) diff --git a/en/self-host/deploy/configuration/environments.mdx b/en/self-host/deploy/configuration/environments.mdx index b2b25939d..f16f3231b 100644 --- a/en/self-host/deploy/configuration/environments.mdx +++ b/en/self-host/deploy/configuration/environments.mdx @@ -1399,6 +1399,14 @@ Shows the New Agent in the web UI: the **Agents** item in the main navigation an Set to `false` to hide it and fall back to the classic Agent node. Replaces `ENABLE_AGENT_V2`, which still works as a fallback. +### UPLOAD_SKILL_FILE_SIZE_LIMIT + +Default: `50` + +Maximum size in MB for a skill package (`.zip` or `.skill`) uploaded to an agent as an embedded skill. Larger packages are rejected with a size error. + +Only agent-side uploads read this limit; importing a skill into the skill library has its own fixed caps (50 files, 512 KB each, 5 MB per package) that this variable doesn't change. If you raise it above 100, also raise `NGINX_CLIENT_MAX_BODY_SIZE` to match; otherwise Nginx rejects the upload with a 413 error. + ### AGENT_BACKEND_BASE_URL Default: `http://agent_backend:5050` diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 8b4ac1023..e75f4155e 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -49,28 +49,30 @@ A few things worth covering: - **Tool and file use**: when to reach for each, named explicitly. - **Output**: the format, length, or tone you want back. -You can point the agent at a specific skill, file, tool, or knowledge source, or leave the choice to the agent: +You can point the agent at a specific skill, file, tool, or knowledge base, or leave the choice to the agent: - **Reference it in the prompt** with `/` to send the agent straight to it, right where you want it used. Best when a step depends on a specific one. - **Just add it to its section** and let the agent decide on its own when to use it. Best when you'd rather trust the agent's judgment than script every move. - -You can reference a library skill or tool with `/` right away, since they're shared across your workspace. You can do the same for a file, knowledge source, or embedded skill once it's in its section. - - ### Skills -A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers just that task. For example, a support agent's prompt might keep it warm and careful to verify accounts, while its `refund-requests` skill handles only one job: look up the order, refund only within 30 days, and end with a help-center link. +A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers just that task. + +For example, a support agent's prompt might set its role as a helper that answers any customer question, while its `refund-requests` skill only handles refund tasks: look up the order, refund only within 30 days, and end with a help-center link. Click **Add** and choose where the skill comes from: -- Choose **From skill library** to attach a *library skill* shared workspace-wide. The agent follows the skill's latest published version. To create and manage library skills, see [Skills](/en/self-host/use-dify/build/skills). +- Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide, up to 20. The agent follows the skill's latest published version. - Choose **Upload package** to add a `.zip` or `.skill` package no larger than 50 MB as an *embedded skill*, one the agent keeps to itself. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). + +To allow packages larger than 50 MB, raise [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) in your environment variables. + + -Referencing a tool, file, or knowledge source in a skill doesn't call it. To use one, add it to the agent. +Referencing a Dify tool, file, or knowledge base in a skill doesn't use it. To use one, add it to the agent. ### Files diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 2efbe3ec8..0ebe6285f 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -4,7 +4,7 @@ sidebarTitle: Skills description: Package a task and its supporting files into a reusable skill, then share it workspace-wide --- -A *skill* is a self-contained package you build once and reuse. It includes a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials to consult and scripts to run as the agent works. For the full format, see [Agent Skills](https://agentskills.io/home). +A *skill* is a self-contained package you build once and reuse. It includes a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials and scripts the task needs. For the full format, see [Agent Skills](https://agentskills.io/home). You can keep a skill in the library to share it workspace-wide. Publish it once, and every agent that uses it picks up your latest change. @@ -13,38 +13,34 @@ Use a skill in: - a [New Agent](/en/self-host/use-dify/build/new-agent/build#skills) app - a [New Agent node](/en/self-host/use-dify/nodes/agent) in a [Workflow app](/en/self-host/use-dify/build/workflow-chatflow) -Create, import, and manage your library skills on the **Skills** page in your workspace. - -## Create a Skill - -From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu. Either way you land in the editor, where you build the skill by hand or with the **Skill Builder**. +The library lives on the **Skills** page in your workspace, where you create, import, and manage up to 500 skills. Creating and managing skills requires the Editor role or above. -### Write It by Hand +## Create a Skill -Build the skill yourself in the editor: write the `SKILL.md` and add any supporting files it needs. +From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu. Either way you land in the editor, where you write the skill yourself or draft it with the [Skill Builder](#draft-with-the-skill-builder). -`SKILL.md` holds the skill itself. The body is the procedure the agent follows, and the frontmatter sets: +In the body of `SKILL.md`, lay out the procedure for the agent to follow. In the frontmatter, set: - **Name**: the skill's unique ID, like `refund-requests`. The agent reads it and the description to decide when to use the skill. - **Description**: the main factor in the agent's decision. Make it specific. - **Display name**: the name you see and pick wherever the skill appears. Make it easy to recognize. - **Metadata**: custom fields for your own reference details, like `owner: payments-team` or `source: https://wiki.example.com/refund-policy`. -Add scripts, references, and other supporting files through the file tree. What you can do with each depends on its type: +Add any scripts, references, and other supporting files through the file tree. What you can do with each depends on its type: - **Text and code** (Markdown, scripts, JSON, YAML, CSV, and the like): edit in place. - **Images and PDFs**: preview in place. - **Other files**: download to view. -Each file can be up to 100 MB. To allow larger uploads, raise `NGINX_CLIENT_MAX_BODY_SIZE` in your [environment variables](/en/self-host/deploy/configuration/environments). +A skill supports up to 50 files, up to 512 KB each and 5 MB in total. ### Draft with the Skill Builder -Instead of writing the skill yourself, chat with the Skill Builder. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates supporting files for you to review and refine. +Chat with the Skill Builder and it drafts the skill for you. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates supporting files to review and refine. It accepts the following file types: @@ -61,11 +57,11 @@ Attach up to 3 files per message, up to 20 MB each. They are context for the Ski ## Import a Skill -To bring in a skill built elsewhere as a library skill, click **Import** and choose a `.zip` or `.skill` package. It must contain a `SKILL.md`. Once imported, it arrives as a draft for you to review and publish. +To bring in a skill built elsewhere as a library skill, click **Import** and choose a `.zip` or `.skill` package. Make sure it has a `SKILL.md` inside. Once imported, it arrives as a draft for you to review and publish. ## Tag a Skill -Hover a skill's card and click **Add tag**. You can then filter skills by tags. +Add tags to a skill on its card or in the editor, then filter the library by tags. ## Publish and Versions From 20ab2baac7b715a3e1b1301096e962a57345181d Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 5 Aug 2026 18:19:35 +0800 Subject: [PATCH 10/20] style: inline skill upload limit env var per docs convention Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/new-agent/build.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index e75f4155e..e1f0168a0 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -63,14 +63,10 @@ For example, a support agent's prompt might set its role as a helper that answer Click **Add** and choose where the skill comes from: - Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide, up to 20. The agent follows the skill's latest published version. -- Choose **Upload package** to add a `.zip` or `.skill` package no larger than 50 MB as an *embedded skill*, one the agent keeps to itself. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). +- Choose **Upload package** to add a `.zip` or `.skill` package no larger than 50 MB as an *embedded skill*, one the agent keeps to itself. You can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). - -To allow packages larger than 50 MB, raise [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) in your environment variables. - - Referencing a Dify tool, file, or knowledge base in a skill doesn't use it. To use one, add it to the agent. From 4e44f0355b8d6bdebd19ae3c709d070383d5ff24 Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 5 Aug 2026 18:22:34 +0800 Subject: [PATCH 11/20] docs: move skill library capacity into library intro Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/skills.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 0ebe6285f..090933c8a 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -6,14 +6,14 @@ description: Package a task and its supporting files into a reusable skill, then A *skill* is a self-contained package you build once and reuse. It includes a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials and scripts the task needs. For the full format, see [Agent Skills](https://agentskills.io/home). -You can keep a skill in the library to share it workspace-wide. Publish it once, and every agent that uses it picks up your latest change. +You can keep a skill in the library to share it workspace-wide. Publish it once, and every agent that uses it picks up your latest change. The library can hold up to 500 skills. Use a skill in: - a [New Agent](/en/self-host/use-dify/build/new-agent/build#skills) app - a [New Agent node](/en/self-host/use-dify/nodes/agent) in a [Workflow app](/en/self-host/use-dify/build/workflow-chatflow) -The library lives on the **Skills** page in your workspace, where you create, import, and manage up to 500 skills. +Create, import, and manage your library skills on the **Skills** page. Creating and managing skills requires the Editor role or above. From 0d406e560a09bd9d4d3f4efd78e8cb653bc0ed97 Mon Sep 17 00:00:00 2001 From: yajing Date: Wed, 5 Aug 2026 18:41:37 +0800 Subject: [PATCH 12/20] fix: filter skills by tags, not the library Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 090933c8a..39d31a819 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -61,7 +61,7 @@ To bring in a skill built elsewhere as a library skill, click **Import** and cho ## Tag a Skill -Add tags to a skill on its card or in the editor, then filter the library by tags. +Add tags to a skill on its card or in the editor, then filter skills by tags. ## Publish and Versions From 252f7edefbb38c49254530e9e7d16c655458bd47 Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 6 Aug 2026 18:47:23 +0800 Subject: [PATCH 13/20] docs: align skill pages with unified limits and PRD updates Co-Authored-By: Claude Fable 5 --- en/self-host/deploy/configuration/environments.mdx | 4 ++-- en/self-host/use-dify/build/skills.mdx | 6 ++---- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/en/self-host/deploy/configuration/environments.mdx b/en/self-host/deploy/configuration/environments.mdx index f16f3231b..8cd6a68ba 100644 --- a/en/self-host/deploy/configuration/environments.mdx +++ b/en/self-host/deploy/configuration/environments.mdx @@ -1403,9 +1403,9 @@ Set to `false` to hide it and fall back to the classic Agent node. Replaces `ENA Default: `50` -Maximum size in MB for a skill package (`.zip` or `.skill`) uploaded to an agent as an embedded skill. Larger packages are rejected with a size error. +Maximum size in MB for a skill package (`.zip` or `.skill`), whether uploaded to an agent as an embedded skill or imported into the skill library. Larger packages are rejected with a size error. -Only agent-side uploads read this limit; importing a skill into the skill library has its own fixed caps (50 files, 512 KB each, 5 MB per package) that this variable doesn't change. If you raise it above 100, also raise `NGINX_CLIENT_MAX_BODY_SIZE` to match; otherwise Nginx rejects the upload with a 413 error. +A skill's unpacked content is separately capped at 200 MB and 5000 files, which this variable doesn't change. If you raise it above 100, also raise `NGINX_CLIENT_MAX_BODY_SIZE` to match; otherwise Nginx rejects the upload with a 413 error. ### AGENT_BACKEND_BASE_URL diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 39d31a819..35d34ae86 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -21,7 +21,7 @@ Creating and managing skills requires the Editor role or above. ## Create a Skill -From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu. Either way you land in the editor, where you write the skill yourself or draft it with the [Skill Builder](#draft-with-the-skill-builder). +From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu; you get a copy of the last published version, or of the current draft if the skill has never been published. Either way you land in the editor, where you write the skill yourself or draft it with the [Skill Builder](#draft-with-the-skill-builder). In the body of `SKILL.md`, lay out the procedure for the agent to follow. In the frontmatter, set: @@ -36,8 +36,6 @@ Add any scripts, references, and other supporting files through the file tree. W - **Images and PDFs**: preview in place. - **Other files**: download to view. -A skill supports up to 50 files, up to 512 KB each and 5 MB in total. - ### Draft with the Skill Builder Chat with the Skill Builder and it drafts the skill for you. Describe the scenario or attach existing process docs, and it writes the `SKILL.md` and creates supporting files to review and refine. @@ -65,7 +63,7 @@ Add tags to a skill on its card or in the editor, then filter skills by tags. ## Publish and Versions -Your edits autosave as a draft. Publish the draft so you can add it to agents. Each publish is saved as a version you can revisit or restore later. +Your edits autosave as a draft. Publish the draft so you can add it to agents. Each publish is saved as a version you can revisit or restore later. To record what a version changed, give it a title and note with **Edit version info** in its **⋯** menu. Restoring a version publishes it immediately as the newest version. From d9f45df8726ecab9f96a4c3c78413848c52a2045 Mon Sep 17 00:00:00 2001 From: yajing Date: Fri, 7 Aug 2026 11:38:45 +0800 Subject: [PATCH 14/20] docs: tighten skills example and upload limit wording Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/new-agent/build.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index e1f0168a0..edef12cd4 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -58,12 +58,12 @@ You can point the agent at a specific skill, file, tool, or knowledge base, or l A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent's overall role, a skill covers just that task. -For example, a support agent's prompt might set its role as a helper that answers any customer question, while its `refund-requests` skill only handles refund tasks: look up the order, refund only within 30 days, and end with a help-center link. +For example, a support agent's prompt might set its role as a customer helper that handles any issue, while its `refund-requests` skill covers only refunds: look up the order, refund only within 30 days, and end with a help-center link. Click **Add** and choose where the skill comes from: - Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide, up to 20. The agent follows the skill's latest published version. -- Choose **Upload package** to add a `.zip` or `.skill` package no larger than 50 MB as an *embedded skill*, one the agent keeps to itself. You can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). +- Choose **Upload package** to add a `.zip` or `.skill` package as an *embedded skill*, one the agent keeps to itself. The package can be up to 50 MB. You can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). From 7ecb583c5b4ce55312601de2acd9bfaa6545a61f Mon Sep 17 00:00:00 2001 From: yajing Date: Fri, 7 Aug 2026 14:39:54 +0800 Subject: [PATCH 15/20] docs: update skill builder attachment types and limits Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/skills.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 35d34ae86..1b875607b 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -49,9 +49,10 @@ It accepts the following file types: | Excel | `.xls`, `.xlsx` | | PowerPoint | `.ppt`, `.pptx` | | RTF | `.rtf` | +| Image | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg` | | Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | -Attach up to 3 files per message, up to 20 MB each. They are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. +Attach up to 10 files per message, up to 15 MB each, or 10 MB for an image. They are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. ## Import a Skill From 46530c4b25fd1af643312db865916b366a8597b6 Mon Sep 17 00:00:00 2001 From: yajing Date: Fri, 7 Aug 2026 15:49:18 +0800 Subject: [PATCH 16/20] docs: describe version restore as draft replacement Co-Authored-By: Claude Fable 5 --- en/self-host/use-dify/build/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 1b875607b..2111f021c 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -67,7 +67,7 @@ Add tags to a skill on its card or in the editor, then filter skills by tags. Your edits autosave as a draft. Publish the draft so you can add it to agents. Each publish is saved as a version you can revisit or restore later. To record what a version changed, give it a title and note with **Edit version info** in its **⋯** menu. -Restoring a version publishes it immediately as the newest version. +Restoring a version replaces your current draft. Publish the draft to make it the newest version. ## Export a Skill From 97661d45041d122967baec9908595cc03aadd303 Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 13 Aug 2026 11:06:22 +0800 Subject: [PATCH 17/20] docs: refine skill management guidance --- en/self-host/use-dify/build/new-agent/build.mdx | 4 ++-- en/self-host/use-dify/build/skills.mdx | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index edef12cd4..0e97376d0 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -62,8 +62,8 @@ For example, a support agent's prompt might set its role as a customer helper th Click **Add** and choose where the skill comes from: -- Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide, up to 20. The agent follows the skill's latest published version. -- Choose **Upload package** to add a `.zip` or `.skill` package as an *embedded skill*, one the agent keeps to itself. The package can be up to 50 MB. You can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). +- Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide. You can add up to 20 library skills to an agent, and it follows the latest published version of each. +- Choose **Upload package** to add a `.zip` or `.skill` package as an *embedded skill*, one the agent keeps to itself. The package can be up to 50 MB by default; you can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). diff --git a/en/self-host/use-dify/build/skills.mdx b/en/self-host/use-dify/build/skills.mdx index 2111f021c..289e45f7f 100644 --- a/en/self-host/use-dify/build/skills.mdx +++ b/en/self-host/use-dify/build/skills.mdx @@ -6,7 +6,7 @@ description: Package a task and its supporting files into a reusable skill, then A *skill* is a self-contained package you build once and reuse. It includes a `SKILL.md` that holds the instructions for one task and tells the agent when to use it, plus any reference materials and scripts the task needs. For the full format, see [Agent Skills](https://agentskills.io/home). -You can keep a skill in the library to share it workspace-wide. Publish it once, and every agent that uses it picks up your latest change. The library can hold up to 500 skills. +You can keep up to 500 skills in the library and share them workspace-wide. When you publish an update to a skill, every agent that uses it picks up the latest version. Use a skill in: @@ -21,13 +21,13 @@ Creating and managing skills requires the Editor role or above. ## Create a Skill -From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu; you get a copy of the last published version, or of the current draft if the skill has never been published. Either way you land in the editor, where you write the skill yourself or draft it with the [Skill Builder](#draft-with-the-skill-builder). +From **Skills**, click **Create**. To start from a copy instead, choose **Duplicate** from an existing skill's **⋯** menu; published skills are copied without draft changes. Either way you land in the editor, where you write the skill yourself or draft it with the [Skill Builder](#draft-with-the-skill-builder). In the body of `SKILL.md`, lay out the procedure for the agent to follow. In the frontmatter, set: -- **Name**: the skill's unique ID, like `refund-requests`. The agent reads it and the description to decide when to use the skill. -- **Description**: the main factor in the agent's decision. Make it specific. -- **Display name**: the name you see and pick wherever the skill appears. Make it easy to recognize. +- **Display name**: the name shown at the top of the sidebar and anywhere the skill appears. Make it easy to recognize. +- **Name**: the unique name agents use to reference the skill, like `refund-requests`. +- **Description**: what the agent reads to decide whether to use the skill. Make it specific. - **Metadata**: custom fields for your own reference details, like `owner: payments-team` or `source: https://wiki.example.com/refund-policy`. Add any scripts, references, and other supporting files through the file tree. What you can do with each depends on its type: @@ -52,11 +52,11 @@ It accepts the following file types: | Image | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg` | | Text and data | `.txt`, `.md`, `.csv`, `.json`, `.yaml` | -Attach up to 10 files per message, up to 15 MB each, or 10 MB for an image. They are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. +Attach up to 10 files per message: images up to 10 MB and other files up to 15 MB. They are context for the Skill Builder, not part of the skill. To include a file, add it through the file tree. ## Import a Skill -To bring in a skill built elsewhere as a library skill, click **Import** and choose a `.zip` or `.skill` package. Make sure it has a `SKILL.md` inside. Once imported, it arrives as a draft for you to review and publish. +To bring in a skill built elsewhere as a library skill, click **Import** and choose a `.zip` or `.skill` package that contains a `SKILL.md` file. The package can be up to 50 MB by default; you can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. Once imported, it arrives as a draft for you to review and publish. ## Tag a Skill From e806e69c721a7132df67b959d83b9f879fc32213 Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 13 Aug 2026 11:14:36 +0800 Subject: [PATCH 18/20] docs: clarify skill package file limit --- en/self-host/deploy/configuration/environments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/self-host/deploy/configuration/environments.mdx b/en/self-host/deploy/configuration/environments.mdx index 8cd6a68ba..722b78f59 100644 --- a/en/self-host/deploy/configuration/environments.mdx +++ b/en/self-host/deploy/configuration/environments.mdx @@ -1405,7 +1405,7 @@ Default: `50` Maximum size in MB for a skill package (`.zip` or `.skill`), whether uploaded to an agent as an embedded skill or imported into the skill library. Larger packages are rejected with a size error. -A skill's unpacked content is separately capped at 200 MB and 5000 files, which this variable doesn't change. If you raise it above 100, also raise `NGINX_CLIENT_MAX_BODY_SIZE` to match; otherwise Nginx rejects the upload with a 413 error. +A skill's unpacked content is separately capped at 200 MB and 5000 files. For library imports, folders also count toward the 5000 limit. This variable doesn't change either limit. If you raise it above 100, also raise `NGINX_CLIENT_MAX_BODY_SIZE` to match; otherwise Nginx rejects the upload with a 413 error. ### AGENT_BACKEND_BASE_URL From 167647408cb8251d2cc6c930f7d8fdfc93c1b019 Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 13 Aug 2026 15:48:09 +0800 Subject: [PATCH 19/20] docs: standardize skill terminology --- tools/translate/termbase_i18n.md | 11 ++++++++++- writing-guides/glossary.md | 12 ++++++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/tools/translate/termbase_i18n.md b/tools/translate/termbase_i18n.md index c529cddba..9383da3ff 100644 --- a/tools/translate/termbase_i18n.md +++ b/tools/translate/termbase_i18n.md @@ -130,6 +130,15 @@ |:--------|:--------|:---------| | Max Iterations | 最大迭代次数 | 最大反復回数 | +### Skills + +| English | Chinese | Japanese | +|:--------|:--------|:---------| +| skill | Skill | スキル | +| skill library | Skill 库 | スキルライブラリ | +| embedded skill | 内嵌 Skill | 埋め込みスキル | +| Skill Builder | Skill Builder | Skill Builder | + ### Infrastructure | English | Chinese | Japanese | @@ -146,7 +155,6 @@ | runtime | 运行时 | ランタイム | | classic runtime | 经典运行时 | クラシックランタイム | | sandboxed runtime | 沙盒运行时 | サンドボックスランタイム | -| skill | 技能 | スキル | | file system | 文件系统 | ファイルシステム | ### Marketplace @@ -167,6 +175,7 @@ | Explore | 探索 | 探索 | | Integrations | 集成 | インテグレーション | | Tools | 工具 | ツール | +| Skills | Skills | Skills | ### App Detail Tabs diff --git a/writing-guides/glossary.md b/writing-guides/glossary.md index 8f959df50..ab1f8ba10 100644 --- a/writing-guides/glossary.md +++ b/writing-guides/glossary.md @@ -136,6 +136,15 @@ Terms appear in body text exactly as written in this table. Capitalize them furt |:--------|:--------|:---------|:------| | Max Iterations | 最大迭代次数 | 最大反復回数 | Limits the maximum number of reasoning loops and tool actions. The classic Agent app setting is a different string, "Maximum Iterations" (`app-debug.agent.setting.maximumIterations.name`). | +### Skills + +| English | Chinese | Japanese | Notes | +|:--------|:--------|:---------|:------| +| skill | Skill | スキル | Self-contained package of instructions and supporting files for one reusable task. Chinese keeps the product term in English; do not translate it as 技能. | +| skill library | Skill 库 | スキルライブラリ | Workspace-wide collection of shared skills. | +| embedded skill | 内嵌 Skill | 埋め込みスキル | Descriptive docs term for a skill that belongs to one agent and does not follow updates from the skill library. Not a UI label. | +| Skill Builder | Skill Builder | Skill Builder | Product feature and UI name; keep it in English in all languages. | + ### Infrastructure | English | Chinese | Japanese | Notes | @@ -152,7 +161,6 @@ Terms appear in body text exactly as written in this table. Capitalize them furt | runtime | 运行时 | ランタイム | The execution environment for workflow nodes | | classic runtime | 经典运行时 | クラシックランタイム | Original lightweight execution environment focused on speed and token efficiency | | sandboxed runtime | 沙盒运行时 | サンドボックスランタイム | Enhanced execution environment with file system access and autonomous tool installation | -| skill | 技能 | スキル | Reusable expertise packages that eliminate repetitive prompt writing (Sandboxed runtime) | | file system | 文件系统 | ファイルシステム | Sandboxed file access for reading/writing during execution | ### Marketplace @@ -175,6 +183,7 @@ Terms in this section must match the Dify product interface exactly. When these | Explore | 探索 | 探索 | common.menus.explore | Sidebar menu label | | Integrations | 集成 | インテグレーション | common.menus.plugins | Main nav label; the hub for model providers, tools, triggers, and other extensions. Renamed from "Plugins" in v1.15.0. JA main nav uses インテグレーション; docs use 統合 for consistency (see `settings.integrations`). | | Tools | 工具 | ツール | common.menus.tools | Sidebar menu label | +| Skills | Skills | Skills | skill.skillManagement.title | Main navigation label for the workspace skill library; currently stays English in all locales. | ### App Detail Tabs @@ -500,4 +509,3 @@ Terms in this section must match the Dify product interface exactly. When these | Chunking Setting | 分段模式 | チャンキングモード | dataset-documents.embedding.mode | Section heading | | High-quality mode | 高质量模式 | 高品質モード | dataset-documents.embedding.highQuality | | | Economy mode | 经济模式 | 経済モード | dataset-documents.embedding.economy | | - From 7d77122bee2839bde23571180b4477fbacad9063 Mon Sep 17 00:00:00 2001 From: yajing Date: Thu, 13 Aug 2026 19:00:51 +0800 Subject: [PATCH 20/20] translate: sync skill management docs --- docs.json | 2 + .../use-dify/build/new-agent/build.mdx | 6 +- .../deploy/configuration/environments.mdx | 12 ++- .../use-dify/build/new-agent/build.mdx | 30 ++++--- ja/self-host/use-dify/build/skills.mdx | 87 +++++++++++++++++++ tools/translate/termbase_i18n.md | 25 +++++- .../deploy/configuration/environments.mdx | 8 ++ .../use-dify/build/new-agent/build.mdx | 18 ++-- zh/self-host/use-dify/build/skills.mdx | 81 +++++++++++++++++ 9 files changed, 246 insertions(+), 23 deletions(-) create mode 100644 ja/self-host/use-dify/build/skills.mdx create mode 100644 zh/self-host/use-dify/build/skills.mdx diff --git a/docs.json b/docs.json index 9c55892f2..f45acf01c 100644 --- a/docs.json +++ b/docs.json @@ -2221,6 +2221,7 @@ ], "expanded": false }, + "zh/self-host/use-dify/build/skills", { "group": "基础应用", "pages": [ @@ -3613,6 +3614,7 @@ ], "expanded": false }, + "ja/self-host/use-dify/build/skills", { "group": "基本アプリ", "pages": [ diff --git a/en/self-host/use-dify/build/new-agent/build.mdx b/en/self-host/use-dify/build/new-agent/build.mdx index 0e97376d0..75ab600e1 100644 --- a/en/self-host/use-dify/build/new-agent/build.mdx +++ b/en/self-host/use-dify/build/new-agent/build.mdx @@ -62,13 +62,13 @@ For example, a support agent's prompt might set its role as a customer helper th Click **Add** and choose where the skill comes from: -- Choose **From skill library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide. You can add up to 20 library skills to an agent, and it follows the latest published version of each. -- Choose **Upload package** to add a `.zip` or `.skill` package as an *embedded skill*, one the agent keeps to itself. The package can be up to 50 MB by default; you can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). +- Choose **Add from library** to add a [*library skill*](/en/self-host/use-dify/build/skills) shared workspace-wide. You can add up to 20 library skills to an agent, and it follows the latest published version of each. +- Choose **Upload skill.zip** to add a `.zip` or `.skill` package as an *embedded skill*, one the agent keeps to itself. The package can be up to 50 MB by default; you can change this limit with the [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit) environment variable. To share it with other agents, [make it a library skill](/en/self-host/use-dify/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). -Referencing a Dify tool, file, or knowledge base in a skill doesn't use it. To use one, add it to the agent. +To use a Dify tool, file, or knowledge base, add it directly to the agent rather than referencing it in a skill. ### Files diff --git a/ja/self-host/deploy/configuration/environments.mdx b/ja/self-host/deploy/configuration/environments.mdx index 2c7cabff6..d9eb14deb 100644 --- a/ja/self-host/deploy/configuration/environments.mdx +++ b/ja/self-host/deploy/configuration/environments.mdx @@ -1391,6 +1391,14 @@ Dify API が Agent バックエンドの実行 API を呼び出す際に提示 新しい Agent を Web UI に表示します。メインナビゲーションの **Agents** 項目と、ワークフローのノード一覧の新しい Agent ノードです。`false` にすると非表示になり、クラシック Agent ノードにフォールバックします。`ENABLE_AGENT_V2` を置き換えるもので、こちらは引き続きフォールバックとして機能します。 +### UPLOAD_SKILL_FILE_SIZE_LIMIT + +デフォルト値：`50` + +スキルパッケージ（`.zip` または `.skill`）の最大サイズを MB 単位で指定します。Agent に埋め込みスキルとしてアップロードする場合と、スキルライブラリへインポートする場合の両方に適用されます。上限を超えるパッケージはサイズエラーで拒否されます。 + +展開後の内容には、200 MB と 5000 ファイルという別の上限があります。スキルライブラリへインポートする場合、フォルダーも 5000 件の上限に含まれます。この環境変数では、どちらの上限も変更できません。100 より大きくする場合は、`NGINX_CLIENT_MAX_BODY_SIZE` も同じ値以上に設定してください。設定しないと、Nginx が 413 エラーでアップロードを拒否します。 + ### AGENT_BACKEND_BASE_URL デフォルト値：`http://agent_backend:5050` @@ -1493,7 +1501,7 @@ HTTPS を有効化した後、 [共通変数](#共通変数) の URL 変数（ | 変数 | デフォルト値 | 説明 | |---|---|---| -| `COMPOSE_PROFILES` | `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration` | 起動するサービスコンテナを選択します。デフォルトでは、対応するベクトルストアとデータベース（`DB_TYPE=mysql` を設定すれば PostgreSQL の代わりに MySQL が起動）、および専用の `api_websocket` コンテナを起動する `collaboration` プロファイルが含まれます。`collaboration` を削除すると、独立した WebSocket サービスを起動しません。 | +| `COMPOSE_PROFILES` | `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration` | 起動するサービスコンテナを選びます。デフォルトでは、ベクトルストア、データベース、`collaboration` プロファイルを起動します。`DB_TYPE=mysql` なら MySQL を使います。`collaboration` を削除すると、`api_websocket` コンテナを起動しません。 | | `EXPOSE_NGINX_PORT` | `80` | Nginx HTTP にマッピングされるホストポート。 | | `EXPOSE_NGINX_SSL_PORT` | `443` | Nginx HTTPS にマッピングされるホストポート。 | @@ -1821,4 +1829,4 @@ API と Celery ワーカー間の Redis ベースのイベント転送です。 | `PLUGIN_VOLCENGINE_TOS_REGION` | （空） | Volcengine TOS リージョン。 | - \ No newline at end of file + diff --git a/ja/self-host/use-dify/build/new-agent/build.mdx b/ja/self-host/use-dify/build/new-agent/build.mdx index 162e9c51c..05e47fcef 100644 --- a/ja/self-host/use-dify/build/new-agent/build.mdx +++ b/ja/self-host/use-dify/build/new-agent/build.mdx @@ -51,21 +51,29 @@ Agent の出来はモデルしだいで大きく変わります。できるだ - **ツールとファイルの使い方**：それぞれを使う場面（名前を挙げて明示）。 - **出力**：望む形式、長さ、トーン。 -特定のスキル、ファイル、ツール、ナレッジソースを Agent に指定することも、どれを使うかを Agent に任せることもできます： +特定のスキル、ファイル、ツール、ナレッジベースを Agent に指定することも、どれを使うかを Agent に任せることもできます： - **プロンプト内で参照する**：`/` で参照を挿入すると、使ってほしいまさにその箇所で、Agent をその対象へ直接導けます。特定のステップが特定の対象に依存する場合に向いています。 - - **セクションに追加するだけ**：いつ使うかは Agent 自身に判断させます。一手一手を指示するより、Agent の判断を信頼したい場合に向いています。 ### スキル -「スキル」は、Agent 向けにパッケージ化する自己完結型の手順書です。1 つの専門タスクのための指示、参考資料、スクリプトをひとまとめにし、一度定義すれば繰り返し使えます。 +スキルは、Agent が特定のタスクで従う手順です。プロンプトが Agent の全体的なロールを定めるのに対し、スキルはそのタスクだけを扱います。 + +たとえば、サポート担当の Agent では、プロンプトであらゆる問い合わせに対応する役割を設定できます。`refund-requests` スキルでは、返金だけを扱います。注文を確認し、30 日以内に限って返金し、最後にヘルプセンターへのリンクを案内します。 + +**追加** をクリックし、スキルの追加元を選択します： -プロンプトが Agent の全体的なロールを定めるのに対し、スキルは特定のタスクで必要になったときだけ取り出す作業手順、いわば有能な人材に渡す SOP です。Agent 側は汎用的な能力を、スキル側はその仕事専用の手順、資料、ツールを持ち寄ることで、期待どおりの成果につながります。 +- **From skill library** を選択すると、ワークスペース全体で共有する [スキルライブラリのスキル](/ja/self-host/use-dify/build/skills) を追加できます。1 つの Agent に最大 20 個追加でき、それぞれの最新公開バージョンが反映されます。 +- **Upload package** を選択すると、`.zip` または `.skill` パッケージを埋め込みスキルとして追加できます。埋め込みスキルは、その Agent だけが使用します。パッケージの上限はデフォルトで 50 MB です。 + [`UPLOAD_SKILL_FILE_SIZE_LIMIT`][upload-skill-file-size-limit] 環境変数で変更できます。 + ほかの Agent と共有するには、[スキルライブラリに追加](/ja/self-host/use-dify/build/skills#スキルのインポート) してください。 -たとえば `marketing-copy` というスキルにスタイルガイド、ブランド素材、チェックリストをまとめておけば、毎回説明し直す必要がなくなります。 +[ビルドモード](#チャットによるビルド) では、Agent に埋め込みスキルを作成させることもできます。 -スキルパッケージは、50 MB 以内の `.zip` または `.skill` ファイルで、`SKILL.md` が入っている必要があります。フォーマットの詳細や作成方法は、[Agent Skills](https://agentskills.io/home) を参照してください。[ビルドモード](#チャットによるビルド) で Agent にスキルを作成させることもできます。 + +ツール、ファイル、ナレッジベースを使うには、スキル内で参照するのではなく、Agent に直接追加してください。 + ### ファイル @@ -90,10 +98,10 @@ Agent の出来はモデルしだいで大きく変わります。できるだ ### ツール -[Dify ツール](/ja/self-host/use-dify/workspace/tools) を持たせると、Agent はチャットの外でも行動できるようになります。ワークスペースにあるプラグイン、カスタム API、ワークフロー、MCP サーバーを利用できます。一部のツールは使用前に認証が必要です。 +[ツール](/ja/self-host/use-dify/workspace/tools) を持たせると、Agent はチャットの外でも行動できるようになります。ワークスペースにあるプラグイン、カスタム API、ワークフロー、MCP サーバーを利用できます。一部のツールは使用前に認証が必要です。 -ここで追加する Dify ツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインプログラムをインストールして実行できます。 +ここで追加するツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインプログラムをインストールして実行できます。 こうしたプログラムは「ツール」のリストに表示されません。また、作業ディレクトリ内のファイルと異なり、一度インストールすれば以後のタスクでも使えます。 @@ -182,7 +190,7 @@ Agent は作業しながら、設定した内容を「ビルドノート」（`b - 記録をいちからやり直したい場合は、**ファイル** でノートを削除します。 -ビルドチャットをまたいで、このノートは Agent の記憶のような役割も果たします。たとえば、あるチャットで議事録 Agent の形式を決めておけば、後日アクションアイテムの担当者を追加するチャットは、決めた形式や方針を引き継いだ状態から始まります。 +このノートは、ビルドチャットをまたいで Agent の記憶のように機能します。たとえば、あるチャットで議事録 Agent の形式を決めたとします。後日、アクションアイテムの担当者を追加するチャットを始めると、決めた形式や方針が引き継がれます。 ## 公開 @@ -192,7 +200,7 @@ Agent は作業しながら、設定した内容を「ビルドノート」（`b バージョンを復元しても、巻き戻るのは Agent の設定だけです。サンドボックス環境にはバージョン管理がなく、インストールしたツールなどの環境への変更はそのまま残ります。 -**アクセスポイント** タブでは、共有可能なリンクで Web アプリとして公開したり、自分のサイトに埋め込んだり、サービス API 経由でコードから呼び出したりできます。 +**アクセスポイント** タブでは、共有リンクを使って Web アプリとして公開できます。自分のサイトへの埋め込みや、サービス API 経由でのコードからの呼び出しもできます。 **データセキュリティに関する注意** @@ -211,3 +219,5 @@ Agent の API はストリーミングにのみ対応しています。API ア 公開後は、**ログ** で会話を、**モニタリング** で使用状況、品質、速度、コストを確認できます。 Agent をワークスペース間で共有するには、DSL ファイルとしてエクスポートします。エクスポートされるファイルにスキルとファイルは含まれません。 + +[upload-skill-file-size-limit]: /ja/self-host/deploy/configuration/environments#upload_skill_file_size_limit diff --git a/ja/self-host/use-dify/build/skills.mdx b/ja/self-host/use-dify/build/skills.mdx new file mode 100644 index 000000000..b36b0c9ca --- /dev/null +++ b/ja/self-host/use-dify/build/skills.mdx @@ -0,0 +1,87 @@ +--- +title: Skills +sidebarTitle: Skills +description: 1 つのタスクと関連ファイルを再利用可能なスキルにまとめ、ワークスペース全体で共有 +--- + +> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/build/skills) を参照してください。 + +スキルは一度作成すれば繰り返し使える、自己完結型のパッケージです。`SKILL.md` には、1 つのタスクの手順と Agent がそのスキルを使うタイミングを記述します。タスクに必要な参考資料やスクリプトも含められます。完全な形式は [Agent Skills](https://agentskills.io/home) を参照してください。 + +スキルライブラリには最大 500 個のスキルを保存し、ワークスペース全体で共有できます。スキルの更新を公開すると、そのスキルを利用するすべての Agent に最新バージョンが反映されます。 + +スキルは次の場所で利用できます： + +- [新しい Agent アプリ](/ja/self-host/use-dify/build/new-agent/build#スキル) +- [Workflow アプリ](/ja/self-host/use-dify/build/workflow-chatflow) 内の [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent) + +**Skills** ページで、スキルライブラリのスキルを作成、インポート、管理します。 + + +スキルの作成と管理には、エディター以上のロールが必要です。 + + +## スキルの作成 + +**Skills** で **Create** をクリックします。既存のスキルを複製して始めるには、そのスキルの **⋯** メニューから **複製** を選択します。公開済みのスキルを複製しても、ドラフトの変更は含まれません。どちらの方法でもエディターが開きます。自分で書くことも、[Skill Builder](#skill-builder-による下書き) で下書きを作ることもできます。 + +`SKILL.md` の本文には、Agent が従う手順を書きます。frontmatter では次の項目を設定します： + +- **表示名**：スキルがサイドバー上部や各所に表示されるときの名前です。見分けやすい名前にします。 +- **名前**：Agent がスキルを参照するための一意の名前です。例：`refund-requests`。 +- **説明**：Agent がそのスキルを使うか判断するために読みます。具体的に記述します。 +- **メタデータ**：参考情報を記録するためのカスタムフィールドです。例：`owner: payments-team`、`source: https://wiki.example.com/refund-policy`。 + +ファイルツリーから、スクリプト、参考資料、その他の関連ファイルを追加します。ファイルの種類によって操作が異なります： + +- **テキストとコード**（Markdown、スクリプト、JSON、YAML、CSV など）：その場で編集できます。 +- **画像と PDF**：その場でプレビューできます。 +- **その他のファイル**：ダウンロードして確認します。 + +### Skill Builder による下書き + +Skill Builder とチャットすると、スキルの下書きを作成できます。シナリオを説明するか、既存の手順書を添付してください。Skill Builder が `SKILL.md` を記述し、確認や修正に使える関連ファイルも作成します。 + +次のファイル形式に対応しています： + +| 種類 | 例 | +|:-----|:---| +| PDF | `.pdf` | +| Word | `.doc`、`.docx` | +| Excel | `.xls`、`.xlsx` | +| PowerPoint | `.ppt`、`.pptx` | +| RTF | `.rtf` | +| 画像 | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.svg` | +| テキストとデータ | `.txt`、`.md`、`.csv`、`.json`、`.yaml` | + +1 回のメッセージに最大 10 個のファイルを添付できます。画像は 10 MB、その他のファイルは 15 MB までです。添付ファイルは Skill Builder のコンテキストとして使われ、スキルには含まれません。スキルに含めるファイルは、ファイルツリーから追加します。 + +## スキルのインポート + +ほかで作成したスキルをスキルライブラリに取り込むには、**Import** をクリックします。`SKILL.md` を含む `.zip` または `.skill` パッケージを選択してください。 + +パッケージの上限はデフォルトで 50 MB です。 +[`UPLOAD_SKILL_FILE_SIZE_LIMIT`][upload-skill-file-size-limit] 環境変数で変更できます。 +インポートすると、確認して公開できるドラフトとして追加されます。 + +## スキルへのタグ付け + +スキルのカードまたはエディターでタグを追加し、タグでスキルを絞り込みます。 + +## 公開とバージョン + +編集内容はドラフトとして自動保存されます。Agent に追加するには、ドラフトを公開してください。公開するたびにバージョンが保存され、後から確認したり復元したりできます。変更内容を記録するには、**⋯** メニューの **Edit version info** でタイトルとメモを入力します。 + + +バージョンを復元すると、現在のドラフトが置き換わります。そのドラフトを公開すると、最新バージョンになります。 + + +## スキルのエクスポート + +ワークスペース外でスキルを使うには、カードの **⋯** メニューから **エクスポート** を選択します。最新の公開バージョンが `.zip` ファイルとして出力されます。 + +## スキルの削除 + +スキルを削除すると、すべてのバージョンとともにワークスペースから削除されます。そのスキルを使うすべての Agent からも削除されます。削除したスキルは復元できません。後で必要になる可能性があれば、先にコピーをエクスポートしてください。 + +[upload-skill-file-size-limit]: /ja/self-host/deploy/configuration/environments#upload_skill_file_size_limit diff --git a/tools/translate/termbase_i18n.md b/tools/translate/termbase_i18n.md index 9383da3ff..343a5e3b9 100644 --- a/tools/translate/termbase_i18n.md +++ b/tools/translate/termbase_i18n.md @@ -182,11 +182,22 @@ | English | Chinese | Japanese | |:--------|:--------|:---------| | Orchestrate | 编排 | オーケストレート | +| Access Point | 访问点 | アクセスポイント | | Monitoring | 监测 | 監視 | -| API Access | 访问 API | API アクセス | | Logs | 日志 | ログ | | Annotations | 标注 | 注釈 | +### Access Point Channel Cards + +| English | Chinese | Japanese | +|:--------|:--------|:---------| +| Web App | Web 应用 | Web アプリ | +| Backend Service API | 后端服务 API | バックエンドサービス API | +| API Endpoint | API Endpoint | API エンドポイント | +| API Key | API 密钥 | API キー | +| MCP Server | MCP 服务 | MCP サーバー | +| Trigger | 触发器 | トリガー | + ### Log Page | English | Chinese | Japanese | @@ -203,6 +214,7 @@ | English | Chinese | Japanese | |:--------|:--------|:---------| | Documents | 文档 | ドキュメント | +| API Access | 访问 API | API アクセス | | Retrieval Testing | 召回测试 | 検索テスト | | Settings | 设置 | 設定 | | Pipeline | 流水线 | パイプライン | @@ -325,14 +337,23 @@ | English | Chinese | Japanese | |:--------|:--------|:---------| | Publish | 发布 | 公開する | +| Publish Update | 发布更新 | 更新を公開 | | Published | 已发布 | 公開済み | | Unpublished | 未发布 | 未公開 | +| Not published yet | 尚未发布 | まだ公開されていません | +| No changes | 无更改 | 変更なし | +| Unpublished changes | 有未发布的更改 | 未公開の変更 | +| Up to date | 已是最新 | 最新です | +| Open web app | 打开 Web 应用 | Web アプリを開く | | Preview | 预览 | プレビュー | | Test Run | 测试运行 | テスト実行 | -| Run App | 运行 | アプリを実行 | | Features | 功能 | 機能 | | Version History | 版本历史 | バージョン履歴 | | Workflow as Tool | 发布为工具 | ワークフローをツールとして公開する | +| Needs Setup | 需要进行配置 | 設定が必要 | +| Ready | 已就绪 | 準備完了 | +| Update Needed | 需要更新 | 更新が必要 | +| Reconfigure | 重新配置 | 再設定 | | Embed Into Site | 嵌入网站 | サイトに埋め込む | | Conversation Variables | 会话变量 | 会話変数 | | Environment Variables | 环境变量 | 環境変数 | diff --git a/zh/self-host/deploy/configuration/environments.mdx b/zh/self-host/deploy/configuration/environments.mdx index 2066ecdcc..2c2dbf07d 100644 --- a/zh/self-host/deploy/configuration/environments.mdx +++ b/zh/self-host/deploy/configuration/environments.mdx @@ -1395,6 +1395,14 @@ Dify API 调用 Agent 后端运行接口时出示的 Bearer 令牌。Compose 会 设为 `false` 可隐藏它并回退到经典 Agent 节点。此变量替代了 `ENABLE_AGENT_V2`，后者仍可作为回退。 +### UPLOAD_SKILL_FILE_SIZE_LIMIT + +默认值：`50` + +Skill 包（`.zip` 或 `.skill`）的最大大小，单位为 MB。无论将包作为内嵌 Skill 上传到 Agent，还是导入 Skill 库，都受此限制。超过限制时会返回大小错误。 + +Skill 解压后的内容另有两项上限：200 MB 和 5000 个文件；导入 Skill 库时，文件夹也计入 5000 个条目。此变量不会改变这两项限制。若将其提高到 100 以上，还需同步提高 `NGINX_CLIENT_MAX_BODY_SIZE`，否则 Nginx 会以 413 错误拒绝上传。 + ### AGENT_BACKEND_BASE_URL 默认值：`http://agent_backend:5050` diff --git a/zh/self-host/use-dify/build/new-agent/build.mdx b/zh/self-host/use-dify/build/new-agent/build.mdx index d6703811b..7c08f3eb1 100644 --- a/zh/self-host/use-dify/build/new-agent/build.mdx +++ b/zh/self-host/use-dify/build/new-agent/build.mdx @@ -51,21 +51,27 @@ Agent 表现好不好，很大程度取决于模型，尽量选较新的模型 - **工具与文件的使用**：点名说明各自何时使用。 - **输出**：期望的格式、长度或语气。 -你可将 Agent 指向特定的 Skill、文件、工具或知识源，也可把选择权留给它： +你可将 Agent 指向特定的 Skill、文件、工具或知识库，也可把选择权留给它： - **在提示词中引用**：输入 `/` 引用，Agent 会在你指定的位置直接用上它。适合某个步骤依赖特定资源的场景。 - - **只添加不引用**：把它加到对应区域，何时使用由 Agent 自行决定。适合你更愿意相信 Agent 的判断、不想事事写死的场景。 ### Skill -Skill 是你为 Agent 打包的一套完整流程：把某项专门任务所需的指令、参考材料和脚本捆绑在一起，定义一次即可反复使用。 +Skill 是 Agent 针对某项特定任务遵循的一套流程。提示词设定 Agent 的整体角色，而 Skill 只负责这一项任务。 + +例如，客服 Agent 的提示词可把它设定为处理各类问题的客服助手，而 `refund-requests` Skill 只处理退款：查询订单、仅处理 30 天内的退款，并在最后提供帮助中心链接。 + +点击 **添加**，再选择 Skill 的来源： -提示词设定的是 Agent 的整体角色，而 Skill 是它只在特定任务需要时才取用的作业指南，就像交给能干员工的一份 SOP。Agent 自带通用能力，Skill 则为这项工作提供你规定的确切步骤、材料和工具，让产出符合你的预期。 +- 选择 **从 Skill 库添加**，添加工作空间内共享的 [Skill 库中的 Skill](/zh/self-host/use-dify/build/skills)。每个 Agent 最多可添加 20 个此类 Skill，并会采用各 Skill 的最新发布版本。 +- 选择 **上传 skill.zip**，将 `.zip` 或 `.skill` 包作为内嵌 Skill 添加到 Agent。内嵌 Skill 只属于该 Agent。包大小默认不超过 50 MB；可通过 [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/zh/self-host/deploy/configuration/environments#upload_skill_file_size_limit) 环境变量调整。要与其他 Agent 共享，[将它加入 Skill 库](/zh/self-host/use-dify/build/skills#导入-skill)。 -例如，一个 `marketing-copy` Skill 可打包你的风格指南、品牌素材和检查清单，省得每次重新解释。 +你也可在 [构建模式](#通过对话构建) 中让 Agent 替你创建内嵌 Skill。 -Skill 包只能是 `.zip` 或 `.skill` 文件，不超过 50 MB，且包内要有 `SKILL.md`。关于包格式和构建方法，参见 [Agent Skills](https://agentskills.io/home)。你也可在 [构建模式](#通过对话构建) 中让 Agent 替你创建 Skill。 + +要使用 Dify 工具、文件或知识库，请将其直接添加到 Agent，而不要只在 Skill 中引用。 + ### 文件 diff --git a/zh/self-host/use-dify/build/skills.mdx b/zh/self-host/use-dify/build/skills.mdx new file mode 100644 index 000000000..a2afd2cdf --- /dev/null +++ b/zh/self-host/use-dify/build/skills.mdx @@ -0,0 +1,81 @@ +--- +title: Skills +sidebarTitle: Skills +description: 将单项任务及其配套文件打包为可复用的 Skill，并在工作空间内共享 +--- + +> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/build/skills)。 + +Skill 是一次构建、重复使用的独立内容包。其中的 `SKILL.md` 包含一项任务的执行说明，并告诉 Agent 何时使用；还可加入该任务所需的参考资料和脚本。完整格式参见 [Agent Skills](https://agentskills.io/home)。 + +Skill 库最多可保存 500 个 Skill，并在整个工作空间内共享。发布 Skill 更新后，所有使用它的 Agent 都会采用最新版本。 + +Skill 可用于： + +- [新 Agent 应用](/zh/self-host/use-dify/build/new-agent/build#skill) +- [Workflow 应用](/zh/self-host/use-dify/build/workflow-chatflow) 中的 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent) + +在 **Skills** 页面创建、导入和管理 Skill 库中的 Skill。 + + +创建和管理 Skill 需要编辑及以上角色。 + + +## 创建 Skill + +在 **Skills** 页面点击 **创建**。如需以现有 Skill 为起点，在其 **⋯** 菜单中选择 **复制**；复制已发布的 Skill 时，不包含草稿中的更改。无论采用哪种方式，系统都会打开编辑器，你可自行编写，也可通过 [Skill Builder](#使用-skill-builder-起草) 生成草稿。 + +在 `SKILL.md` 正文中写明 Agent 要遵循的流程，并在 frontmatter 中设置： + +- **显示名称**：显示在侧边栏顶部以及 Skill 出现的各处。使用容易辨认的名称。 +- **名称**：Agent 引用 Skill 时使用的唯一名称，例如 `refund-requests`。 +- **描述**：Agent 通过它判断是否使用该 Skill。描述要具体。 +- **元数据**：用于记录其他参考信息的自定义字段，例如 `owner: payments-team` 或 `source: https://wiki.example.com/refund-policy`。 + +通过文件树添加脚本、参考资料和其他配套文件。不同文件类型支持的操作如下： + +- **文本和代码**（Markdown、脚本、JSON、YAML、CSV 等）：直接编辑。 +- **图片和 PDF**：直接预览。 +- **其他文件**：下载后查看。 + +### 使用 Skill Builder 起草 + +与 Skill Builder 对话，让它为你起草 Skill。描述使用场景或附上已有的流程文档，它会编写 `SKILL.md` 并创建配套文件，供你检查和完善。 + +支持以下文件类型： + +| 类型 | 示例 | +|:-----|:-----| +| PDF | `.pdf` | +| Word | `.doc`、`.docx` | +| Excel | `.xls`、`.xlsx` | +| PowerPoint | `.ppt`、`.pptx` | +| RTF | `.rtf` | +| 图片 | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.svg` | +| 文本和数据 | `.txt`、`.md`、`.csv`、`.json`、`.yaml` | + +每条消息最多附加 10 个文件：图片不超过 10 MB，其他文件不超过 15 MB。这些文件只为 Skill Builder 提供上下文，不会成为 Skill 的一部分。要将文件加入 Skill，请通过文件树添加。 + +## 导入 Skill + +要把在其他地方构建的 Skill 加入 Skill 库，点击 **导入**，选择包含 `SKILL.md` 的 `.zip` 或 `.skill` 包。包大小默认不超过 50 MB；可通过 [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/zh/self-host/deploy/configuration/environments#upload_skill_file_size_limit) 环境变量调整。导入后，Skill 会以草稿状态加入 Skill 库，供你检查并发布。 + +## 为 Skill 添加标签 + +在 Skill 卡片或编辑器中添加标签，再按标签筛选 Skill。 + +## 发布和版本 + +更改会自动保存为草稿。发布草稿后，才能将 Skill 添加到 Agent。每次发布都会保存为一个版本，之后可重新查看或恢复。要记录版本变化，在其 **⋯** 菜单中选择 **编辑版本信息**，填写标题和说明。 + + +恢复版本会替换当前草稿。发布该草稿后，它才会成为最新版本。 + + +## 导出 Skill + +要在当前工作空间之外使用 Skill，在其卡片的 **⋯** 菜单中选择 **导出**。你会获得 Skill 最新发布版本的 `.zip` 文件。 + +## 删除 Skill + +删除 Skill 会将它及其全部版本从工作空间和所有使用它的 Agent 中移除。删除后无法恢复；如之后可能还会用到，请先导出副本。