> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill

> Skill 是可复用的能力包：一段 SKILL.md 说明加上允许使用的工具，供 AI SRE Agent 在对话中按需调用。从市场安装、上传自定义 Skill，或在对话中用 skill-creator 直接创建。

<Info>
  **公测功能**：AI SRE 已全量开放公测，无需申请，登录控制台即可直接使用，公测期间免费。功能与界面可能继续调整。
</Info>

## 概述

***

Skill 是一个**可复用的能力包**。一个 Skill 由两部分组成：

* 一段 **SKILL.md** 说明文档，告诉 Agent「什么场景下用、怎么用、按什么步骤做」；
* 该 Skill 声明的**允许使用的工具**，以及可选的参考资源文件（脚本、模板、子文档等）。

Skill 被打包成 Skill 归档（`.zip` 或 `.tar.gz`，扩展名 `.zip` / `.skill` / `.tar.gz` / `.tgz`）上传到 AI SRE，`.tar.gz` 在安装时会被规范化为标准 zip。归档的根目录必须包含一个 `SKILL.md` 文件，其余资源文件可放在归档内任意位置，Agent 可在执行时按需读取。

启用后，该 Skill 即在会话中对 Agent 可见、可被调用。Agent 既可以**自主判断**何时调用某个 Skill，您也可以在对话框里用 `/<skill-name>`（如 `/skill-creator`）来**显式触发**它。

显式触发时还可以追加参数：`/<skill-name> 参数1 参数2`。SKILL.md 正文可以用 `$1`…`$9` 引用按空白拆分的位置参数，用 `$ARGUMENTS` 引用参数串的完整原文；这些占位符会在该轮对话发送前被替换为实际值。

如果只是想在消息里**提到** `/skill-name`（比如问「`\/skill-name` 是做什么的？」）而不想触发它，可以在消息开头加一个反斜杠转义：以 `\/` 开头的消息会被去掉这个反斜杠、按普通文本发送，不会被解析为命令。

<Info>
  **团队同名 Skill 与 `@` 限定语法。** Skill 名在同一团队内必须唯一，但不同团队可以各自拥有同名 Skill。当两个团队都启用了同名 Skill 且都在当前会话的可见范围内时，裸 `/<skill-name>` 无法确定指向哪一个，会被拒绝并提示可用的限定形式。此时需要使用 `/<skill-name>@<team_id>` 来消除歧义（例如 `/deploy@5`）。因此 `@` 字符在 Skill 名中被保留，不能使用。
</Info>

<Tip>
  Skill 与 MCP 的区别：MCP 提供**外部工具的接入能力**，Skill 提供**如何编排这些工具完成一类任务的方法论**。两者配合使用——Skill 在 SKILL.md 里声明它需要哪些工具，包括内置工具和 `mcp:服务名/工具名` 形式的 MCP 工具。
</Tip>

### SKILL.md 格式

`SKILL.md` 由 YAML frontmatter（元数据）和正文（Agent 可读的说明）两部分组成，以 `---` 分隔：

```markdown theme={null}
---
name: skill-name
description: USE FIRST for ... — 简明说明此 Skill 解决的问题与适用场景
version: "1.0.0"
tags:
  - tag1
  - tag2
author: author-name
license: MIT
allowed-tools: bash, read, task
---

## Instructions

Skill 正文写在这里：执行步骤、约束、注意事项……
```

frontmatter 字段如下：

