本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

AWS DevOps 代理程式技能是模組化的指令集，可根據您的基礎設施和操作工作流程量身打造專業領域知識和調查方法，來擴展代理程式的功能。

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

Skills 是包含 Markdown 指示的獨立目錄，可提供特殊功能給 AWS DevOps 代理程式。 AWS DevOps 代理程式支援[代理程式技能規格](https://agentskills.io/)的子集，這是封裝代理程式指示和資源的開放標準，僅支援不可執行的文件：Markdown 指示、PDFs、影像和資料檔案。

**注意**  
** 當您啟用沙盒 （預覽版） 時，技能也可以包含代理程式在沙盒環境中執行的可執行程式碼。如需詳細資訊，請參閱[設定沙盒](configuring-integrations-and-knowledge-sandbox.md)。

每項技能都需要一個 SKILL.md 檔案，其中包含您要為 AWS DevOps 代理程式提供的指示。除了必要的 SKILL.md 檔案之外，技能還可以包括：
+ 特定案例或基礎設施類型的**調查工作流程**。
+ **參考資料**，包括架構模式和操作程序。
+ **代理程式類型鎖定** – 技能可以鎖定特定代理程式類型 （通用、隨需、事件分類、事件 RCA、事件緩解、評估），以減少內容消耗並改善代理程式焦點。

## 為什麼要使用 Skills
<a name="why-use-skills"></a>

技能將一般用途助理中的 transform AWS DevOps 代理程式轉換為基礎設施和操作工作流程的專家。與聊天訊息中提供的一次性指示不同，技能是可重複使用的功能，可在與 AWS DevOps 代理程式執行的任務相關時自動載入。

**主要優點：**
+ **專用於您的代理程式** – Tailor AWS DevOps 代理程式，其中包含調查程序、最佳實務，以及專屬於基礎設施和營運模式的組織知識。
+ **減少重複** – 建立一次調查工作流程， AWS DevOps 代理程式會在所有相關調查中自動使用這些工作流程，無需重複提供相同的指引。
+ **編寫功能** – 結合多種技能來建置end-to-end調查工作流程。 AWS DevOps 代理程式會在執行期間讀取多種技能，例如從自訂 CI/CD 管道擷取部署的技能，以及搜尋程式碼儲存庫的技能。
+ **Amplify 自訂工具** – 建立技能，以有效地使用您的自訂 MCP 伺服器工具在 中引導 AWS DevOps 代理程式。技能可以記錄何時叫用特定工具、用於不同案例的參數，以及如何解譯結果以完成基礎設施特定的工作流程。

## 技能的運作方式
<a name="how-skills-work"></a>

當 AWS DevOps 代理程式遇到相關任務時，它會載入適當的技能並遵循指示來引導其調查。例如，「資料庫效能調查」技能可能包括step-by-step程序，讓代理程式有系統地檢查警示狀態、分析連線指標，以及識別慢速查詢。

## 技能結構
<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 格式撰寫的核心指示。此檔案應該：
+ 描述何時及如何使用技能。
+ 提供step-by-step調查程序。
+ 包含不同案例的決策樹。
+ 記錄預期的輸出和成功條件。

### Frontmatter
<a name="frontmatter"></a>

Frontmatter 是`SKILL.md`檔案頂端的中繼資料區塊，包含在`---`分隔符號之間。它包含 AWS DevOps 代理程式用來判斷在調查或任務期間何時啟用技能的 `name`和 `description` 欄位。

```
---
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.
---
```

**name** – 技能的唯一識別符。僅使用小寫字母、數字和連字號 （最多 64 個字元）。不得以連字號開頭或結尾。

**描述** – 詳細說明何時和為何 AWS DevOps 代理程式應該使用此技能。 AWS DevOps 代理程式會評估此欄位，以決定技能是否與目前的任務相關。即使指示撰寫良好，模糊或遺漏的描述也可能導致客服人員完全略過技能。

**重要** – 從客服人員的角度撰寫描述。包含應觸發技能的特定案例、服務、錯誤類型或症狀。例如，「在調查 Amazon RDS 執行個體的資料庫延遲、連線錯誤或查詢逾時時使用此技能」比「RDS 技能」更有效。

當您在 UI 中建立技能時，系統會自動從您提供的名稱和描述產生前綴。上傳為 zip 檔案的技能必須在 `SKILL.md` 檔案中包含前綴。

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

下列範例顯示調查 RDS 效能問題的完整、格式良好的技能。它示範了目錄結構、https：//SKILL.md 前綴、可執行的調查程序和補充參考檔案。

**目錄結構：**

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

**https：//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
```

**參考/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 代理程式會將其標記為**略過**。系統提供原因，說明篩選的原因。

下列範例顯示在排程維護期間略過低優先順序事件的技能：

**https：//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)。

您可以根據您的工作流程偏好設定和技能複雜性，以兩種方式建立技能：

若要透過 CLI AWS 或 AWS SDKs 以程式設計方式管理技能，請參閱 [管理資產](about-aws-devops-agent-managing-assets.md)。

### 在 UI 中建立技能
<a name="creating-a-skill-in-the-ui"></a>

在 AWS DevOps Agent Operator Web 應用程式中建立的技能在單一 SKILL.md 檔案中包含名稱、描述和指示。

**若要在 UI 中建立技能：**
+ 導覽至 Agent Space Operator Web 應用程式**的知識**頁面，然後選擇**技能**索引標籤。
+ 選擇**新增技能**。
+ 從模態中選取**建立技能**。
+ 填寫技能表單：
  + **名稱** – 僅限小寫字母、數字和連字號 （最多 64 個字元）。不得以連字號開頭或結尾。範例：`rds-throttling-investigation`
  + **描述** – 簡短說明何時使用此技能 （建議最少 100 個字元，最多 1，024 個字元）。這有助於客服人員判斷何時啟用技能。
  + **狀態** – 設定為作用中 （預設） 或非作用中。客服人員不會使用非作用中技能。
  + **客服人員類型** – 選取一個或多個可使用此技能的客服人員類型。依預設會選取**一般**，讓所有客服人員類型都能使用這項技能。若要鎖定特定客服人員，請取消選取一般，然後從中選擇：隨需、事件分類、事件 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 檔案的技能必須在 SKILL.md 中包含具有 `name`和 `description` 欄位的前綴。 AWS DevOps 代理程式會使用這些欄位來判斷何時啟用技能。如需撰寫有效前綴的詳細資訊，請參閱本主題稍早的前綴章節。

```
---
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)。
+ 選取一個或多個可使用此技能的代理程式類型 （依預設會選取通用，並套用到所有代理程式類型；取消選取以鎖定隨需、事件分類、事件 RCA、事件緩解或評估）。
+ 檢閱 zip 檔案需求和驗證結果。
+ 選擇「上傳」，將技能新增至您的客服人員空間。

