建立 Skill / Agent / Team 倉庫

Buda 掃描你的 GitHub 倉庫，根據特定清單文件的位置自動發現 Skills、Agents 和 Teams。

給 Coding Agent

如果你在使用 coding agent，可以直接把本頁連結發給它。

這篇文件已經按「可執行規範」來寫，包括：

• 倉庫結構
• 必須文件
• 推薦的 README.md / SKILL.md 分工
• 展示與可見性規則
• 私有倉庫建議
• 常見錯誤
• 輸出檢查清單

規則速覽

必須滿足

• 每個 Skill 都必須有 SKILL.md
• 每個 Agent 都必須有 agents/{name}/AGENTS.md，且包含有效 frontmatter
• 每個 Team 都必須有 teams/{name}/TEAM.md，且包含有效 frontmatter

強烈建議

• 商業化 Skill 都加上同目錄 README.md
• 用 README.md 寫面向買家的展示文案
• 用 SKILL.md 寫面向 Agent 的執行指令
• 付費或專有 Skill 優先使用私有 GitHub 倉庫

展示規則

• Marketplace 詳情頁優先顯示 README.md
• 如果沒有 README.md，則回退顯示 SKILL.md / AGENTS.md

可見性規則

• 買家在購買前看不到完整 Skill 指令內容
• 支援私有倉庫
• 完整實作邏輯保留在你的倉庫內

倉庫結構

本倉庫遵循 Agent Companies 規範。

my-repo/
├── COMPANY.md                     ← 可選的公司根清單
│
├── skills/                        ← Skills（任意布局均可）
│   ├── keyword-research/
│   │   ├── SKILL.md
│   │   └── README.md          ← 可選詳情 / 銷售頁
│   └── content-writer/
│       ├── SKILL.md
│       └── README.md
│
├── agents/                        ← Agents 放這裡
│   ├── research-assistant/
│   │   ├── AGENTS.md              ← agent 清單 + 指令（必填）
│   │   └── README.md              ← 詳情頁正文（可選，優先於 AGENTS.md）
│   └── code-reviewer/
│       └── AGENTS.md
│
└── teams/                         ← Teams 放這裡
    ├── marketing-team/
    │   ├── TEAM.md                ← team 清單（必填）
    │   └── README.md              ← 詳情頁正文（可選）
    └── dev-team/
        └── TEAM.md

發現規則：

Skills — SKILL.md

Skill 是 Agent 可以安裝和調用的可複用能力，SKILL.md 可以放在倉庫任意位置。

詳情頁正文優先使用同目錄下的 README.md，如果不存在則使用 SKILL.md 本身。

建議做法

建議把兩個文件分開承擔不同職責：

• README.md = 面向買家的展示頁，用來寫行銷文案、定位、場景、賣點與銷售內容
• SKILL.md = 面向 Agent 的指令文件，保留真正的執行邏輯

skills/keyword-research/
├── SKILL.md      ← 必填：frontmatter（name、description）+ 指令內容
└── README.md     ← 可選：更豐富的詳情頁正文（優先於 SKILL.md）

---
name: 關鍵詞研究
description: 自動發現高意圖關鍵詞並按主題分類。
---

# 關鍵詞研究

## 何時使用
當用戶詢問關鍵詞研究或搜尋意圖分析時使用。

可見性與知識產權保護

私有倉庫非常適合商業化 Skill：

• 在使用者購買前，終端使用者看不到完整的 Skill 指令內容
• Listing 詳情頁展示的是你希望使用者看到的內容，最適合透過 README.md 來承載
• 你的 know-how、提示詞結構與工作流設計，可以放在私有倉庫裡得到較好的保護

Agents — agents/{name}/AGENTS.md

Agent 是具有特定角色和技能集的預配置 AI 助手。AGENTS.md 是必填的，frontmatter 包含 Agent 的元數據，markdown 正文是 Agent 的指令內容。

AGENTS.md 格式：

---
schema: agentcompanies/v1
name: 研究助手
slug: research-assistant
description: 一個嚴謹的研究 Agent，負責查找、總結並引用資訊來源。
skills:
  - https://github.com/buda-ai/buda-marketplace#web-search
  - https://github.com/buda-ai/buda-marketplace#summarizer
  - https://github.com/my-org/my-skills#citation-formatter
---

# 研究助手

你是一個研究助手。查找準確資訊，清晰總結，始終引用來源。

## 行為規範
- 不捏造資訊來源
- 對不確定的資訊進行標注

Frontmatter 欄位說明：

