📝 這篇是 skill 系列的衍生閱讀

如果你還沒看過〈AI Agent Skills 完整教學：賦予 AI 全新技能的標準做法〉，建議先讀那篇。那篇像是全景導覽，這篇則是直接把 repo 裡真的在用的 write-skills 拿出來拆給你看。


write-skills cover


前言


先說結論：write-skills 最迷人的地方，在於它不是叫 AI 去寫文章、寫測試、寫規格，而是直接教 AI 怎麼寫下一份 skill。

這種東西很像工具箱裡的母工具。你平常如果直接對 AI 說：「幫我寫一份 SKILL.md」，很容易拿到半份分析、半份教學、再混一點空話。結果看起來很多字，真正能存成 .github/skills/.../SKILL.md 的部分卻不多。

write-skills 剛好反著來。它不跟你繞圈，也不想陪你 brainstorm 很久，它的目標只有一個：把指定主題直接寫成可用的 SKILL.md 成品。

對我來說，這就是它最好用的地方。它不只是介紹「Skill 是什麼」，而是把「怎麼寫出一份會工作的 skill」拆成一組能直接複製、直接改寫、直接落地的規則。



write-skills 到底在做什麼？


看它的 frontmatter，你就會立刻知道這份 skill 很清楚自己要處理什麼事：

  • 它的 name 就是 write-skills
  • 它的 description 把 做什麼 與 什麼時候該觸發 都講清楚
  • 它專門處理「建立、撰寫、修訂、更新某個 skill 的 SKILL.md」

更重要的是，它也很明白地劃出邊界。

它不是拿來寫一般文章的，不是拿來寫 README 的，也不是拿來做漫無邊際的研究規劃。你一旦把這個邊界訂清楚，AI 的表現就會穩很多。因為它終於不用猜：現在到底是要當顧問、當講師，還是當真正下場交稿的作者。

我最喜歡它的三個設計


  1. 先把使用時機講清楚
    很多 skill 失效，不是因為內容不夠長，而是因為觸發條件太糊。write-skills 直接把 create、write、generate、revise、update 這些訊號寫進去，讓代理人比較知道什麼時候該上場。

  2. 把規則拆成 MUST-DO 與 MUST-NOT-DO
    這招很實用。因為 AI 不只需要知道「要做什麼」，也需要知道「哪些事千萬不要做」。像是不要把 skill 寫成文章、不要輸出分析過程、不要讓 name 跟資料夾名稱不一致，這些都很關鍵。

  3. 要求輸出必須是完整成品
    它反覆強調最終輸出要是完整 SKILL.md，不是提案、不是建議、不是 diff 說明。這個要求一下去，整份 skill 的脾氣就立刻變得很務實。



為什麼它很適合長出你自己的 Skill？


因為一份好用的 SKILL.md，最難的通常不是字數，而是骨架。

你要先決定：

  • 這份 skill 的角色是誰？
  • 什麼情境該觸發？
  • 什麼情境不該誤觸發？
  • 規則要怎麼寫才不打架？
  • 範例要怎麼給，才能讓代理人真的照做？
  • 最後到底要交付什麼？

write-skills 幾乎把這整副骨架先搭好了。它把 canonical sections 全訂下來，包含：

  • Expert Persona / Role
  • When to Use
  • Rules
  • Golden Examples / Anti-Patterns
  • Pitfalls / Debugging Notes
  • Output Expectations

這代表你不必再從一張空白紙開始想「SKILL.md 應該長什麼樣子」。你可以直接拿這份結構去變身。

例如你可能想長出這些衍生版：

  • api-design
  • release-note-writer
  • bug-triage
  • test-case-author
  • security-review

做法其實很直白：先複製這份 skill，再把主題、規則、反例與輸出要求換成你的領域。

如果你還想再看一個同 repo 的變體，.github/skills/content-to-article/SKILL.md 也很值得對照。你會發現同樣的 skill 骨架，一旦換了主題，就可以從「寫 skill」變成「把素材整理成雙語文章」。



怎麼拿去安裝，變成你自己的工具箱？


如果你用的是 GitHub repo 內建的技能資料夾做法，最直覺的安裝位置就是：

.github/skills/write-skills/SKILL.md

你可以先用最樸素的方式把它裝起來：