| 字段              | 类型        | 是否必填 | 说明                                                                                                                                           |
| --------------- | --------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | string    | 是    | Skill 名：以字母开头，只能包含字母（不限大小写）、数字、`-` 和 `_`（如 `my-skill-name`、`code_reviewer`、`IncidentTriage`），长度 1–64。会作为 `/<skill-name>` 的触发词，斜杠命令按同一套命名规则解析 |
| `description`   | string    | 否    | Skill 描述。这是 Agent 选择 Skill 的核心信号，建议写成「USE FIRST / prefer-over-X」式的祈使句，越精准越容易被正确调用                                                            |
| `version`       | string    | 否    | 版本号，如 `1.0.0`                                                                                                                                |
| `tags`          | string\[] | 否    | 标签列表                                                                                                                                         |
| `author`        | string    | 否    | 作者                                                                                                                                           |
| `license`       | string    | 否    | 许可证                                                                                                                                          |
| `allowed-tools` | string\[] | 否    | 此 Skill 允许使用的工具清单，留空表示不额外限制                                                                                                                  |
| `venues`        | string\[] | 否    | 限制此 Skill 只在指定类型的执行环境中可用。取值为 `cloud`（云端 Sandbox）与 `byoc`（自托管 Runner），可多选；留空表示所有环境都可用。上传时会校验取值，写错会被拒绝                                         |

<Note>
  `venues` 用于那些结构上离不开某类环境的 Skill——例如需要访问运行环境所在主机的本地二进制、本地文件或内网服务的 Skill，在云端 Sandbox 里根本无法工作。声明 `venues: [byoc]` 后，该 Skill 在云端 Sandbox 会话中既不会出现在 Agent 的可用 Skill 清单里，也无法通过 `/<skill-name>` 触发；只有绑定了自托管 Runner 的会话才能看到并调用它。
</Note>

工具的写法有两种：

* **内置工具**：直接写工具名。可用的内置工具包括 `read`、`write`、`edit`、`bash`、`grep`、`glob`、`skill`、`mcp`、`todo`、`time`、`webfetch`、`web_search` 等。
* **MCP 工具**：写成 `mcp:服务名/工具名`（如 `mcp:my-server/query`）。上传时只校验该 MCP 服务是否存在，具体工具名在会话中加载 MCP 时才会被验证。

<Note>
  AI SRE 运行时内置了几个 Skill，无需安装即可使用。`flashduty` 是其中一个范例：它通过 `fduty` 命令行覆盖整个 Flashduty API，让 Agent 可以排障故障、读取 AI 详情、查询告警、关联变更等。您可以参考它来编写自己的 Skill。另一个内置 Skill 是 `github`，Agent 会从 `<available_skills>` 中自主选用它，让 AI SRE 直接在 GitHub 仓库里工作——探索代码、调查 PR / 提交、按需开 PR 或 Issue；它需要安装 GitHub App（云端）或运行环境主机上的 `gh`（BYOC）。第三个内置 Skill 是 `gitlab`，能力与 `github` 对称：Agent 自主选用它在 GitLab 仓库里探索代码、追溯 MR / Issue、按需开 MR 或 Issue；它需要安装 GitLab App（云端）或运行环境主机上的 `glab`（BYOC）。详见 [Apps](/zh/ai-sre/apps)。
</Note>

## 从市场安装

***

进入 **插件 → Skill** 页面，点击 **浏览 Marketplace** 打开 Skill**目录**，可以浏览并安装 Flashduty 与 Anthropic 提供的 Skill 模板。

<Steps>
  <Step title="打开目录">
    在 Skill 列表页点击 **浏览 Marketplace**，弹出目录对话框，以卡片网格展示所有可用 Skill 模板。
  </Step>

  <Step title="检索与筛选">
    顶部搜索框按名称或描述检索；右上角的**筛选**可只看「已安装」或「未安装」，**排序**支持「已安装优先」或「名称 A–Z」。
  </Step>

  <Step title="确认安装">
    在未安装的卡片上点击 **+** 按钮，会弹出「安装 Skill」确认对话框（标题中带模板名称），提示「将安装到账户，账号内所有成员可用」——市场安装的 Skill 固定为**共享范围**（共享即账户级），不提供归属选择。点击 **安装** 才会真正调用安装接口，把模板内容复制到您的账户，成为一个普通 Skill 行，并标记其来源模板（卡片上以 `v<版本>` 角标标识「来自 Marketplace」）。
  </Step>

  <Step title="管理已安装项">
    已安装的卡片右上角变为齿轮图标，点击进入该 Skill 的检视面板进行管理。
  </Step>
