📝 This is a companion piece in the skill series

If you have not read AI Agent Skills Complete Tutorial: The Standard Way to Give AI New Abilities yet, start there first. That article gives you the wide-angle view. This one zooms in on a real file from the repo: write-skills.


write-skills cover


Introduction


write-skills is fun because it is not a skill for writing blog posts, tests, or specs. It is a skill for teaching AI how to write the next skill.

That makes it feel like a parent tool inside the toolbox. If you ask AI, “Please write a SKILL.md for me,” you often get a strange mix of analysis, teaching notes, and motivational filler. It looks busy, but not all of it is ready to be saved as .github/skills/.../SKILL.md.

write-skills pushes in the opposite direction. It does not want to brainstorm forever. It does not want to hand you a proposal. It wants one thing: a usable SKILL.md deliverable.

That is what makes it powerful. It does not merely explain what a Skill is. It shows what a working skill file looks like when the boundaries, rules, examples, and output expectations are all pinned down.



What does write-skills actually do?


Its frontmatter tells the story immediately:

  • the name is write-skills
  • the description explains both what it does and when it should trigger
  • the target is specifically creating, writing, revising, or updating a skill SKILL.md

Just as importantly, it also draws a line around what it is not for.

It is not for general articles. It is not for README writing. It is not for open-ended research plans. Once that boundary is clear, the agent has far less room to guess. It no longer has to decide whether it should act like a consultant, a tutor, or a real file author. The job is explicit.

Three things it gets right


  1. It makes the trigger conditions concrete
    Many skills fail because they are vague about when they should wake up. write-skills bakes in signals like create, write, generate, revise, and update, which makes activation much more reliable.

  2. It separates MUST-DO from MUST-NOT-DO
    This is more important than it looks. AI needs a strong sense of both the required path and the forbidden path. “Do not turn this into an article” and “do not output analysis instead of the final file” are the kind of guardrails that change the result.

  3. It insists on a complete final deliverable
    The file keeps repeating the same message: the output must be a full SKILL.md, not a proposal, not a teaching note, and not a diff explanation. That one demand makes the whole skill feel practical.



Why is it such a good starter for your own skill?


Because the hardest part of a strong SKILL.md is usually not the word count. It is the skeleton.

You have to decide:

  • Who is this skill supposed to be?
  • When should it activate?
  • When should it stay quiet?
  • Which rules are testable and non-contradictory?
  • What examples will actually steer the agent?
  • What is the final output shape?

write-skills gives you that skeleton almost for free. It already locks in the canonical sections:

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

So you do not have to stare at a blank page and wonder what a proper skill file should even look like.

You can spin that structure into variants such as:

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

The move is simple: duplicate the structure, then swap in your own domain rules, anti-patterns, and output target.

If you want another real repo example after this one, compare it with .github/skills/content-to-article/SKILL.md. It uses a similar skeleton, but the mission shifts from writing skills to turning source material into bilingual articles.



How do you install it and turn it into your own toolkit?


If you are using the repo-local GitHub skill layout, the most natural installation path is:

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

You can install it the plain manual way:

mkdir -p .github/skills/write-skills
# then save the full file below as .github/skills/write-skills/SKILL.md

Once it is installed, the point is not to make it solve every problem directly. The point is to make it reliably author the next skill file.

That means it is a great fit for prompts like:

  • “Create an api-design SKILL.md for me.”
  • “Revise .github/skills/security-review/SKILL.md.”
  • “Turn this recurring workflow into a GitHub skill.”

If you want to evolve it into your own version, I would change at least four things on purpose:

  1. The folder name
    For example, .github/skills/api-design/

  2. The name field
    Keep it identical to the folder name, in lowercase kebab-case

  3. The description field
    Make sure it explains both WHAT the skill does and WHEN it should trigger

  4. The Rules, Examples, and Output Expectations
    Those three sections shape the real behavior of the skill more than anything else

In other words, write-skills works beautifully as a seed template. You do not have to treat it as the final answer. You can treat it as the first answer that already works.



Suggested companion reading


If you want the fullest payoff from this piece, I would pair it with two things:

  1. Read the broader article first
    AI Agent Skills Complete Tutorial: The Standard Way to Give AI New Abilities gives you the conceptual map: why skills matter, how agents discover them, and why they outperform vague verbal reminders.

  2. Then compare a sibling skill file
    After write-skills, open .github/skills/content-to-article/SKILL.md. It becomes much easier to see how the same structural logic can be retuned for a different domain and a different deliverable.

That way, you are not just collecting a file. You are learning a reusable pattern.



The exact original write-skills/SKILL.md


Below is the original repo file reproduced exactly as-is.

It stays in Traditional Chinese on purpose. If you want to install it first, use it first, and only customize it later, this is the cleanest place to start.

---
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 說明。


Conclusion


If you have been thinking, “I want my own Skill, but how do I even start the first SKILL.md?”

The easiest answer is usually not to invent everything from scratch. It is to borrow a working skeleton.

write-skills is exactly that kind of starter.

Install it. Let it stabilize the tone, sections, guardrails, anti-patterns, and output format for skill authoring. Then swap the topic, constraints, and examples until it becomes something that genuinely belongs to your own team, repo, and workflow.

In practice, planting one working skill into a repo is often more useful than asking AI ten times to “please understand me better.”