# Create a Skill / Agent / Team Repository (/docs/create-skill-repo) Buda scans your GitHub repository and automatically discovers Skills, Agents, and Teams based on where you place specific manifest files. Browse community repositories at **[agentskills.io](https://agentskills.io)** and **[agentcompanies.io](https://agentcompanies.io)** for inspiration. This page is the **implementation guide**. * Use this page when you want to build the repo structure directly. * Use this page when you want to paste instructions into a coding agent. * If you want the business overview first, read [Sell Your Skills on Buda Marketplace](/en/docs/sell-skills). For Coding Agents [#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 [#rules-at-a-glance] Required [#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 [#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 [#rendering-rules] * Marketplace detail page uses `README.md` first * If `README.md` is missing, Marketplace falls back to `SKILL.md` / `AGENTS.md` Visibility rules [#visibility-rules] * Buyers do not see full Skill instructions before purchase * Private repositories are supported * Full implementation stays protected in your repo *** Repository layout [#repository-layout] This repository follows the [Agent Companies specification](https://agentcompanies.io/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:** | Type | Trigger file | Location | | ----- | ------------ | ------------------------------ | | Skill | `SKILL.md` | Anywhere in the repo tree | | Agent | `AGENTS.md` | Must be under `agents/{name}/` | | Team | `TEAM.md` | Must be under `teams/{name}/` | *** Skills — `SKILL.md` [#skills--skillmd] 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. For paid or commercial Skills, we strongly recommend adding a `README.md` in the same directory. By default, Buda shows `README.md` on the listing detail page. If no `README.md` exists, it falls back to `SKILL.md`. Recommended pattern [#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) ``` ```markdown --- 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 [#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` [#agents--agentsnameagentsmd] 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:** ```markdown --- 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:** | Field | Required | Description | | ------------- | -------- | ---------------------------------------------- | | `schema` | ✓ | Must be `agentcompanies/v1` | | `name` | ✓ | Display name in the Marketplace | | `slug` | ✓ | Stable identifier, matches the directory name | | `description` | ✓ | One-sentence summary on the listing card | | `skills` | ✓ | List of skill dependencies as `repo#skillName` | **Optional `README.md`:** If present, takes priority over `AGENTS.md` as the detail page body. *** Teams — `teams/{name}/TEAM.md` [#teams--teamsnameteammd] 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:** ```markdown --- 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:** | Field | Required | Description | | ------------- | -------- | --------------------------------------------- | | `schema` | ✓ | Must be `agentcompanies/v1` | | `name` | ✓ | Display name in the Marketplace | | `slug` | ✓ | Stable identifier, matches the directory name | | `description` | ✓ | One-sentence summary on the listing card | | `includes` | ✓ | Relative paths to member `AGENTS.md` files | **Optional `README.md`:** If present, used as the team's detail page body. *** Quick start [#quick-start] ```bash 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 [#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 [#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. | Company status | Listing behavior | | -------------- | --------------------------------------------------------------------- | | `pending` | Hidden from Marketplace, awaiting admin review | | `published` | All `pending` listings become visible. `draft` listings are excluded. | | `rejected` | All listings hidden | 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 [#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 **Draft listings are excluded from company approval.** When a Buda admin approves a company, only `pending` listings are published. `draft` listings remain hidden. **Install requires the file to exist on GitHub.** Since Buda fetches content at install time, if a listing's source file is deleted from GitHub, installation will fail even if the listing appears in the Marketplace. Always sync after removing content so affected listings are set to `draft`. *** After creating your repo [#after-creating-your-repo] 1. Go to [Developer Portal → Plugin Repos](/developer/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 [#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 [#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