update-skill

update-skill

本指南提供在此儲存庫中建立或更新技能的說明。涵蓋必要的結構、frontmatter 以及技能的最佳實務。

快速開始

每個技能都是一個目錄，內含一個包含 YAML frontmatter 和 Markdown 主體的 SKILL.md 檔案：

---
name: pdf-processing
description: 從 PDF 檔案中擷取文字與表格、填寫表單、合併文件。
---

# PDF 處理

## 何時使用此技能
當使用者需要處理 PDF 檔案時使用此技能...

## 如何擷取文字
1. 使用 pdfplumber 進行文字擷取...

## 如何填寫表單
...

需求

Frontmatter（必要）

每個 SKILL.md 必須以 YAML frontmatter 開頭，包含：

• name：Kebab-case 識別碼（僅限小寫字母、數字、連字號）
  • 範例：add-feature-flag、pdf-processing、update-skill
• description：具體描述技能的功能與使用時機
  • 不可為空
  • 應包含技能發現的關鍵詞
  • 以動作動詞開頭，清楚說明技能達成的事項（例如「新增功能開關...」而非「協助功能...」），並立即接上具體的使用案例或情境（例如「用於處理功能開關時」）
  • 使用第三人稱（例如「新增功能開關...」而非「我可以幫你新增...」）

撰寫有效的描述

description 欄位對技能發現至關重要。請同時包含技能做什麼以及何時使用。一些好的範例：

• git-commit：「透過分析 git diff 產生描述性的提交訊息。用於使用者請求協助撰寫提交訊息或檢視暫存變更時。」
• pdf-processing：「從 PDF 檔案中擷取文字與表格、填寫表單、合併文件。用於處理 PDF 檔案或使用者提及 PDF、表單或文件擷取時。」

避免模糊的描述，例如「協助程式碼」或「執行開發任務」。更多背景資訊請參閱 references/best-practices.md 中的「描述最佳實務」。

技能結構

Warp 技能的典型章節：

1. 標題與簡要摘要 – 清晰的標題與技能目的及主要使用案例的簡潔概述。可連結至章節、參考檔案或相關技能（若有幫助）
2. 概述 – 關於技能目的的背景資訊（可選但常見），延伸摘要的細節與背景
3. 主要內容 – 步驟、使用說明或工作流程指引
4. 最佳實務 – 指引與建議（可選）
5. 範例 / 參考 PR – 實際範例的連結（可選）

根據技能需求保持結構彈性。簡單的技能可以省略可選章節。

驗證

可選用 skills-ref 參考函式庫來驗證你的技能：

skills-ref validate ./my-skill

這會檢查你的 SKILL.md frontmatter 是否有效並遵循所有命名慣例。若未安裝，請使用 WebSearch 工具取得此套件的相關背景資訊。

主要內容最佳實務

• 關於什麼是好的主要內容的指引，請參閱 references/best-practices.md 中的「簡潔原則」
• 格式化程式碼範例時，請參閱 references/best-practices.md 中的「程式碼範例格式化」。

檔案組織

• 簡單技能（<=200 行）：將所有內容保留在 SKILL.md 中
• 複雜技能（>200 行）：將詳細內容拆分至 references/ 子目錄
  • 從 SKILL.md 以清晰連結參考檔案
  • 範例：「詳細指引請參閱 references/best-practices.md」

何時拆分內容

在以下情況建立 references/ 子目錄：

• SKILL.md 接近 200 行以上
• 技能涵蓋多個領域或工作流程，可獨立載入
• 詳細的參考資料會使主要指令變得雜亂

僅將必要的工作流程與程序性指令保留在 SKILL.md 中。將詳細的參考資料、綱要與大量範例移至 references/ 檔案。

現有技能範例

關於結構與風格的參考：

• .agents/skills/add-feature-flag/SKILL.md - 具有清晰順序步驟的多步驟工作流程
• .agents/skills/remove-feature-flag/SKILL.md - 包含搜尋指令的清理工作流程

最佳實務

詳細的撰寫指引請參閱 references/best-practices.md，包括：

• 漸進式揭露模式
• 撰寫簡潔有效的指令
• 程式碼範例格式化
• 應避免的常見反模式