Buda LogoBuda

创建 Skill / Agent / Team 仓库

如何组织 GitHub 仓库,让 Buda 能自动发现并发布你的 Skills、Agents 和 Teams

创建 Skill / Agent / Team 仓库

Buda 扫描你的 GitHub 仓库,根据特定清单文件的位置自动发现 Skills、Agents 和 Teams。

访问 agentskills.ioskills.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

发现规则:

类型触发文件位置
SkillSKILL.md仓库任意位置
Agentagent.json必须在 .buda/agents/{name}/
Teamteam.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.mdREADME.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在市场中显示的名称
descriptionListing 卡片上的一句话描述
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在市场中显示的名称
descriptionListing 卡片上的一句话描述
agents成员 Agent 列表
agents[].repo包含该 Agent 的仓库 GitHub URL
agents[].agentNameAgent 名称(对应 .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 仓库中

创建仓库后

  1. 前往开发者中心 → 插件仓库
  2. 点击添加仓库并选择你的仓库
  3. Buda 扫描仓库并创建状态为 待审核 的 Listing
  4. Buda 团队在 24 小时内审核并通过
  5. 你的 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 面向执行逻辑
  • 涉及知识产权保护时优先考虑私有仓库

On this page