</Steps>

<Note>
  新账户会自动预装一组官方 Marketplace 模板：`browser-automation`（浏览器自动化 CLI，用于操作网站/仪表盘/监控 UI）、`mcp-builder`（指导创建 MCP 服务器）、`monit-query`（Monit 数据源查询）与 `skill-creator`（见下文「在对话中创建」）。这些预装 Skill 与手动安装的 Skill 完全一样，可以在下方「管理与检视」中启用/禁用、卸载或更新到最新版本。
</Note>

<Warning>
  **同名冲突**：若账户里已存在同名 Skill，且它**不是**从同一模板安装的（例如您手工上传的自定义 Skill），安装会被拒绝——市场安装不会覆盖或接管这类 Skill，即使选择覆盖更新也一样。此时请先删除该自定义 Skill，再安装同名市场模板。
</Warning>

### 自动更新与手动更新

当市场中的模板发布了更高版本时，对应 Skill 行会出现 **有更新** 标记。是否自动更新取决于该 Skill 是否被本地改动过：

<CardGroup cols={2}>
  <Card title="纯净 Skill（未改动）" icon="rotate">
    安装后未做任何本地修改的 Skill，会在列表加载时**自动**拉取市场最新版本并覆盖，无需手动操作；更新成功后会有提示。
  </Card>

  <Card title="已改动 Skill" icon="pen">
    被本地编辑或重新上传过的 Skill，自动更新会**跳过**，避免覆盖您的改动。它会保留「有更新」标记，需您**手动**点击更新并确认覆盖。
  </Card>
</CardGroup>

<Warning>
  对已改动 Skill 执行更新，会用市场最新版本**覆盖您的本地改动且无法恢复**。界面会弹出「覆盖更新」确认框，请谨慎操作。重新安装市场版本后，本地改动标记会被清除，该 Skill 恢复为纯净状态、重新参与自动更新。
</Warning>

## 自定义 Skill

***

除了从市场安装，您也可以上传自己的 Skill 包。在 Skill 列表页点击 **上传 Skill**，在表单中填写：

| 字段     | 类型      | 是否必填 | 说明                                                                                                     |
| ------ | ------- | ---- | ------------------------------------------------------------------------------------------------------ |
| 归属     | 团队 / 共享 | 是    | 选择 Skill 的作用域：**共享**（即账户级，账户内全局可见）或某个**团队**（仅该团队成员可见）。上传到团队作用域时，您必须是目标团队成员；共享范围上传仅限账户所有者或管理员。详见下文「作用域」 |
| Zip 文件 | 文件      | 是    | 包含 `SKILL.md`（必需）及可选资源文件的归档；接受 `.zip` / `.skill` / `.tar.gz` / `.tgz` 归档                               |

上传时系统会自动校验：归档是合法 zip、根目录存在 `SKILL.md`、frontmatter 可解析、`name` 符合命名规则（字母开头，仅含字母、数字、`-`、`_`，长度 1–64）、声明的工具有效（内置工具存在、MCP 服务存在）。同一**团队**内**Skill 名不能重复**，重名会被拒绝并提示换名；不同团队可以各自拥有同名 Skill。

<Note>
  Skill 名以外的元数据（描述、版本、标签、作者、工具等）都从 `SKILL.md` 的 frontmatter 解析得到，无需在表单中重复填写。
</Note>

### 覆盖上传（Replace）

当您要用新版本替换已有 Skill 时，上传端点支持两种覆盖模式，界面会在适当时机弹出「替换」确认对话框：

| 模式          | 触发条件                                      | 行为                                                                                                   |
| ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **按名称覆盖**   | 上传 zip 时携带 `replace=true`，且不指定 `skill_id` | 以新归档的 `SKILL.md` 中 `name` 字段匹配账户内同名 Skill 并覆盖其内容；SkillID 不变，所有对该 Skill 的引用（如 `/<skill-name>` 触发）继续生效 |
| **按 ID 覆盖** | 上传 zip 时携带 `replace=true` 且指定 `skill_id`  | 不依赖 zip 内的 `name` 字段，直接以指定 ID 定位并替换对应 Skill；适合在重命名后仍要覆盖原记录的场景                                        |

