Create a Skill / Agent / Team Repository

Buda scans your GitHub repository and automatically discovers Skills, Agents, and Teams based on where you place specific manifest files.

For Coding Agents

If you are using a coding agent, you can give it this page URL directly.

This document is written as an implementation spec, including:

• repository structure
• required files
• recommended README.md / SKILL.md split
• rendering and visibility rules
• private repo guidance
• common mistakes
• output checklist

Rules At A Glance

Required

• Every Skill must include SKILL.md
• Every Agent must include .buda/agents/{name}/agent.json
• Every Team must include .buda/teams/{name}/team.json

Recommended

• Add README.md beside every commercial Skill
• Use README.md for buyer-facing copy
• Use SKILL.md for agent-facing instructions
• Prefer private GitHub repos for paid or proprietary Skills

Rendering rules

• Marketplace detail page uses README.md first
• If README.md is missing, Marketplace falls back to SKILL.md

Visibility rules

• Buyers do not see full Skill instructions before purchase
• Private repositories are supported
• Full implementation stays protected in your repo

Repository layout

my-repo/
├── skills/                        ← Skills (any layout works)
│   ├── keyword-research/
│   │   ├── SKILL.md
│   │   └── README.md          ← optional detail/sales page
│   └── content-writer/
│       ├── SKILL.md
│       └── README.md
│
├── .buda/                         ← Agents & Teams live here
│   ├── agents/
│   │   ├── research-assistant/
│   │   │   ├── agent.json        ← agent manifest (required)
│   │   │   ├── AGENTS.md          ← instruction file (optional)
│   │   │   └── README.md          ← detail page body (optional, overrides AGENTS.md)
│   │   └── code-reviewer/
│   │       └── agent.json
│   └── teams/
│       ├── marketing-team/
│       │   ├── team.json        ← team manifest (required)
│       │   └── README.md          ← detail page body (optional)
│       └── dev-team/
│           └── team.json
│
└── README.md

Discovery rules:

Skills — SKILL.md

A skill is a reusable capability that agents can install and invoke. Place SKILL.md anywhere in the repo.

The detail page body uses README.md if present in the same directory, otherwise falls back to SKILL.md itself.

Recommended pattern

Use the two files for different jobs:

• README.md = buyer-facing page for marketing, positioning, screenshots, use cases, and sales copy
• SKILL.md = agent-facing instruction file with the real operating logic

This gives you a cleaner marketplace presentation while keeping the actual execution instructions separate.

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.

## What I can do
- Find keywords for a given topic
- Group by intent (informational, commercial, transactional)
- Estimate search volume and competition

## How to use
Ask: "Research keywords for [topic]"

Visibility and IP protection

Private repositories work well for commercial Skills:

• Before purchase, end users do not see the full Skill instructions
• The listing detail page shows what you choose to present, ideally through README.md
• Even after purchase, users typically need to enter the terminal/runtime environment to inspect the full Skill content in practice

That means your know-how, prompt structure, and workflow design can stay protected in a private repo while the listing still sells the value clearly.

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

An agent is a pre-configured AI assistant with a specific role and a declared set of skills. The agent.json file is required and defines the agent's metadata and skill dependencies. AGENTS.md and README.md are optional (used as the detail page body).

agent.json format:

{
  "name": "Research Assistant",
  "description": "A thorough research agent that finds, summarizes, and cites sources.",
  "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"
    }
  ]
}

Fields:

Optional AGENTS.md: The agent's instruction file — defines role, personality, and behavior rules. Used as the detail page body if no README.md is present.

Optional README.md: If present, takes priority over AGENTS.md as the detail page body.

---
# AGENTS.md example
---

# Research Assistant

You are a research assistant. Find accurate information, summarize clearly, always cite sources.

## Behavior Rules
- Never fabricate sources
- Flag uncertain information

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

A team is a collection of agents that collaborate on complex multi-step workflows. The team.json file is required and defines the team's metadata and members. README.md is optional (used as the body/detail page if present).

team.json format:

{
  "name": "Marketing Team",
  "description": "A coordinated team for content strategy, copywriting, and distribution.",
  "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"
    }
  ]
}

Fields:

Optional README.md: If present, it's used as the team's detail page body. If absent, the listing shows only the name and description from team.json.

Quick start

mkdir my-repo && cd my-repo
mkdir -p skills/my-skill .buda/agents/my-agent .buda/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

git init && git add . && git commit -m "Initial commit"
gh repo create my-repo --public --push

Private repositories

Your repository can be private — Buda accesses it via the GitHub App installation token. Users who install your listings never see your source code.

This is usually the best setup if you want to protect intellectual property:

• Buyers do not see your repository source code
• Buyers do not see the full Skill instructions before purchase
• You can still present a polished sales/detail page through README.md
• Your proprietary implementation remains in your private GitHub repository

After creating your repo

1. Go to Developer Portal → Plugin Repos
2. Click Add Repository and select your repo
3. Buda scans it and creates listings with status pending
4. The Buda team reviews and approves within 24 hours
5. Your listings appear in the Marketplace

Common mistakes

• Using SKILL.md as a sales page instead of an instruction file
• Publishing a paid Skill without README.md
• Putting Agents outside .buda/agents/
• Putting Teams outside .buda/teams/
• Assuming buyers can read the full Skill content before purchase

Output checklist

• Repo structure follows Buda discovery rules
• Each Skill has SKILL.md
• Commercial Skills also have README.md
• README.md is buyer-facing
• SKILL.md is instruction-facing
• Private repo support is considered where IP protection matters