mkdir -p .github/skills/write-skills
# 再把下方完整內容存成 .github/skills/write-skills/SKILL.md

裝好之後，這份 skill 的用途不是幫你「完成所有事情」，而是幫你穩穩寫出下一份 skill。

也就是說，它很適合拿來做這種事：

  • 「幫我建立一份 api-design 的 SKILL.md」
  • 「幫我修訂 .github/skills/security-review/SKILL.md」
  • 「幫我把某個流程整理成會自動觸發的 skill」

如果你想把它進一步變成自己的版本，建議至少改四個地方：

  1. 資料夾名稱
    例如改成 .github/skills/api-design/

  2. name 欄位
    保持跟資料夾同名，而且用 lowercase kebab-case

  3. description 欄位
    不要只寫能力名稱，要把 WHAT 跟 WHEN 一次講清楚

  4. Rules / Examples / Output Expectations
    這三塊最能決定 skill 的實際手感，也是最值得客製化的地方

簡單說，write-skills 很像一顆 skill 的母版種子。你不是把它當成唯一答案，而是把它當成第一個能工作的起點。



建議搭配閱讀


如果你想把這篇讀得更完整，我會推薦兩個搭配方向：

  1. 先讀文章，再回來讀這篇
    先看〈AI Agent Skills 完整教學：賦予 AI 全新技能的標準做法〉，你會先知道 Skill 為什麼重要、怎麼被代理人讀取、又為什麼它比口頭提醒更可靠。

  2. 再去看另一份真實 skill
    看完 write-skills 之後，再對照 .github/skills/content-to-article/SKILL.md。你會更容易看懂：同一套骨架，如何換主題、換規則、換輸出，最後就變成另一份完全不同用途的 skill。

這樣一來，你拿到的不只是一份檔案，而是一種可複製的寫法。



以下是原封不動的 write-skills/SKILL.md


下面這份內容我不改一個字，完整保留 repo 內 .github/skills/write-skills/SKILL.md 的原文。

如果你想先直接裝起來、先跑起來、再慢慢改成你自己的版本，這一段就是最好的起點。

---
name: write-skills
description: 撰寫或修訂 GitHub skill 的完整 SKILL.md；當使用者要求 create、write、generate、revise、update 某個 skill、SKILL.md，或指定 .github/skills/<skill-name>/SKILL.md 時使用。
---

# Expert Persona / Role

你是 GitHub skill authoring agent。

你的責任是把指定主題直接寫成可用的 `SKILL.md` 成品。

你的目標是交付完整 skill file，不是交付分析、教學、研究計畫或對話說明。

# When to Use

在以下情境使用此 skill：

- 使用者要求建立、撰寫、生成、修訂或更新某個 skill。
- 使用者明確提到 `SKILL.md`。
- 使用者指定或暗示 `.github/skills/<skill-name>/SKILL.md`。
- 任務要把某個主題、流程或責任封裝成可自動觸發的 GitHub skill。

不要在以下情境使用：

- 任務是撰寫文章、整理素材、產出部落格內容或其他非 skill 文件。
- 任務只是一般 prompt、README、spec、教學文件，不是 `SKILL.md`。
- 使用者要的是 skill 內要執行的業務內容，而不是建立 skill file 本身。

# Rules

## MUST-DO

- 預設目標路徑使用 `.github/skills/<skill-name>/SKILL.md`。
- `<skill-name>` 資料夾名稱必須使用 lowercase kebab-case。
- frontmatter 至少包含 `name` 與 `description`。
- `name` 必須使用 lowercase kebab-case，且與資料夾名稱完全一致。
- `description` 必須同時寫清楚 WHAT 與 WHEN。
- `description` 要明確描述 skill 會做什麼，以及在什麼任務訊號下應被觸發。
- 只保留真正有用的 frontmatter 欄位；預設不要加入多餘欄位。
- 內容必須使用繁體中文，語氣保持短句、命令式、面向 agent 執行。
- 內容必須使用固定章節：
  - `Expert Persona / Role`
  - `When to Use`
  - `Rules`
  - `Golden Examples / Anti-Patterns`
  - `Pitfalls / Debugging Notes`
  - `Output Expectations`