**上傳為 zip 檔案之技能的重要限制：**
+ **目前不支援指令碼** – 包含 `scripts/`目錄中指令碼的技能會在上傳期間遭到拒絕。一旦代理程式可以存取安全編碼環境，就會在未來版本中啟用指令碼執行。
+ **大小限制** – zip 檔案大小總計不得超過 6 MB （包括所有檔案）。
+ **需要 SKILL.md ** – zip 檔案必須包含具有有效前端的 SKILL.md 檔案。

**命名技能的最佳實務：**

使用清晰的描述性名稱，例如 "rds-throttling-investigation"，而不是通用名稱。良好的技能名稱會反映其處理的特定案例或服務，讓您更輕鬆地一目了然地識別正確的技能。

### 從儲存庫匯入技能
<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 Enterprise Server 和 GitHub Enterprise Cloud。
+ 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 Enterprise Server 或 GitHub Enterprise Cloud，請改用執行個體的 URL，例如 `https://github.example.com/my-org/my-repo/tree/main/skills/rds-investigation`。
+ 選取一個或多個可使用此技能的代理程式類型。
+ 設定生命週期狀態 （作用中或非作用中）。
+ 選擇**匯入技能**。

AWS DevOps Agent 會擷取目錄內容、讀取 SKILL.md 前綴以擷取技能名稱和描述，並將所有檔案匯入您的 Agent Space。

**檢視匯入的技能：**

匯入的技能會出現在自訂技能清單中，其中包含來源儲存庫的連結。在技能詳細資訊檢視中：
+ 技能名稱和描述為唯讀 （由 SKILL.md 檔案管理）。
+ 指示和資源檔案會以唯讀模式顯示。
+ 狀態和客服人員類型仍可編輯。
+ 「上次同步」時間戳記會顯示技能上次從儲存庫同步的時間。

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

當您更新儲存庫中的技能檔案時，您可以同步匯入的技能以提取最新的變更：
+ 在詳細資訊檢視中開啟匯入的技能。
+ 選擇**同步**。
+ AWS DevOps 代理程式會從來源儲存庫重新擷取目錄內容，並更新技能內容。

您也可以在匯入的技能列上選擇同步，從技能清單檢視中**同步**。

**注意：**同步會將技能內容完全取代為儲存庫目錄的目前狀態。可編輯欄位 （狀態、客服人員類型） 的任何本機變更都會保留。

