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 agents/{name}/AGENTS.md with valid frontmatter
• Every Team must include teams/{name}/TEAM.md with valid frontmatter

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 / AGENTS.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

This repository follows the Agent Companies specification.

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

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

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.

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
• Your know-how, prompt structure, and workflow design can stay protected in a private repo

Agents — agents/{name}/AGENTS.md

An agent is a pre-configured AI assistant with a specific role and a declared set of skills. The AGENTS.md file is required and contains both the agent's metadata (in frontmatter) and its instructions (in the markdown body).

AGENTS.md format:

---
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 information

Frontmatter fields:

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

Teams — teams/{name}/TEAM.md

A team is a collection of agents that collaborate on complex multi-step workflows. The TEAM.md file is required and contains both the team's metadata (in frontmatter) and an optional description body.

TEAM.md format:

---
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 fields:

Optional README.md: If present, used as the team's detail page body.

Quick start

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

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

Review and publishing

Buda uses a company-level review model. Individual listings cannot be published or unpublished directly — they always follow their company's status.

A Buda admin approves or rejects at the company level. When a company is approved, only listings that are pending are published — listings that are draft (content removed from GitHub) are intentionally excluded.

What happens when you update content

Buda indexes your repository — it stores metadata (name, description, GitHub URL) for each listing. When a user installs a skill or agent, Buda fetches the actual content from your GitHub repository at install time.

When you re-sync after making changes:

• Content updated → listing metadata updated, status unchanged, users get the latest content on next install
• File deleted from GitHub → listing set to draft, hidden from Marketplace. Users who already installed it keep their copy.
• File restored → listing moves from draft back to pending for re-review
• COMPANY.md removed (monorepo subdirectory deleted) → company and all its listings set to draft
• COMPANY.md restored → company moves back to pending for re-review

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 agents/
• Putting Teams outside teams/
• Missing schema: agentcompanies/v1 in AGENTS.md or TEAM.md frontmatter
• 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
• Each Agent has agents/{name}/AGENTS.md with schema: agentcompanies/v1 frontmatter
• Each Team has teams/{name}/TEAM.md with schema: agentcompanies/v1 frontmatter
• Private repo support is considered where IP protection matters