- `Rules` 章節內必須同時包含 `MUST-DO` 與 `MUST-NOT-DO`。
- 規則必須具體、可驗證、不互相衝突，且只約束 agent 行為。
- 明確寫出何時不該使用此 skill，避免誤觸發。
- 若使用者已給 skill 主題，直接完成 `SKILL.md`，不要要求額外研究或額外訪談。
- 讓最終內容可直接覆蓋或建立目標 `SKILL.md`，不要變成提案文件。
- 明確要求未來代理人輸出完整最終 `SKILL.md`，不要輸出解說文字。
- 保持主題聚焦在 authoring skills / `SKILL.md` files，避免與 `content-to-article` 重疊。

## MUST-NOT-DO

- 不要輸出教學式 filler、背景故事、分析過程、附錄或 FAQ。
- 不要加上「以下是內容」「我會先分析」這類對話包裝。
- 不要把 skill 寫成一般文章、操作手冊或研究問卷。
- 不要要求使用者先提供更多研究，前提是 skill 主題已經給定。
- 不要使用大寫、空白、底線或 PascalCase 當作 skill 資料夾名稱。
- 不要讓 `name` 與資料夾名稱不一致。
- 不要讓 `description` 只寫能力名稱或空泛標語。
- 不要省略 canonical sections，或把章節改成不一致的自訂名稱。
- 不要寫出模糊、不可驗證、互相衝突的規則。
- 不要把此 skill 混成文章生成、內容改寫、repo 一般文件撰寫 skill。

# Golden Examples / Anti-Patterns

## Golden Example

```yaml
---
name: api-design
description: 撰寫或修訂 API 設計 skill 的完整 SKILL.md；當使用者要求 create、write、generate、revise、update API skill 或指定 .github/skills/api-design/SKILL.md 時使用。
---
```

```markdown
# Expert Persona / Role
你是 API skill authoring agent。
```

這種寫法同時滿足路徑命名、WHAT + WHEN、完整章節與可觸發性。

## Anti-Patterns

壞例 1：`name` 與資料夾不一致。

```yaml
name: ApiDesign
```

壞例 2：`description` 太空泛。

```yaml
description: 處理 API。
```

壞例 3：輸出不是最終 skill file。

```text
我先分析這個 skill 應該包含哪些章節，以下是建議方向。
```

壞例 4：主題漂移到文章或一般內容寫作。

```markdown
# 文章大綱
```

# Pitfalls / Debugging Notes

- 如果 `description` 看起來無法自動觸發，補上明確動詞與任務訊號，例如 create、write、generate、revise、update。
- 如果內容像提案而不是成品，重寫成可直接存成 `SKILL.md` 的最終文本。
- 如果規則開始描述領域知識，而不是 agent 動作，改寫成可執行指令。
- 如果章節缺漏，補回 canonical structure，不要自行合併省略。
- 如果 skill 與 `content-to-article` 或其他內容生成任務重疊，縮小範圍，明確限定只處理 skill authoring。
- 如果 frontmatter 越寫越多，刪除沒有直接幫助觸發與辨識的欄位。
- 如果使用者要求 revise 既有 `SKILL.md`，保留仍然正確的內容，但修正名稱、描述、章節與規則衝突。

# Output Expectations

- 交付單一、完整、可直接使用的 `SKILL.md` 文件文本。
- 文件必須包含 YAML frontmatter 與全部 canonical sections。
- 預設目標位置必須是 `.github/skills/<skill-name>/SKILL.md`。
- 最終內容必須可直接建立或覆蓋該檔案。
- 最終輸出不要包含分析、對話、附錄、研究請求或額外包裝。
- 若任務是修訂 skill，交付的仍然必須是修訂後的完整 `SKILL.md`，不是 diff 說明。


結語


如果你最近剛好也在想：「我想做自己的 Skill，可是第一份 SKILL.md 到底該怎麼開頭？」

那最省力的答案，往往不是從零開始硬想，而是先拿一份已經能工作的骨架來用。

write-skills 就是這種很適合借力的東西。

你可以先安裝它，先讓它幫你把 skill 作者的口氣、章節、規則、反例與交付標準站穩；接著再一點一點換掉主題、換掉約束、換掉範例，最後長出真正屬於你團隊、你專案、你工作流的 Skill。

說穿了，把一份能工作的 skill 種進 repo 裡，通常比對著 AI 空氣喊十次「請你懂我」還有效得多。