**限制條件**：
+ **URL 格式** – 僅接受 GitHub URLs，包括具有資料駐留的 GitHub Enterprise Server 和 GitHub Enterprise Cloud。連接的 GitHub 帳戶必須符合 URL 主機。例如，`github.example.com`連線只能從 `github.example.com` URLs匯入，不能從 `github.com` URLs匯入。您可以指向包含 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 代理程式工具儲存庫](https://github.com/aws/tools-for-devops-agent)包含社群貢獻的技能、自訂代理程式和 MCP 伺服器，您可以依原狀使用或做為撰寫自己的起點。儲存庫由 AWS DevOps Agent 服務團隊維護。所有貢獻都會在新增之前通過相同的安全審查列，因此您可以快速交付新功能，確保每個工具都符合 AWS 品質標準。若要瀏覽可用的項目，請參閱 GitHub 網站上的[社群技能圖庫](https://aws.github.io/tools-for-devops-agent/skills/)。

可用的技能包括：
+ AWS 運作狀態事件調查
+ AWS 支援案例分析
+ Amazon Virtual Private Cloud (Amazon VPC) DNS 調查
+ Amazon Managed Streaming for Apache Kafka (Amazon MSK) 操作
+ 服務配額檢查
+ Amazon Elastic Kubernetes Service (Amazon EKS) 操作審查
+ Amazon Relational Database Service (Amazon RDS) 操作審查

若要使用社群技能：
+ **從 GitHub 匯入** – 複製技能目錄 URL，並將其貼到 Operator Web 應用程式中的「從儲存庫匯入」流程。如需詳細資訊，請參閱[從儲存庫匯入技能](#importing-a-skill-from-a-repository)。
+ **上傳為 zip** – 複製儲存庫、壓縮技能目錄，並使用「上傳技能」流程進行上傳。如需詳細資訊，請參閱[上傳技能](#uploading-a-skill)。

每項技能都包含具有先決條件和使用說明的 README。

儲存庫也包含社群自訂代理程式和可部署的 MCP 伺服器。如需詳細資訊，請參閱[社群自訂代理程式](custom-agents-creating-a-custom-agent.md)和[社群 MCP 伺服器](configuring-integrations-and-knowledge-connecting-mcp-servers.md)。

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

AWS DevOps Agent 透過 Operator Web 應用程式提供全方位的技能管理功能：

**列出技能** – 檢視客服人員空間中的所有技能。**知識**頁面**技能**索引標籤會顯示技能名稱、作用中或非作用中狀態、建立日期、上次更新日期和可用的動作。

**檢視技能** – 選擇任何技能以查看其詳細資訊檢視。在 UI 中建立的技能會顯示可編輯的內容，您可以在其中直接在 UI 中修改名稱、描述或指示，然後選擇「儲存」進行更新。上傳為 zip 檔案的技能會顯示檔案樹狀目錄，其中顯示 SKILL.md 和參考/ 和資產/ 等任何其他目錄。選擇樹狀目錄中的檔案，以唯讀模式檢視其內容。

**選取技能的客服人員** – 設定哪些客服人員類型可以在建立或編輯時使用每項技能。在客服人員類型下拉式清單中，使用核取方塊選取一或多個客服人員類型：**一般** （預設 - 適用於所有客服人員類型）、**隨需 **（整合查詢）、**事件分類 **（初始事件評估）、**事件 RCA** （根本原因分析）、**事件緩解 **（自動化事件回應） 或**評估** （主動建議）。依預設會選取一般，讓所有客服人員類型都能使用這項技能。以特定代理程式為目標的技能可減少內容耗用量，並改善代理程式的焦點。

**啟用和停用技能** – 暫時停用技能，而不使用作用中/非作用中切換將其刪除。開啟技能詳細資訊檢視並切換切換到「非作用中」，以防止代理程式載入它以進行新的調查，同時保留所有內容和組態。進行中的調查會繼續使用技能。切換回「作用中」，讓技能立即再次可用。若要以程式設計方式啟用或停用技能，請參閱管理資產頁面上[的啟用和停用技能](about-aws-devops-agent-managing-assets.md)。

**更新技能** – 根據現有技能的建立方式來修改現有技能。對於在 UI 中建立的技能，請在技能詳細資訊檢視中選擇「編輯」、修改名稱、描述或指示，然後選擇「儲存」進行更新。對於上傳為 zip 檔案的技能，請在本機修改檔案、建立新的 zip 檔案，以及上傳新版本。

**刪除技能** – 從客服人員空間永久移除技能。開啟技能清單檢視，選擇更多選項選單 (⋮)，然後選擇「刪除」，檢閱永久刪除的相關警告，輸入要確認的技能名稱，然後選擇「刪除技能」。刪除無法復原。如果嘗試載入已刪除的技能，進行中的調查可能會受到影響。對於上傳為 zip 檔案的技能，請先下載 zip 檔案，然後再刪除 做為備份。如果可能再次需要，請考慮停用技能，而不是將其刪除。

## 從 Runbook 遷移
<a name="migrating-from-runbooks"></a>

現有的 Runbook 會自動遷移至 Skills，而不需要客戶動作。當您的客服人員空間轉換為技能模型時，所有 Runbook 都會轉換為技能，並出現在您的技能使用者介面中。遷移後，您可以：
+ **檢閱遷移的技能** – 檢查自動遷移是否已正確轉換您的 Runbook。
+ **視需要更新** – 直接在 UI 中編輯技能，以精簡指示、更新描述或設定代理程式類型目標。
+ **使用參考展開** – 對於可受益於其他參考資料或架構圖的技能，請使用參考/ 或資產/ 目錄將其重新建立為 zip 上傳技能。
+ **建立新的技能**：為 Runbook 先前未涵蓋的調查工作流程新增技能。

如果您遇到任何自動遷移的技能問題，或需要遷移後更新的協助，請聯絡 AWS Support。