建立技能 / 智慧體 / 團隊倉庫
如何組織 GitHub 倉庫結構,讓 Buda 能夠發現併發布你的技能、智慧體和團隊
Buda 會掃描你的 GitHub 倉庫,並根據你放置特定清單檔案的位置自動發現技能、智慧體和團隊。
前往 agentskills.io 和 agentcompanies.io 瀏覽社群倉庫,獲取靈感。
本頁面是實現指南。
- 當你想直接構建倉庫結構時,使用本頁。
- 當你想把指令貼上給程式設計智慧體時,使用本頁。
- 如果你想先了解商業概覽,請閱讀在 Buda 應用市場銷售你的技能。
面向程式設計智慧體
如果你正在使用程式設計智慧體,可以直接把本頁面的 URL 交給它。
本文件以實現規範的方式編寫,內容包括:
- 倉庫結構
- 必需檔案
- 推薦的
README.md/SKILL.md分工 - 渲染與可見性規則
- 私有倉庫指引
- 常見錯誤
- 輸出檢查清單
規則速覽
必需
- 每個技能都必須包含
SKILL.md - 每個智慧體都必須包含帶有效 frontmatter 的
agents/{name}/AGENTS.md - 每個團隊都必須包含帶有效 frontmatter 的
teams/{name}/TEAM.md
推薦
- 在每個商業技能旁新增
README.md - 用
README.md撰寫面向買家的文案 - 用
SKILL.md撰寫面向智慧體的指令 - 對付費或專有技能優先使用私有 GitHub 倉庫
渲染規則
- 應用市場詳情頁優先使用
README.md - 如果缺少
README.md,應用市場會回退到SKILL.md/AGENTS.md
可見性規則
- 買家在購買前看不到完整的技能指令
- 支援私有倉庫
- 完整實現始終保留在你的倉庫中受保護
倉庫佈局
本倉庫遵循 Agent Companies 規範。
my-repo/
├── COMPANY.md ← optional company root manifest
│
├── skills/ ← Skills (any layout works)
│ ├── keyword-research/
│ │ ├── SKILL.md
│ │ └── README.md ← optional detail/sales page
│ └── content-writer/
│ ├── SKILL.md
│ └── README.md
│
├── agents/ ← Agents live here
│ ├── research-assistant/
│ │ ├── AGENTS.md ← agent manifest + instructions (required)
│ │ └── README.md ← detail page body (optional, overrides AGENTS.md)
│ └── code-reviewer/
│ └── AGENTS.md
│
└── teams/ ← Teams live here
├── marketing-team/
│ ├── TEAM.md ← team manifest (required)
│ └── README.md ← detail page body (optional)
└── dev-team/
└── TEAM.md發現規則:
| 型別 | 觸發檔案 | 位置 |
|---|---|---|
| 技能 | SKILL.md | 倉庫樹中的任意位置 |
| 智慧體 | AGENTS.md | 必須位於 agents/{name}/ 之下 |
| 團隊 | TEAM.md | 必須位於 teams/{name}/ 之下 |
技能 —— SKILL.md
技能是一項可複用的能力,智慧體可以安裝並呼叫它。把 SKILL.md 放在倉庫中的任意位置。
詳情頁正文優先使用同一目錄下的 README.md(如果存在),否則回退到 SKILL.md 本身。
對於付費或商業技能,我們強烈建議在同一目錄中新增 README.md。
預設情況下,Buda 在列表項詳情頁展示 README.md。如果不存在 README.md,則回退到 SKILL.md。
推薦模式
讓這兩個檔案各司其職:
README.md= 面向買家的頁面,用於營銷、定位、截圖、用例和銷售文案SKILL.md= 面向智慧體的指令檔案,包含真正的執行邏輯
skills/keyword-research/
├── SKILL.md ← required: frontmatter (name, description) + instructions
└── README.md ← optional: richer detail page (overrides SKILL.md as body)---
name: Keyword Research
description: Discover high-intent keywords and cluster them by topic automatically.
---
# Keyword Research
## When to use this skill
Use when the user asks to research keywords or analyze search intent.可見性與智慧財產權保護
私有倉庫非常適合商業技能:
- 購買前,終端使用者看不到完整的技能指令
- 列表項詳情頁只展示你選擇呈現的內容,理想情況下通過
README.md呈現 - 你的技術訣竅、提示詞結構和工作流設計可以保留在私有倉庫中受保護
智慧體 —— agents/{name}/AGENTS.md
智慧體是一個預先配置好的 AI 助手,擁有特定角色和一組宣告的技能。AGENTS.md 檔案是必需的,其中既包含智慧體的後設資料(在 frontmatter 中),也包含它的指令(在 markdown 正文中)。
AGENTS.md 格式:
---
schema: agentcompanies/v1
name: Research Assistant
slug: research-assistant
description: A thorough research agent that finds, summarizes, and cites sources.
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
---
# Research Assistant
You are a research assistant. Find accurate information, summarize clearly, always cite sources.
## Behavior Rules
- Never fabricate sources
- Flag uncertain informationFrontmatter 欄位:
| 欄位 | 必需 | 描述 |
|---|---|---|
schema | ✓ | 必須為 agentcompanies/v1 |
name | ✓ | 在應用市場中顯示的名稱 |
slug | ✓ | 穩定識別符號,與目錄名一致 |
description | ✓ | 列表項卡片上的一句話摘要 |
skills | ✓ | 以 repo#skillName 形式列出的技能依賴 |
可選的 README.md: 如果存在,作為詳情頁正文時優先於 AGENTS.md。
團隊 —— teams/{name}/TEAM.md
團隊是一組在複雜的多步驟工作流中協作的智慧體。TEAM.md 檔案是必需的,其中既包含團隊的後設資料(在 frontmatter 中),也包含一段可選的描述正文。
TEAM.md 格式:
---
schema: agentcompanies/v1
name: Marketing Team
slug: marketing-team
description: A coordinated team for content strategy, copywriting, and distribution.
includes:
- ../agents/strategist/AGENTS.md
- ../agents/copywriter/AGENTS.md
- ../agents/analyst/AGENTS.md
---
# Marketing Team
A coordinated team for content strategy, copywriting, and distribution.Frontmatter 欄位:
| 欄位 | 必需 | 描述 |
|---|---|---|
schema | ✓ | 必須為 agentcompanies/v1 |
name | ✓ | 在應用市場中顯示的名稱 |
slug | ✓ | 穩定識別符號,與目錄名一致 |
description | ✓ | 列表項卡片上的一句話摘要 |
includes | ✓ | 指向成員 AGENTS.md 檔案的相對路徑 |
可選的 README.md: 如果存在,用作團隊的詳情頁正文。
快速開始
mkdir my-repo && cd my-repo
mkdir -p skills/my-skill agents/my-agent teams/my-team
# Create a skill
cat > skills/my-skill/SKILL.md << 'EOF'
---
name: My Skill
description: A brief description of what this skill does.
---
# My Skill
Instructions for the AI agent go here.
EOF
# Create an agent
cat > agents/my-agent/AGENTS.md << 'EOF'
---
schema: agentcompanies/v1
name: My Agent
slug: my-agent
description: A brief description of what this agent does.
skills:
- https://github.com/my-org/my-repo#my-skill
---
# My Agent
Instructions for the agent go here.
EOF
git init && git add . && git commit -m "Initial commit"
gh repo create my-repo --public --push私有倉庫
你的倉庫可以是私有的——Buda 通過 GitHub App 安裝令牌訪問它。安裝你列表項的使用者絕不會看到你的原始碼。
如果你想保護智慧財產權,這通常是最佳設定:
- 買家看不到你的倉庫原始碼
- 買家在購買前看不到完整的技能指令
- 你仍然可以通過
README.md呈現一個精美的銷售/詳情頁 - 你的專有實現始終保留在你的私有 GitHub 倉庫中
稽核與釋出
Buda 採用公司級稽核模式。單個列表項無法被直接釋出或取消釋出——它們始終跟隨所屬公司的狀態。
| 公司狀態 | 列表項行為 |
|---|---|
pending | 從應用市場中隱藏,等待管理員稽核 |
published | 所有 pending 列表項變為可見。draft 列表項被排除在外。 |
rejected | 所有列表項被隱藏 |
Buda 管理員在公司級別進行批准或拒絕。當一家公司獲批時,只有 pending 狀態的列表項會被髮布——draft 狀態(內容已從 GitHub 移除)的列表項會被有意排除。
更新內容時會發生什麼
Buda 會索引你的倉庫——它為每個列表項儲存後設資料(名稱、描述、GitHub URL)。當用戶安裝技能或智慧體時,Buda 會在安裝時從你的 GitHub 倉庫獲取實際內容。
當你在做出改動後重新同步時:
- 內容已更新 → 列表項後設資料更新,狀態不變,使用者在下次安裝時獲得最新內容
- 檔案已從 GitHub 刪除 → 列表項被設為
draft,從應用市場中隱藏。已安裝的使用者保留各自的副本。 - 檔案已恢復 → 列表項從
draft回到pending,等待重新稽核 - COMPANY.md 被移除(monorepo 子目錄被刪除)→ 公司及其所有列表項被設為
draft - COMPANY.md 已恢復 → 公司回到
pending,等待重新稽核
草稿(draft)列表項被排除在公司審批之外。 當 Buda 管理員批准一家公司時,只有 pending 列表項會被髮布。draft 列表項仍保持隱藏。
安裝要求檔案在 GitHub 上存在。 由於 Buda 在安裝時獲取內容,如果某個列表項的原始檔已從 GitHub 刪除,即便該列表項出現在應用市場中,安裝也會失敗。移除內容後請務必同步,以便受影響的列表項被設為 draft。
建立倉庫之後
- 前往 Developer Portal → Plugin Repos(開發者門戶 → 外掛倉庫)
- 點選 Add Repository(新增倉庫) 並選擇你的倉庫
- Buda 掃描它並建立狀態為
pending的列表項 - Buda 團隊在 24 小時內稽核並批准
- 你的列表項出現在應用市場中
常見錯誤
- 把
SKILL.md當作銷售頁面而非指令檔案 - 釋出付費技能卻沒有
README.md - 把智慧體放在
agents/之外 - 把團隊放在
teams/之外 AGENTS.md或TEAM.md的 frontmatter 中缺少schema: agentcompanies/v1- 誤以為買家在購買前能讀到完整的技能內容
輸出檢查清單
- 倉庫結構遵循 Buda 的發現規則
- 每個技能都有
SKILL.md - 商業技能還附帶
README.md README.md面向買家SKILL.md面向指令- 每個智慧體都有帶
schema: agentcompanies/v1frontmatter 的agents/{name}/AGENTS.md - 每個團隊都有帶
schema: agentcompanies/v1frontmatter 的teams/{name}/TEAM.md - 在涉及智慧財產權保護的場景中考慮了私有倉庫支援