docs: add skills overview and skill library guides

docs.json

@@ -828,6 +828,7 @@
                         ],
                         "expanded": false
                       },
+                      "en/self-host/use-dify/build/skills",
                       {
                         "group": "Basic Apps",
                         "pages": [
@@ -2220,6 +2221,7 @@
                         ],
                         "expanded": false
                       },
+                      "zh/self-host/use-dify/build/skills",
                       {
                         "group": "基础应用",
                         "pages": [
@@ -3612,6 +3614,7 @@
                         ],
                         "expanded": false
                       },
+                      "ja/self-host/use-dify/build/skills",
                       {
                         "group": "基本アプリ",
                         "pages": [

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`), 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. 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
 
 Default: `http://agent_backend:5050`

en/self-host/use-dify/build/new-agent/build.mdx

@@ -49,21 +49,27 @@ 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.
 
 ### 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.
+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 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:
 
-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.
+- 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).
 
-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.
+You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting).
 
-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).
+<Note>
+To use a Dify tool, file, or knowledge base, add it directly to the agent rather than referencing it in a skill.
+</Note>
 
 ### Files
 

en/self-host/use-dify/build/skills.mdx

@@ -0,0 +1,79 @@
+---
+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 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 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:
+
+- 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.
+
+<Info>
+Creating and managing skills requires the Editor role or above.
+</Info>
+
+## Create a Skill
+
+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:
+
+- **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:
+
+- **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.
+
+### 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.
+
+It accepts the following file types:
+
+| Type | Examples |
+|:-----|:---------|
+| PDF | `.pdf` |
+| Word | `.doc`, `.docx` |
+| 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 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 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
+
+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. To record what a version changed, give it a title and note with **Edit version info** in its **⋯** menu.
+
+<Note>
+Restoring a version replaces your current draft. Publish the draft to make it the newest version.
+</Note>
+
+## 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.

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 リージョン。 |
 
 </Accordion>
-</AccordionGroup>
+</AccordionGroup>

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 にスキルを作成させることもできます。
+<Note>
+ツール、ファイル、ナレッジベースを使うには、スキル内で参照するのではなく、Agent に直接追加してください。
+</Note>
 
 ### ファイル
 
@@ -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 サーバーを利用できます。一部のツールは使用前に認証が必要です。
 
 <Tip>
-ここで追加する Dify ツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインプログラムをインストールして実行できます。
+ここで追加するツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインプログラムをインストールして実行できます。
 
 こうしたプログラムは「ツール」のリストに表示されません。また、作業ディレクトリ内のファイルと異なり、一度インストールすれば以後のタスクでも使えます。
 </Tip>
@@ -182,7 +190,7 @@ Agent は作業しながら、設定した内容を「ビルドノート」（`b
 
 - 記録をいちからやり直したい場合は、**ファイル** でノートを削除します。
 
-ビルドチャットをまたいで、このノートは Agent の記憶のような役割も果たします。たとえば、あるチャットで議事録 Agent の形式を決めておけば、後日アクションアイテムの担当者を追加するチャットは、決めた形式や方針を引き継いだ状態から始まります。
+このノートは、ビルドチャットをまたいで Agent の記憶のように機能します。たとえば、あるチャットで議事録 Agent の形式を決めたとします。後日、アクションアイテムの担当者を追加するチャットを始めると、決めた形式や方針が引き継がれます。
 
 ## 公開
 
@@ -192,7 +200,7 @@ Agent は作業しながら、設定した内容を「ビルドノート」（`b
 バージョンを復元しても、巻き戻るのは Agent の設定だけです。サンドボックス環境にはバージョン管理がなく、インストールしたツールなどの環境への変更はそのまま残ります。
 </Note>
 
-**アクセスポイント** タブでは、共有可能なリンクで Web アプリとして公開したり、自分のサイトに埋め込んだり、サービス API 経由でコードから呼び出したりできます。
+**アクセスポイント** タブでは、共有リンクを使って Web アプリとして公開できます。自分のサイトへの埋め込みや、サービス API 経由でのコードからの呼び出しもできます。
 
 <Warning>
 **データセキュリティに関する注意**
@@ -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