两种模式在替换成功后均返回更新后的 Skill 对象；若目标 Skill 不存在，返回 404 错误而非新建。**不携带 `replace` 参数时（默认），重名归档会被直接拒绝**，上传端点不会隐式覆盖已有 Skill。

### 在对话中创建（skill-creator）

除了上传 zip，您还可以**直接在 AI SRE 会话里创建和打磨 Skill**。`skill-creator` 是 Flashduty 在 Marketplace 提供、并默认预置到账户的一个 Skill，专门用来「造 Skill」。在任意会话里用 `/skill-creator` 触发，或直接用自然语言提出需求即可：

* **从零创建**：说「帮我创建一个用于排查 X 的 Skill」，或在一次排障结束后说「把刚才这套流程固化成一个 Skill」。skill-creator 会与您澄清意图、起草 `SKILL.md`、（可选）建立测试用例并据此迭代，满意后一键保存为账户里的 Skill。
* **改写与优化**：在某个 Skill 的检视面板点击 **「在聊天中编辑」**，会以 skill-creator 改写该 Skill；它也能帮您打磨 `description`，提升被正确触发的准确度。

Agent 完成起草后可一键把内容保存为 Skill；与已有 Skill 重名时，保存前会弹出「替换」确认对话框——底层即走按名称覆盖模式（`replace=true`，无 `skill_id`）。

<Warning>
  Skill 归档大小有上限：通过对话中 Agent 打包保存的归档上限为 **10 MB**，通过网页表单或会话内呈现文件上传的归档上限为 **100 MB**。
</Warning>

## 管理与检视

***

Skill 列表以表格展示每个 Skill 的**名称**（含来源模板角标、「有更新」标记与「仅本地 Runner」角标）、**范围**（共享或团队）、**版本**、**启用**开关与**操作**列。仅声明了 `venues: [byoc]` 的 Skill 会带上「**仅本地 Runner**」角标，鼠标悬停显示「仅在绑定本地 Runner 的会话中可用，云沙箱会话中不可用」；Marketplace 的模板卡片上也有同样的角标，方便您在安装前就知道它需要自托管 Runner。列表上方的工具条提供范围筛选（全部 / 账户 / 团队）与搜索框，搜索按名称、描述或作者中的关键词过滤列表。

<AccordionGroup>
  <Accordion title="启用 / 禁用" icon="toggle-on">
    用列表或检视面板上的开关切换。只有**已启用**的 Skill 才会对 Agent 可见；禁用后 Agent 看不到、也无法调用它。
  </Accordion>

  <Accordion title="编辑" icon="pen-to-square">
    点击编辑按钮可更新**描述**与**归属**（作用域）。市场安装的 Skill 归属固定为账户，编辑表单中作用域不可改。如需修改 Skill 内容，请下载 zip、编辑后**重新上传**（这会创建新版本，并把该 Skill 标记为已改动）。
  </Accordion>

  <Accordion title="替换 / 重新上传" icon="upload">
    在检视面板选择「替换」，用一个新的 zip 覆盖当前 Skill 内容；SkillID 保持不变，对它的引用（如 `/<skill-name>` 触发）依然有效。
  </Accordion>

  <Accordion title="下载" icon="download">
    下载完整 zip 包（含 `SKILL.md` 和所有资源文件），便于离线编辑或备份。
  </Accordion>

  <Accordion title="卸载 / 删除" icon="trash">
    将 Skill 从当前范围移除。正在使用它的活跃会话会持续失败，直到重新安装。此操作有确认提示。
  </Accordion>
</AccordionGroup>

### 检视面板

在列表中点击任意一行，打开 Skill**检视面板**：

