创建 Skill / Agent / Team 仓库
如何组织 GitHub 仓库,让 Buda 能自动发现并发布你的 Skills、Agents 和 Teams
创建 Skill / Agent / Team 仓库
Buda 扫描你的 GitHub 仓库,根据特定清单文件的位置自动发现 Skills、Agents 和 Teams。
访问 agentskills.io 和 skills.sh 浏览社区仓库获取灵感。
这篇是实现导向文档。
- 当你要直接搭仓库时,看这篇。
- 当你要把规范直接复制给 coding agent 时,看这篇。
- 如果你想先看商业模式和上架流程,先读 在 Buda 市场销售你的技能。
给 Coding Agent
如果你在使用 coding agent,可以直接把本页链接发给它。
这篇文档已经按“可执行规范”来写,包括:
- 仓库结构
- 必须文件
- 推荐的
README.md/SKILL.md分工 - 展示与可见性规则
- 私有仓库建议
- 常见错误
- 输出检查清单
规则速览
必须满足
- 每个 Skill 都必须有
SKILL.md - 每个 Agent 都必须有
.buda/agents/{name}/agent.json - 每个 Team 都必须有
.buda/teams/{name}/team.json
强烈建议
- 商业化 Skill 都加上同目录
README.md - 用
README.md写面向买家的展示文案 - 用
SKILL.md写面向 Agent 的执行指令 - 付费或专有 Skill 优先使用私有 GitHub 仓库
展示规则
- Marketplace 详情页优先显示
README.md - 如果没有
README.md,则回退显示SKILL.md
可见性规则
- 买家在购买前看不到完整 Skill 指令内容
- 支持私有仓库
- 完整实现逻辑保留在你的仓库内
仓库结构
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 的元数据和技能依赖。AGENTS.md 和 README.md 是可选的(用作详情页正文)。
agent.json 格式:
{
"name": "研究助手",
"description": "一个严谨的研究 Agent,负责查找、总结并引用信息来源。",
"skills": [
{
"repo": "https://github.com/buda-ai/buda-marketplace",
"skillName": "web-search"
},
{
"repo": "https://github.com/buda-ai/buda-marketplace",
"skillName": "summarizer"
},
{
"repo": "https://github.com/my-org/my-skills",
"skillName": "citation-formatter"
}
]
}字段说明:
| 字段 | 必填 | 说明 |
|---|---|---|
name | ✓ | 在市场中显示的名称 |
description | ✓ | Listing 卡片上的一句话描述 |
skills | ✓ | 技能依赖列表 |
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: 如果存在,用作团队详情页的正文内容。如果不存在,Listing 只显示 team.json 中的名称和描述。
快速开始
mkdir my-repo && cd my-repo
mkdir -p skills/my-skill .buda/agents/my-agent .buda/teams/my-team
cat > skills/my-skill/SKILL.md << 'EOF'
---
name: 我的技能
description: 简短描述这个技能的功能。
---
# 我的技能
AI 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 扫描仓库并创建状态为
待审核的 Listing - Buda 团队在 24 小时内审核并通过
- 你的 Listing 出现在应用市场
常见错误
- 把
SKILL.md写成销售页,而不是指令文件 - 付费 Skill 没有配
README.md - Agent 没有放在
.buda/agents/下 - Team 没有放在
.buda/teams/下 - 误以为买家购买前能看到完整 Skill 内容
输出检查清单
- 仓库结构符合 Buda discovery 规则
- 每个 Skill 都有
SKILL.md - 商业化 Skill 同时有
README.md README.md面向买家SKILL.md面向执行逻辑- 涉及知识产权保护时优先考虑私有仓库