feat: add support for Anthropic Skills and environment variable loading for API keys

Soulter · Soulter · commit 675731a9c715 · 2026-01-29T00:44:46.000+08:00
diff --git a/en/config/providers/start.md b/en/config/providers/start.md
@@ -17,4 +17,10 @@ Using DeepSeek as an example, assuming you have registered and logged in to a De
 4. On the API documentation page, find the section about the "OpenAI-compatible interface" and note the API Base URL, for example `https://api.deepseek.com/v1`. (If there is no `/v1`, please add `/v1`.)
 5. Open the AstrBot Console -> Service Providers page, click Add Provider, find and click `OpenAI` (if the provider type you want to connect is listed, prefer clicking that type; for some providers like DeepSeek we provide optimized adapter support). Paste the API Key into the `API Key` field of the form and paste the API Base URL into the `API Base URL` field.
 6. Click Get Model List, find the model you want to use, click the + button on the right, then toggle the switch that appears on the right to enable it.
-7. Go to the Configuration page, find the conversational model, click the selection button on the right, choose the provider and model you just added, then click the Save Configuration button at the bottom-right of the screen.
+7. Go to the Configuration page, find the conversational model, click the selection button on the right, choose the provider and model you just added, then click the Save Configuration button at the bottom-right of the screen.
+
+## Using Environment Variables to Load Keys
+
+> v4.13.0 之后引入
+
+Supports using environment variables to load the API Key of model service providers. On the provider configuration page, fill in the API Key field with the name `$ENV_VARIABLE_NAME`, for example, `$DEESEEK_API_KEY`.
diff --git a/en/dev/star/guides/plugin-config.md b/en/dev/star/guides/plugin-config.md
@@ -43,7 +43,7 @@ The file content is a `Schema` that represents the configuration. The Schema is
 }
 ```
 
-- `type`: **Required**. The type of the configuration. Supports `string`, `text`, `int`, `float`, `bool`, `object`, `list`. When the type is `text`, it will be visualized as a larger resizable textarea component to accommodate large text.
+- `type`: **Required**. The type of the configuration. Supports `string`, `text`, `int`, `float`, `bool`, `object`, `list`, `dict`, `template_list`, `file`. When the type is `text`, it will be visualized as a larger resizable textarea component to accommodate large text.
 - `description`: Optional. Description of the configuration. A one-sentence description of the configuration's behavior is recommended.
 - `hint`: Optional. Hint information for the configuration, displayed in the question mark button on the right in the image above, shown when hovering over it.
 - `obvious_hint`: Optional. Whether the configuration hint should be prominently displayed, like `token` in the image above.
@@ -64,7 +64,130 @@ When the code editor is enabled, it looks like this:
 
 The **_special** field is only available after v4.0.0. Currently supports `select_provider`, `select_provider_tts`, `select_provider_stt`, `select_persona`, allowing users to quickly select model providers, personas, and other data already configured in the WebUI. Results are all strings. Using select_provider as an example, it will present the following effect:
 
-![image](/source/images/plugin/image.png)
+![image](/source/images/plugin/image-select-provider.png)
+
+### `file` type schema
+
+Introduced in v4.13.0, this allows plugins to define file-upload configuration items to guide users to upload files required by the plugin.
+
+```json
+{
+  "demo_files": {
+    "type": "file",
+    "description": "Uploaded files for demo",
+    "default": [],
+    "file_types": ["pdf", "docx"]
+  }
+}
+```
+
+### `dict` type schema
+
+Used to visualize editing a Python `dict` type configuration. For example, AstrBot Core's custom extra body parameter configuration:
+
+```py
+"custom_extra_body": {
+  "description": "Custom request body parameters",
+  "type": "dict",
+  "items": {},
+  "hint": "Used to add extra parameters to requests, such as temperature, top_p, max_tokens, etc.",
+  "template_schema": {
+      "temperature": {
+          "name": "Temperature",
+          "description": "Temperature parameter",
+          "hint": "Controls randomness of output, typically 0-2. Higher is more random.",
+          "type": "float",
+          "default": 0.6,
+          "slider": {"min": 0, "max": 2, "step": 0.1},
+      },
+      "top_p": {
+          "name": "Top-p",
+          "description": "Top-p sampling",
+          "hint": "Nucleus sampling parameter, typically 0-1. Controls probability mass considered.",
+          "type": "float",
+          "default": 1.0,
+          "slider": {"min": 0, "max": 1, "step": 0.01},
+      },
+      "max_tokens": {
+          "name": "Max Tokens",
+          "description": "Maximum tokens",
+          "hint": "Maximum number of tokens to generate.",
+          "type": "int",
+          "default": 8192,
+      },
+  },
+}
+```
+
+### `template_list` type schema
+
+> [!NOTE]
+> Introduced in v4.10.4. For more details see: [#4208](https://github.com/AstrBotDevs/AstrBot/pull/4208)
+
+Plugin developers can add a template-style configuration to `_conf_schema` in the following format (somewhat similar to nested configs):
+
+```json
+ "field_id": {
+  "type": "template_list",
+  "description": "Template List Field",
+  "templates": {
+    "template_1": {
+        "name": "Template One",
+        "hint":"hint",
+        "items": {
+          "attr_a": {
+            "description": "Attribute A",
+            "type": "int",
+            "default": 10
+          },
+          "attr_b": {
+            "description": "Attribute B",
+            "hint": "This is a boolean attribute",
+            "type": "bool",
+            "default": true
+          }
+        }
+      },
+    "template_2": {
+      "name": "Template Two",
+      "hint":"hint",
+      "items": {
+        "attr_c": {
+          "description": "Attribute A",
+          "type": "int",
+          "default": 10
+        },
+        "attr_d": {
+          "description": "Attribute B",
+          "hint": "This is a boolean attribute",
+          "type": "bool",
+          "default": true
+        }
+      }
+    }
+  }
+}
+```
+
+Saved config example:
+
+```json
+"field_id": [
+    {
+        "__template_key": "template_1",
+        "attr_a": 10,
+        "attr_b": true
+    },
+    {
+        "__template_key": "template_2",
+        "attr_c": 10,
+        "attr_d": true
+    }
+]
+```
+
+<img width="1000" alt="image" src="https://github.com/user-attachments/assets/74876d30-11a4-491b-a7a0-8ebe8d603782" />
+
 
 ## Using Configuration in Plugins
 
diff --git a/en/use/skills.md b/en/use/skills.md
@@ -0,0 +1,37 @@
+# Anthropic Skills
+
+Anthropic's Agent Skills are a modular extension standard designed to turn Claude from a "general-purpose chatbot" into a "task executor" with domain-specific expertise. A Skill is a structured folder containing instructions, scripts, metadata, and reference resources. It is more than just a prompt—it functions like a specialized "operation manual" that is dynamically loaded only when the Agent needs to perform a specific task. A Tool is the model's concrete interface for interacting with the outside world (APIs/functions), while a Skill standardizes the combination of instructions, templates, and tools into a reusable task execution guide. Traditional Tools require all API definitions to be injected into the prompt at conversation start. If there are more than 50 tools, tens of thousands of tokens can be consumed before any conversation begins, making responses slower and costlier.
+
+Support for Anthropic Skills was introduced in AstrBot starting from v4.13.0, allowing users to easily integrate and use various predefined skill modules to improve the Agent's performance on specific tasks.
+
+## Key Features
+
+- Progressive Disclosure: The model initially loads only skill names and short descriptions. Detailed `SKILL.md` instructions are loaded only when a task matches, saving context window space and reducing cost.
+- Highly Reusable: Skills can be used across different Claude API projects, Claude Code, or Claude.ai.
+- Executable Capability: Skills can include executable code scripts that, together with Anthropic's code execution environment, can directly generate or process files.
+
+## Uploading Skills to AstrBot
+
+Open the AstrBot admin panel, navigate to the `Plugins` page, and find `Skills`.
+
+![Skills](../source/images/skills/image.png)
+
+You can upload Skills with the following requirements:
+
+1. The upload must be a `.zip` archive.
+2. **After extraction, it must contain a single Skill folder. The folder name will be used as the identifier for the Skill in AstrBot—please name it using English characters.**
+3. The Skill folder must include a file named `SKILL.md`, and its contents should preferably follow the Anthropic Skills specification. You can refer to Anthropic's documentation: https://code.claude.com/docs/zh-CN/skills
+
+## Using Skills in AstrBot
+
+Skills serve as operation manuals for Agents and often include executable Python snippets and scripts. Therefore, an Agent requires an **execution environment**.
+
+Currently, AstrBot provides two execution environments:
+
+- Local — The Agent runs in your AstrBot runtime environment. **Use with caution: this allows the Agent to execute arbitrary code in your environment, which may pose security risks.**
+- Sandbox — The Agent runs inside an isolated sandbox environment. **You must enable AstrBot sandbox mode first.** See: /use/astrbot-agent-sandbox. If sandbox mode is not enabled, Skills will not be passed to the Agent.
+
+You can select the default execution environment on the `Config` page under Skills.
+
+> [!NOTE]
+> Please note: if you select `Local` as the execution environment, AstrBot currently only allows **AstrBot administrators** to request that the Agent operate on your local environment. Regular users are prohibited from doing so. The Agent will be prevented from executing code locally via Shell, Python, or other tools and will receive a permission restriction message such as `Sorry, I cannot execute code on your local environment due to permission restrictions.`.
diff --git a/source/images/skills/image.png b/source/images/skills/image.png
diff --git a/zh/config/providers/start.md b/zh/config/providers/start.md
@@ -30,4 +30,10 @@ AstrBot 适配了 OpenAI、Google GenAI、Anthropic 三种原生 API 格式。
 4. 在 API 文档页面中，找到 “OpenAI 兼容接口” 相关的内容，记下 API Base URL，例如 `https://api.deepseek.com/v1`。（如果没有 /v1，就请加上 /v1）。
 5. 打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到并点击 `OpenAI`（如果其中有您想要接入的提供商的类型，请优先点击那些类型，如 DeepSeek，我们会针对部分提供商做适配优化）。将 API Key 填入对话框表单的 `API Key` 处，将 API Base URL 填入 `API Base URL` 处。
 6. 点击获取模型列表，找到您想要使用的模型名称，点击右侧 + 号，然后将右侧的出现的开关打开。