* **左侧**：Skill 包的文件树（`SKILL.md`、`README.md` 等会优先作为默认预览文件）。
* **右侧**：选中文件的内容预览，顶部显示 Skill 描述。
* **标题区**：Skill 名（短引用形如 `skill-xxxxxx`）、范围标签（共享 / 团队名）、来源模板版本角标（鼠标悬停显示「来自 Marketplace — 模板名 v版本」）、**有更新**标记、作者、`version`、以及完整 SkillID。
* **操作**：在聊天中试用（向新会话注入 `/<skill-name>`）、更新到最新版本、在聊天中编辑、替换、下载、卸载。

<Tip>
  Skill 包**过大无法预览**时，检视面板会提示体积并建议改用「下载」查看。
</Tip>

## 作用域

***

Skill 与其他资源（知识库、MCP、Agent、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级：

| 作用域     | 可见性       |
| ------- | --------- |
| 共享（账户级） | 账户内所有成员可见 |
| 团队级     | 仅该团队成员可见  |

**编辑权限**：团队级 Skill 仅该团队的成员可以操作，组织管理员也需要先加入该团队；账户级 Skill 仅账户所有者或管理员可以操作；没有「创建者保留权限」这一例外。无编辑权限时，列表对应行显示为**只读**。

**创建与改归属**：上传新的团队级 Skill 时，您必须是目标团队成员；账户级上传仅限账户所有者或管理员。**从市场安装是例外**：安装固定为共享范围（账户级），账户内任何成员都可以安装，不需要所有者或管理员权限，也不能在安装时选择团队。编辑已有 Skill 时，账户所有者或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。但**市场安装的 Skill 不可改归属到团队**——编辑表单中其作用域固定显示为账户；极少量早期遗留的团队级市场 Skill 可通过检视面板的「设为共享」提升为账户级。**「设为共享」与账户级上传同门槛，仅限账户 Owner 或管理员**：普通成员即使属于该 Skill 所在团队也不能自助提升，操作被拒绝时会提示「请管理员把它设为共享」。

**运行时可见性**：会话开始时，只会加载**共享范围（账户级）**的 Skill，以及**当前会话所绑定团队**的 Skill。当 Agent 在排障中读取另一个团队的知识后，该团队的 Skill 与 MCP 才会被按需挂载进当前会话。**账户是运行时唯一的安全边界；对团队级 Skill 的使用同样受此可见性约束，团队不只是归属与编辑的标记。**

<Note>
  对话框 `/` 自动补全下拉只展示**共享范围的 Skill** 以及**您所属团队**的团队级 Skill——这不只是菜单显示问题：手动输入的斜杠命令与自动补全受同一套按行范围门控（「可见即可解析」），不在当前会话可见范围内的团队级 Skill 不会被解析执行。具体而言：团队会话中调用其他团队的命令会被拒绝并提示不可用的原因；个人会话中，该 Skill 所在团队的成员手动输入命令可以解析（并按需挂载该团队），非成员输入则与输入了不存在的命令一样被拒绝。
</Note>

## 相关页面

***

<CardGroup cols={2}>
  <Card title="管理知识" icon="book" href="/zh/ai-sre/knowledge">
    用 DUTY.md 与知识包为 Agent 提供团队上下文与排障经验。
  </Card>

  <Card title="MCP（外部工具）" icon="plug" href="/zh/ai-sre/mcp">
    接入外部工具，让 Skill 在 SKILL.md 中以 `mcp:服务名/工具名` 调用它们。
  </Card>

  <Card title="Agent" icon="satellite-dish" href="/zh/ai-sre/agents">
    用 Agent 扩展 AI SRE 的协作与分工能力。
  </Card>

  <Card title="控制台" icon="comments" href="/zh/ai-sre/sessions">
    在会话中用 `/<skill-name>` 显式触发 Skill，或让 Agent 自主调用。
  </Card>

  <Card title="概述" icon="gauge-high" href="/zh/ai-sre/overview">
    了解 AI SRE 的整体能力与定位。
  </Card>
</CardGroup>