本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# DevOps 代理技能
<a name="about-aws-devops-agent-devops-agent-skills"></a>

AWS DevOps Agent Skills 是模块化指令集，通过为您的基础设施和操作工作流程量身定制的专业领域知识和调查方法，扩展代理人的能力。

## 什么是技能
<a name="what-are-skills"></a>

技能是独立的目录，包含 Markdown 指令，可为代理提供专业功能。 AWS DevOps AWS DevOps 代理支持代理技能规范的子集[（一种打包](https://agentskills.io/)代理指令和资源的开放标准），仅支持不可执行的文档：Markdown 指令、PDF、图像和数据文件。

**注意**  
**启用沙盒（预览版）时，技能还可以包括代理在沙盒环境中运行的可执行代码。有关更多信息，请参阅[设置沙盒](configuring-integrations-and-knowledge-sandbox.md)。

每项技能都需要一个 SKILL.md 文件，其中包含你要为 AWS DevOps 代理提供的指令。除了所需的 SKILL.md 文件外，技能还可能包括：
+ ****针对特定场景或基础设施类型的调查工作流程。
+ **参考资料**包括架构模式和操作程序。
+ **代理类型定位 **-技能可以针对特定的代理类型（通用、事件分类 On-demand、事件 RCA、事件缓解、评估），以减少情境消耗并提高代理关注度。

## 为什么要使用技能
<a name="why-use-skills"></a>

技能将 AWS DevOps 代理从通用助理转变为基础设施和运营工作流程方面的专家。与聊天消息中提供的一次性说明不同，技能是可重复使用的功能，当与 AWS DevOps 代理执行的任务相关时，会自动加载。

**主要好处：**
+ **专业化您的代理 ** ——根据您的基础架构和运营模式特定的调查程序、最佳实践和组织知识来定制 AWS DevOps 代理。
+ **减少重复 ** — 只需创建一次调查工作流程， AWS DevOps Agent 便会在所有相关调查中自动使用这些工作流程，无需重复提供相同的指导。
+ **撰写能力 ** — 结合多种技能，构建端到端的调查工作流程。 AWS DevOps 代理在执行过程中会读取多种技能，例如从自定义 CI/CD 管道检索部署的技能和搜索代码存储库的技能。
+ **增强自定义工具 ** — 创建指导 AWS DevOps 代理有效使用自定义 MCP 服务器工具的技能。技能可以记录何时调用特定工具、在不同场景中使用哪些参数，以及如何解释结果以完成特定于您的基础架构的工作流程。

## 技能是如何运作的
<a name="how-skills-work"></a>

当 AWS DevOps 特工遇到相关任务时，它会加载相应的技能并按照指示进行调查。例如，“数据库性能调查” 技能可能包括分析 RDS 限制问题的分步程序，使代理能够系统地检查警报状态、分析连接指标和识别慢速查询。

## 技能结构
<a name="skill-structure"></a>

技能按目录进行组织，其中包含：

```
my-skill/
├── SKILL.md              # Main skill instructions
├── references/           # Optional: additional reference documentation
└── assets/               # Optional: images, diagrams, data files
```

### SKILL.md
<a name="skillmd"></a>

`SKILL.md`是唯一的必填文件。它包含以 Markdown 格式编写的核心指令。该文件应该：
+ 描述何时以及如何使用该技能。
+ 提供分步调查程序。
+ 包括适用于不同场景的决策树。
+ 记录预期产出和成功标准。

### 前言
<a name="frontmatter"></a>

Frontmatter 是位于`SKILL.md`文件顶部的元数据块，包含在`---`分隔符之间。它包含`name`和`description`字段， AWS DevOps 代理在调查或任务期间使用这些字段来确定何时激活技能。

```
---
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues including
  connection exhaustion, slow queries, replication lag, and storage capacity.
  Use this skill when investigating database latency, connection errors, or
  read/write performance degradation.
---
```

**名称 ** — 技能的唯一标识符。仅使用小写字母、数字和连字符（最多 64 个字符）。不得以连字符开头或结尾。

**描述 ** — 详细说明 AWS DevOps 代理应在何时及为何使用此技能。 AWS DevOps 代理评估此字段以确定该技能是否与当前任务相关。即使指令写得很好，模糊或缺失的描述也会导致代理完全跳过该技能。

**重要 ** — 从代理的角度撰写描述。包括应触发技能的特定场景、服务、错误类型或症状。例如，“在调查 Amazon RDS 实例的数据库延迟、连接错误或查询超时时使用此技能” 比 “RDS 技能” 更有效。

当你在用户界面中创建技能时，系统会根据你提供的名称和描述自动生成 frontmatter。以 zip 文件形式上传的技能必须在文件中包含 frontmatter。`SKILL.md`

## 示例：完成技能
<a name="example-complete-skill"></a>

以下示例显示了调查 RDS 性能问题的完整、结构正确的技能。它演示了目录结构、 SKILL.md 前言、可操作的调查程序和补充参考文件。

**目录结构：**

```
rds-performance-investigation/
├── SKILL.md
├── references/
│   └── rds-metrics-reference.md
└── assets/
    └── rds-investigation-flowchart.png
```

**SKILL.md:**

```
---
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues including
  connection exhaustion, slow queries, replication lag, and storage capacity.
  Use this skill when investigating database latency, connection errors, or
  read/write performance degradation.
---

# RDS Performance Investigation

Use this skill when customers report database latency, connection errors,
query timeouts, or read/write performance degradation.


## Step 1: Check alarm status

Query CloudWatch for active alarms on the affected RDS instance. Look for:
- `DatabaseConnections` exceeding 80% of max_connections
- `ReadLatency` or `WriteLatency` above 20ms
- `FreeStorageSpace` below 20% of total storage
- `ReplicaLag` above 30 seconds (read replicas only)


## Step 2: Analyze connection metrics

Retrieve `DatabaseConnections` over the past hour. If connections are near
the max_connections limit, check for connection pool misconfiguration or
long-running idle connections.


## Step 3: Identify slow queries

Use Performance Insights (`pi:GetResourceMetrics`) to retrieve the top SQL
statements by average active sessions. Focus on queries with high `db.load`
contribution or frequent I/O waits.


## Step 4: Summarize findings

Provide a summary with:
1. Current performance status (healthy / degraded / critical)
2. Root cause hypothesis with supporting metrics
3. Recommended remediation steps ranked by priority
```

**references/rds-metrics-reference.md：**

```
# RDS CloudWatch Metrics Reference


| Metric | Normal Range | Investigation Threshold |
|---|---|---|
| DatabaseConnections | < 70% max_connections | > 80% max_connections |
| ReadLatency | < 5ms | > 20ms |
| WriteLatency | < 5ms | > 20ms |
| FreeStorageSpace | > 30% total storage | < 20% total storage |
| ReplicaLag | < 5 seconds | > 30 seconds |
| CPUUtilization | < 70% | > 85% |
```

## 示例：事件过滤技能
<a name="example-incident-filtering-skill"></a>

针对 “**事件分类” ** 代理类型的技能可以定义自动跳过事件的标准。使用它来筛选不需要调查的事件。当新事件符合跳过条件时， AWS DevOps 代理会将其标记为 “**已跳过**”。该系统提供了解释其被过滤的原因。

以下示例显示了在定期维护期间跳过低优先级事件的技能：

**SKILL.md:**

```
---
name: skip-scheduled-maintenance
description: Skip low-priority incidents during a scheduled maintenance window.
  Use this skill to automatically filter MEDIUM and LOW severity alarms that
  fire during planned maintenance, avoiding unnecessary investigations for
  expected disruptions.
---

# Skip Scheduled Maintenance

Skip all incidents that meet BOTH of the following criteria:

1. The incident arrived between **2025-03-15 02:00 UTC** and **2025-03-15 06:00 UTC**
2. Severity is MEDIUM or LOW

Do NOT skip HIGH or CRITICAL severity incidents, even during the maintenance window.
```

创建此技能时，选择 “**事件分类” ** 作为代理类型。这样可以确保仅在分类阶段对技能进行评估。

## 创建技能
<a name="creating-skills"></a>

在创建技能之前，你必须有一个代理空间。有关更多信息，请参阅 [创建代理空间](getting-started-with-aws-devops-agent-creating-an-agent-space.md)。

根据工作流程偏好和技能复杂程度，您可以通过两种方式创建技能：

要通过 AWS CLI 或 AWS SDK 以编程方式管理技能，请参阅。[管理资产](about-aws-devops-agent-managing-assets.md)

### 在用户界面中创建技能
<a name="creating-a-skill-in-the-ui"></a>

在 AWS DevOps 代理操作员 Web 应用程序中创建的技能在单个 SKILL.md 文件中包含名称、描述和说明。

**要在 UI 中创建技能，请执行以下操作：**
+ 在 Agent Space Operator Web 应用程序中导航到 “**知识” ** 页面，然后选择 ** “**技能” 选项卡。
+ 选择 “**添加技能” **。
+ **从模态中选择 “**创建技能”。
+ 填写技能表：
  + **名称 **-仅限小写字母、数字和连字符（最多 64 个字符）。不得以连字符开头或结尾。示例：`rds-throttling-investigation`
  + **描述 ** — 简要说明何时使用此技能（建议至少 100 个字符，最多 1,024 个字符）。这有助于代理确定何时激活技能。
  + **状态 **-设置为 “活动”（默认）或 “非活动”。代理不使用非活跃技能。
  + **代理类型 **-选择一种或多种可以使用此技能的代理类型。**默认**情况下选择 “通用”，使所有代理类型均可使用该技能。要以特定代理为目标，请取消选择 “通用”，然后选择： On-demand、事件分类、事件 RCA、事件缓解或评估。
  + **说明 ** — Markdown 格式的 Step-by-step 程序。要具体且切实可行。
+ 选择 “创建” 保存技能。

系统会自动生成具有正确前端结构的 SKILL.md 文件。

**要编辑在 UI 中创建的技能，请执行以下操作：**
+ 在 “**知识” ** 页面的 “技**能**” 选项卡上导航到该技能，然后选择该技能将其打开。
+ 选择**编辑**。
+ 修改名称、描述或说明。
+ 选择 “**保存” ** 以更新技能。

### 上传技能
<a name="uploading-a-skill"></a>

以 zip 文件形式上传的技能包含 SKILL.md 文件以及其他资源，例如参考材料或资产。

**技能结构：**

```
my-skill.zip
├── SKILL.md              # Required: main skill instructions
├── references/           # Optional: reference documentation
│   ├── architecture.md
│   └── troubleshooting.md
└── assets/               # Optional: images, diagrams, data files
    ├── topology.png
    └── metrics.csv
```

**SKILL.md 前端要求：**

以 zip 文件形式上传的技能必须在 with `name` 和 fi `description` elds 中 SKILL.md 包含前端内容。 AWS DevOps 代理使用这些字段来确定何时激活技能。有关撰写有效前言的详细信息，请参阅本主题前面的 Frontmatter 部分。

```
---
name: rds-performance-analysis
description: Comprehensive RDS performance investigation procedures
  for connection exhaustion, slow queries, and storage capacity issues.
  Use when investigating database latency or read/write degradation.
---


# RDS Performance Analysis


[Your skill instructions here...]
```

**要通过 zip 上传创建技能，请执行以下操作：**
+ 按照前面的结构创建包含技能文件的目录。
+ 确保 SKILL.md 包含正确的正文（名称和描述）。
+ 将该目录压缩为 .zip 文件。
+ 在 Agent Space Operator Web 应用程序中导航到 “**知识” ** 页面，然后选择 ** “**技能” 选项卡。
+ 选择 “**添加技能” **。
+ **从模态中选择**上传技能。
+ 拖放您的 .zip 文件或选择浏览（仅限 ZIP 文件，最大 6 MB）。
+ 选择一种或多种可以使用此技能的代理类型（默认情况下选择 “通用”，适用于所有代理类型；取消选择目标座席 On-demand、事件分类、事件 RCA、事故缓解或评估）。
+ 查看 zip 文件要求和验证结果。
+ 选择 “上传” 将技能添加到您的代理空间。

**对以 zip 文件形式上传的技能的重要限制：**
+ **目前不支持脚本 **-在上传期间，`scripts/`目录中包含脚本的技能将被拒绝。一旦代理可以访问安全的编码环境，将在未来的版本中启用脚本执行。
+ **大小限制 ** — 压缩文件总大小不得超过 6 MB（包括所有文件）。
+ **SKILL.md 必填 ** —压缩文件必须包含带有有效前缀的 SKILL.md 文件。

**命名技巧的最佳实践：**

使用清晰的描述性名称，例如 “rds-throttling-invessigation”，而不是通用名称。一个好的技能名称反映了它所针对的具体场景或服务，因此一目了然地更容易识别出正确的技能。

### 从存储库导入技能
<a name="importing-a-skill-from-a-repository"></a>

您可以直接从 GitHub 存储库目录导入技能。 AWS DevOps 代理从存储库中获取技能内容，从头部提取名称和描述 SKILL.md ，然后在代理空间中创建技能。这使您可以管理版本控制中的技能，并通过一个操作将其导入。

**先决条件：**
+ 与您的代理空间关联的 GitHub 帐户。要关联 GitHub 账户，请参阅[正在连接 GitHub](connecting-to-cicd-pipelines-connecting-github.md)。任何 GitHub 帐户连接都允许从公共存储库导入。对于私有仓库，关联的账户必须具有对仓库的读取权限。 GitHub 还支持具有数据驻留连接的 GitHub 企业服务器和企业云。
+ 包含有效技能目录的 GitHub 存储库，其根目录为 SKILL.md 文件。

**存储库结构：**

您导入的存储库目录必须遵循标准技能结构：

```
my-skill/
├── SKILL.md              # Required: must include name and description in frontmatter
├── references/           # Optional: reference documentation
│   └── runbook.md
└── assets/               # Optional: images, diagrams, data files
    └── architecture.png
```

**要从存储库导入技能，请执行以下操作：**
+ 在 Agent Space Operator Web 应用程序中导航到 “**知识” ** 页面，然后选择 ** “**技能” 选项卡。
+ 选择 “**添加技能” **。
+ 从模态中选择 “**从存储库**导入”。
+ 输入包含您的 SKILL.md 文件的 GitHub 目录 URL。例如：`https://github.com/my-org/my-repo/tree/main/skills/rds-investigation`。例如，对于具有数据驻留的 GitHub GitHub 企业服务器或企业云，请改用您的实例的 URL `https://github.example.com/my-org/my-repo/tree/main/skills/rds-investigation`。
+ 选择一种或多种可以使用此技能的代理类型。
+ 设置生命周期状态（活动或非活动）。
+ 选择 “**导入技能” **。

AWS DevOps 代理获取目录内容，读取 SKILL.md 前端内容以提取技能名称和描述，并将所有文件导入您的代理空间。

**查看导入的技能：**

导入的技能显示在 “自定义技能” 列表中，并带有指向源存储库的链接。在技能详细信息视图中：
+ 技能名称和描述是只读的（由您的 SKILL.md 文件管理）。
+ 指令和资源文件以只读模式显示。
+ 状态和代理类型保持可编辑状态。
+ “上次同步” 时间戳显示上次从存储库同步技能的时间。

**同步导入的技能：**

更新存储库中的技能文件时，您可以同步导入的技能以提取最新的更改：
+ 在详细视图中打开导入的技能。
+ 选择**同步**。
+ AWS DevOps 代理从源存储库重新获取目录内容并更新技能内容。

您也可以通过在导入的技能行**上选择 “**同步”，从技能列表视图进行同步。

**注意：**同步将技能内容完全替换为存储库目录的当前状态。对可编辑字段（状态、代理类型）的任何本地更改都将保留。

**约束**：
+ **URL 格式 ** — 仅接受 GitHub URL，包括具有数据驻留权的 GitHub GitHub 企业服务器和企业云。连接的 GitHub 账户必须与 URL 主机相匹配。例如，`github.example.com`连接只能从 URL 导入，不能从 `github.example.com` `github.com` URL 导入。您可以指向包含 SKILL.md （例如`https://github.com/org/repo/tree/main/skills/my-skill`）的目录，该目录导入包括参考文件在内的整个目录。如果 SKILL.md 位于存储库的根目录，则您也可以直接链接到该文件（例如`https://github.com/org/repo/blob/main/SKILL.md`），该文件仅导入 SKILL.md。
+ **SKILL.md 必填 ** —该目录必须包含具有有效前缀（名称和描述）的 SKILL.md 文件。
+ **最大目录大小 **-总目录大小不得超过 6 MB。
+ **最大文件数 **-一个目录最多可以包含 100 个文件。
+ **GitHub 需要帐户 **-您的代理空间必须有关联的 GitHub 帐户才能导入技能。任何关联的 GitHub 帐户都允许从公共存储库导入。对于私有仓库，关联的账户必须具有对仓库的读取权限。

## 社区工具
<a name="community-tools"></a>

 GitHub 网站上的 [AWS DevOps Agent Tools 存储库](https://github.com/aws/tools-for-devops-agent)包含社区贡献的技能、自定义代理和 MCP 服务器，您可以按原样使用，也可以作为编写自己的技能的起点。存储库由 AWS DevOps 代理服务团队维护。所有贡献在添加之前都要经过相同的安全审查栏，因此您可以快速交付新功能，同时确保每个工具都符合 AWS 质量标准。要浏览可用内容，请参阅 GitHub 网站[上的](https://aws.github.io/tools-for-devops-agent/skills/)社区技能库。

可用技能包括：
+ AWS 健康事件调查
+ AWS 支持案例分析
+ 亚马逊虚拟私有云 (亚马逊 VPC) DNS 调查
+ 适用于 Apache Kafka（亚马逊 MSK）运营的亚马逊托管串流
+ 服务配额检查
+ 亚马逊 Elastic Kubernetes 服务（亚马逊 EKS）运营审查
+ 亚马逊关系数据库服务 (Amazon RDS) 运营审查

要使用社区技能，请执行以下操作：
+ **导入自 GitHub ** — 复制技能目录 URL 并将其粘贴到 Operator Web App 的 “从存储库导入” 流程中。有关详细信息，请参阅从存储库[导入技能](#importing-a-skill-from-a-repository)。
+ **以 zip ** 格式上传 — 克隆存储库，压缩技能目录，然后使用 “上传技能” 流程上传。有关详细信息，请参阅[上传技能](#uploading-a-skill)。

每项技能都包含一个自述文件，其中包含先决条件和使用说明。

该存储库还包括社区自定义代理和可部署的 MCP 服务器。有关详细信息，请参阅[社区自定义代理](custom-agents-creating-a-custom-agent.md)和[社区 MCP 服务器](configuring-integrations-and-knowledge-connecting-mcp-servers.md)。

## 管理技能
<a name="managing-skills"></a>

AWS DevOps 代理通过操作员 Web 应用程序提供全面的技能管理功能：

**列出技能 ** — 查看代理空间中的所有技能。**知识**页面的 ** “**技能” 选项卡显示技能名称、“活动” 或 “非活动” 状态、创建日期、上次更新日期和可用操作。

**查看技能 **-选择任何技能以查看其详细视图。在 UI 中创建的技能会显示可编辑的内容，您可以在其中直接在 UI 中修改名称、描述或说明，然后选择 “保存” 进行更新。以 zip 文件形式上传的技能会显示一个文件树，其中显示了 SKILL.md 所有其他目录，如引用/ 和 assets/。在树中选择文件以只读模式查看其内容。

**为技能选择代理 **-配置哪些代理类型在创建或编辑每种技能时可以使用每种技能。在代理类型下拉列表中，使用复选框选择一种或多种代理类型：**通用**（默认-适用于所有代理类型）、** On-demand**（对话式查询）、**事件分类**（初始事件评估）、**事件 RCA**（根本原因分析）、**事件缓解**（自动事件响应）或**评估**（主动建议）。默认情况下选择 “通用”，使所有代理类型均可使用该技能。针对特定代理的技能可减少上下文消耗，提高代理注意力。

**激活和停用技能 **-暂时禁用技能，但不使用 Active/Inactive 开关将其删除。打开技能详细信息视图并将开关切换到 “非活动”，以防止代理在保留所有内容和配置的同时加载技能详细信息以进行新的调查。 In-progress 继续使用该技能进行调查。切换回 “激活” 以使该技能立即再次可用。要以编程方式激活或停用技能，请参阅 “管理[资产” 页面](about-aws-devops-agent-managing-assets.md)上的激活和停用技能。

**更新技能 **-根据创建方式修改现有技能。对于在用户界面中创建的技能，在技能详细信息视图中选择 “编辑”，修改名称、描述或说明，然后选择 “保存” 进行更新。对于以 zip 文件形式上传的技能，请在本地修改文件、创建新的 zip 文件并上传新版本。

**删除技能 **-从代理空间中永久移除技能。打开技能列表视图，选择更多选项菜单 () 并选择 “删除”，查看有关永久删除的警告，键入技能名称进行确认，然后选择 “删除技能”。删除无法撤消。 In-progress 如果调查人员尝试加载已删除的技能，则可能会受到影响。对于以 zip 文件形式上传的技能，请先下载 zip 文件，然后将其作为备份删除。如果您可能再次需要该技能，可以考虑停用该技能，而不是将其删除。

## 从 Runbook 迁移
<a name="migrating-from-runbooks"></a>

现有的 Runbook 会自动迁移到 Skills，无需客户执行任何操作。当你的 Agent Space 过渡到技能模型时，所有运行手册都将转换为技能并显示在你的技能界面中。迁移后，您可以：
+ **查看迁移的技能 **-检查自动迁移是否正确转换了您的 Runbook。
+ **根据需要更新 **-直接在用户界面中编辑技能，以完善说明、更新描述或配置代理类型定位。
+ **使用参考资料进行扩展 ** — 对于可以从其他参考资料或架构图中受益的技能，请使用参考资料/或资产/目录将其重新创建为压缩上传技能。
+ **创建新技能 ** — 为 Runbook 之前未涵盖的调查工作流程添加新技能。

如果您在自动迁移的技能方面遇到任何问题或需要迁移后更新方面的帮助，请联系 AWS 支持部门。