-7. 进入配置文件页面，找到对话模型，点击右侧的选择按钮，选择刚刚添加的提供商和模型，点击屏幕右下角的保存配置按钮即可。
+7. 进入配置文件页面，找到对话模型，点击右侧的选择按钮，选择刚刚添加的提供商和模型，点击屏幕右下角的保存配置按钮即可。
+
+## 使用环境变量加载 Key
+
+> v4.13.0 之后引入
+
+支持使用环境变量加载模型服务提供商的 API Key。在提供商配置页面，将 API Key 一栏填写为 `$环境变量名称` 的名称即可，例如填写 `$DEESEEK_API_KEY`。
diff --git a/zh/dev/star/guides/plugin-config.md b/zh/dev/star/guides/plugin-config.md
@@ -66,6 +66,21 @@ AstrBot 提供了”强大“的配置解析和可视化功能。能够让用户
 
 ![image](/source/images/plugin/image-select-provider.png)
 
+### file 类型的 schema
+
+在 v4.13.0 之后引入，允许插件定义文件上传配置项，引导用户上传插件所需的文件。
+
+```json
+{
+  "demo_files": {
+    "type": "file",
+    "description": "Uploaded files for demo",
+    "default": [], // 支持多文件上传，默认值为一个空列表
+    "file_types": ["pdf", "docx"] // 允许上传的文件类型列表
+  }
+}
+```
+
 ### dict 类型的 schema
 
 用于可视化编辑一个 Python 的 dict 类型的配置。如 AstrBot Core 中的自定义请求体参数配置项：