可選 README.md： 如果存在，優先於 AGENTS.md 用作詳情頁正文。

Teams — teams/{name}/TEAM.md

Team 是一組協作完成複雜多步驟工作流的 Agent 集合。TEAM.md 是必填的，frontmatter 包含團隊的元數據和成員列表。

TEAM.md 格式：

---
schema: agentcompanies/v1
name: 行銷團隊
slug: marketing-team
description: 負責內容策略、文案撰寫和分發的協作團隊。
includes:
  - ../agents/strategist/AGENTS.md
  - ../agents/copywriter/AGENTS.md
  - ../agents/analyst/AGENTS.md
---

# 行銷團隊

負責內容策略、文案撰寫和分發的協作團隊。

Frontmatter 欄位說明：

可選 README.md： 如果存在，用作團隊詳情頁的正文內容。

快速開始

mkdir my-repo && cd my-repo
mkdir -p skills/my-skill agents/my-agent teams/my-team

# 建立 skill
cat > skills/my-skill/SKILL.md << 'EOF'
---
name: 我的技能
description: 簡短描述這個技能的功能。
---

# 我的技能

AI Agent 的使用說明寫在這裡。
EOF

# 建立 agent
cat > agents/my-agent/AGENTS.md << 'EOF'
---
schema: agentcompanies/v1
name: 我的 Agent
slug: my-agent
description: 簡短描述這個 Agent 的功能。
skills:
  - https://github.com/my-org/my-repo#my-skill
---

# 我的 Agent

Agent 的指令寫在這裡。
EOF

git init && git add . && git commit -m "初始提交"
gh repo create my-repo --public --push

私有倉庫

你的倉庫可以是私有的 — Buda 透過 GitHub App 安裝令牌存取。安裝你 Listing 的使用者不會看到你的原始碼。

如果你希望保護知識產權，這通常是最推薦的方案：

• 買家看不到你的倉庫原始碼
• 買家在購買前看不到完整的 Skill 指令內容
• 你仍然可以透過 README.md 做一個完整的展示 / 銷售頁
• 你的專有實作仍然保留在私有 GitHub 倉庫中

審核與發布

Buda 使用 Company 級別的審核模型。單個 Listing 不能直接發布或下架——它們始終跟隨所屬 Company 的狀態。

Buda 管理員在 Company 級別進行審批。當 Company 被批准時，只有 pending 狀態的 Listing 會被發布——draft 狀態的 Listing（GitHub 內容已消失）會被有意排除。

更新內容後會發生什麼

Buda 索引你的倉庫——它為每個 Listing 儲存元數據（名稱、描述、GitHub URL）。當使用者安裝 skill 或 agent 時，Buda 在安裝時實時從你的 GitHub 倉庫獲取內容。

重新同步後：

• 內容更新 → Listing 元數據更新，狀態不變，使用者下次安裝時獲取最新內容
• 文件從 GitHub 刪除 → Listing 變為 draft，從 Marketplace 隱藏。已安裝的使用者保留其副本。
• 文件恢復 → Listing 從 draft 變回 pending，等待重新審核
• COMPANY.md 刪除（monorepo 子目錄刪除）→ 該 Company 及其所有 Listing 變為 draft
• COMPANY.md 恢復 → Company 變回 pending，等待重新審核

建立倉庫後

1. 前往開發者中心 → 插件倉庫
2. 點擊新增倉庫並選擇你的倉庫
3. Buda 掃描倉庫並建立狀態為 待審核 的 Listing
4. Buda 團隊在 24 小時內審核並通過
5. 你的 Listing 出現在應用市場

常見錯誤

• 把 SKILL.md 寫成銷售頁，而不是指令文件
• 付費 Skill 沒有配 README.md
• Agent 沒有放在 agents/ 下
• Team 沒有放在 teams/ 下
• AGENTS.md 或 TEAM.md 的 frontmatter 缺少 schema: agentcompanies/v1
• 誤以為買家購買前能看到完整 Skill 內容

輸出檢查清單

• 倉庫結構符合 Buda discovery 規則
• 每個 Skill 都有 SKILL.md
• 商業化 Skill 同時有 README.md
• README.md 面向買家
• SKILL.md 面向執行邏輯
• 每個 Agent 都有 agents/{name}/AGENTS.md，frontmatter 包含 schema: agentcompanies/v1
• 每個 Team 都有 teams/{name}/TEAM.md，frontmatter 包含 schema: agentcompanies/v1
• 涉及知識產權保護時優先考慮私有倉庫