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

發現規則：

類型	觸發文件	位置
Skill	`SKILL.md`	倉庫任意位置
Agent	`agent.json`	必須在 `.buda/agents/{name}/` 下
Team	`team.json`	必須在 `.buda/teams/{name}/` 下

Skills — `SKILL.md`

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

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

對於付費或商業化 Skill，我們強烈建議你在同目錄額外寫一個 README.md。

Buda 預設優先展示 README.md 作為 Listing 詳情頁正文；如果沒有 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 來承載
即使購買後，使用者通常也需要進入終端 / runtime 環境後，才會在實際使用中完整查看 Skill 內容

這代表你的 know-how、提示詞結構與工作流設計，可以放在私有倉庫裡得到較好的保護，同時又不影響你在 Marketplace 上銷售。

Agents — `.buda/agents/{name}/agent.json`

Agent 是具有特定角色和技能集的預配置 AI 助手。agent.json 是必填的，定義 Agent 的元數據和技能依賴。

agent.json 格式：

{
  "name": "研究助手",
  "description": "一個嚴謹的研究 Agent，負責查找、總結並引用資訊來源。",
  "skills": [
    {
      "repo": "https://github.com/buda-ai/buda-marketplace",
      "skillName": "web-search"
    },
    {
      "repo": "https://github.com/my-org/my-skills",
      "skillName": "citation-formatter"
    }
  ]
}

欄位說明：

欄位	必填	說明
`name`	✓	在市場中顯示的名稱
`description`	✓	Listing 卡片上的一句話描述
`skills[].repo`	✓	包含該技能的倉庫 GitHub URL
`skills[].skillName`	✓	技能名稱（對應包含 `SKILL.md` 的目錄名）

可選 AGENTS.md： Agent 的指令文件。如果沒有 README.md，用作詳情頁正文。

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

Teams — `.buda/teams/{name}/team.json`

Team 是一組協作完成複雜多步驟工作流的 Agent 集合。team.json 是必填的，定義團隊的元數據和成員列表。README.md 是可選的（如果存在，用作詳情頁正文）。

team.json 格式：

{
  "name": "行銷團隊",
  "description": "負責內容策略、文案撰寫和分發的協作團隊。",
  "agents": [
    {
      "repo": "https://github.com/my-org/my-agents",
      "agentName": "strategist"
    },
    {
      "repo": "https://github.com/my-org/my-agents",
      "agentName": "copywriter"
    },
    {
      "repo": "https://github.com/my-org/other-agents",
      "agentName": "analyst"
    }
  ]
}

欄位說明：

欄位	必填	說明
`name`	✓	在市場中顯示的名稱
`description`	✓	Listing 卡片上的一句話描述
`agents`	✓	成員 Agent 列表
`agents[].repo`	✓	包含該 Agent 的倉庫 GitHub URL
`agents[].agentName`	✓	Agent 名稱（對應 `.buda/agents/{agentName}/`）

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

快速開始

mkdir my-repo && cd my-repo
mkdir -p skills/my-skill .buda/agents/my-agent .buda/teams/my-team
git init && git add . && git commit -m "初始提交"
gh repo create my-repo --public --push

建立倉庫後

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

私有倉庫

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

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

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

常見錯誤

把 SKILL.md 寫成銷售頁，而不是指令文件
付費 Skill 沒有配 README.md
Agent 沒有放在 .buda/agents/ 下
Team 沒有放在 .buda/teams/ 下
誤以為買家購買前能看到完整 Skill 內容

輸出檢查清單

倉庫結構符合 Buda discovery 規則
每個 Skill 都有 SKILL.md
商業化 Skill 同時有 README.md
README.md 面向買家
SKILL.md 面向執行邏輯
涉及知識產權保護時優先考慮私有倉庫

建立 Skill / Agent / Team 倉庫

On this page