diff --git a/zh/use/skills.md b/zh/use/skills.md
@@ -0,0 +1,38 @@
+# Anthropic Skills
+
+Anthropic 推出的 Agent Skills（智能体技能）是一套模块化的功能扩展标准，旨在将 Claude 从一个“通用聊天机器人”转变为具备特定领域专业知识的“任务执行者”。Skills 是包含指令、脚本、元数据和参考资源的结构化文件夹。它不仅仅是提示词（Prompt），更像是一本专门的“操作手册”，在 Agent 需要执行特定任务时才会动态加载。Tool 是模型用来与外部世界交互的“具体工具/函数接口”，而 Skill 是将指令、模板和工具组合在一起的“标准化任务执行手册”。传统 Tool 需要在对话开始时一次性将所有 API 定义填入 Prompt。如果工具超过 50 个，可能还没开始说话就消耗了数万个 Token，导致响应变慢且昂贵。
+
+AstrBot 在 v4.13.0 之后引入了对 Anthropic Skills 的支持，使得用户可以轻松集成和使用各种预定义的技能模块，提升 Agent 在特定任务上的表现。
+
+## 关键特性
+
+- 按需加载 (Progressive Disclosure)：模型初始只加载技能名称和简短描述。只有当任务匹配时，才会加载详细的 SKILL.md 指令，从而节省上下文窗口并降低成本。
+- 高度可复用：技能可以在不同的 Claude API 项目、Claude Code 或 Claude.ai 中通用。
+- 执行能力：技能可以包含可执行代码脚本，配合 Anthropic 代码执行环境（Code Execution）直接生成或处理文件。 
+
+## 上传 Skills 到 AstrBot
+
+进入 AstrBot 管理面板，导航到 `插件` 页面，找到 `Skills`。
+
+![Skills](/source/images/skills/image.png)
+
+你可以上传 Skills，上传格式要求如下：
+
+1. 是一个 .zip 压缩包
+2. **解压后是一个 Skill 文件夹，Skill 文件夹的名字即为这个 Skill 在 AstrBot 中的标识，请用英文命名**。
+3. Skill 文件夹内必须包含一个名为 `SKILL.md` 的文件，且该文件内容最好符合 Anthropic Skills 规范。你可以参考 [Anthropic 技能](https://code.claude.com/docs/zh-CN/skills)
+
+## 在 AstrBot 使用 Skills
+
+Skills 提供了 Agent 操作说明书，并且内容通常包含 Python 代码段、脚本等可执行内容。因此，Agent 需要一个**执行环境**。
+
+目前，AstrBot 提供两种执行环境：
+
+- Local（Agent 将在你的 AstrBot 运行环境中运行。**请谨慎使用，因为这会允许 Agent 在你的环境执行任意代码，可能带来安全风险**）
+- Sandbox (Agent 在隔离化的沙盒环境中运行。**需要先启动 AstrBot 沙盒模式**，请参考：[沙盒模式](/use/astrbot-agent-sandbox)，如果这个模式下不启动沙盒模式，将不会将 Skills 传给 Agent)
+
+你可以在 `配置` 页面 - Skills 中选择默认的执行环境。
+
+> [!NOTE]
+> 需要说明的是，如果您使用 Local 作为执行环境，AstrBot 目前仅允许 **AstrBot 管理员**请求时才真正让 Agent 操作你的本地环境，普通用户将会被禁止，Agent 将无法通过 Shell、Python 等 Tool 在本地环境执行代码，会收到相应的权限限制提示，如 `Sorry, I cannot execute code on your local environment due to permission restrictions.`。
+
