Roo-Code/cline_docs/marketplace/user-guide/05-adding-packages.md

Item Structure, Metadata, and Features

Overview

• Every component on the registry is an item.
• An item can be of type: mcp, mode, prompt, package
• Each item apart from package is a singular object, i.e: one mode, one mcp server.
• A package contains multiple other items
  • All internal sub-items of a package is contained in the binary on the package item metadata itself.
• Each item requires specific metadata files and follows a consistent directory structure.

Directory Structure

The registry structure could be the root or placed in a registry directory of any git repository, a sample structure for a registry is:

registry/
├── metadata.en.yml               # Required metadata for the registry
│
├── modes/                        # `mode` items
│   └── a-mode-name/
│       └── metadata.en.yml
├── mcps/                         # `mcp` items
├── prompts/                      # `prompt` items
│
└── packages/                     # `package` items
    └── a-package-name/
        ├── metadata.en.yml       # Required metadata
        ├── metadata.fr.yml       # Optional localized metadata (French)
        ├── modes/                # `a-package-name`'s internal `mode` items
        │   └── my-mode/
        │       └── metadata.en.yml
        ├── mcps/                 # `a-package-name`'s internal `mcp` items
        │   └── my-server/
        │       └── metadata.en.yml
        └── prompts/              # `a-package-name`'s internal `prompt` items
            └── my-prompt/
                └── metadata.en.yml

Metadata File Format

Metadata files use YAML format and must include specific fields:

registry:

name: "My Registry"
description: "A concise description for your registry"
version: "0.0.0"
author: "your name" # optional
authorUrl: "http://your.profile.url/" # optional

item:

name: "My Package"
description: "A concise description for your package"
version: "0.0.0"
type: "package" # One of: package, mode, mcp, prompt
sourceUrl: "https://url.to/source-repository" # Optional
binaryUrl: "https://url.to/binary.zip"
binaryHash: "SHA256-of-binary"
binarySource: "https://proof.of/source" # Optional, proof-of-source for the binary (tag/hash reference, build job, etc)
tags:
    - tag1
    - tag2
author: "your name" # optional
authorUrl: "http://your.profile.url/" # optional

Localization Support

You can provide metadata in multiple languages by using locale-specific files:

Important Notes on Localization:

• Only files with the pattern metadata.{locale}.yml are supported
• The Marketplace will display metadata in the user's locale if available
• If the user's locale is not available, it will fall back to English
• The English locale (metadata.en.yml) is required as a fallback
• Files without a locale code (e.g., just metadata.yml) are not supported

Configurable Support

Powered with Roo Rocket, the registry supports configurable items like:

• mcp with access token inputs.
• mode / prompt with feature flags.
• And further customizations that a creator can imagine.
  • E.g: a package could prompt you for the location of its context folder.

Contributing Process

To contribute your package to the official repository, follow these steps:

1. Fork the Repository

1. Visit the official Roo Code Packages repository: https://github.com/RooCodeInc/Roo-Code-Marketplace
2. Click the "Fork" button in the top-right corner
3. This creates your own copy of the repository where you can make changes

2. Clone Your Fork

Clone your forked repository to your local machine:

git clone https://github.com/YOUR-USERNAME/Roo-Code-Marketplace.git
cd Roo-Code-Marketplace

3. Create Your Item

1. Create a new directory for your item with an appropriate name
2. Add the required metadata files (and subitem directories for package)
3. Follow the structure and format described above
4. Add sourceUrl that points to a repository or post with info/document for the item.

Example of creating a simple package:

mkdir -p my-package/modes/my-mode
touch my-package/metadata.en.yml
touch my-package/README.md
touch my-package/modes/my-mode/metadata.en.yml

4. Test Your Package

Before submitting, test your package by adding your fork as a custom source in the Marketplace:

1. In VS Code, open the Marketplace
2. Go to the "Settings" tab
3. Click "Add Source"
4. Enter your fork's URL (e.g., https://github.com/YOUR-USERNAME/Roo-Code-Marketplace)
5. Click "Add"
6. Verify that your package appears and functions correctly

5. Commit and Push Your Changes

Once you're satisfied with your package:

git add .
git commit -m "Add my-package with mode component"
git push origin main

6. Create a Pull Request

1. Go to the original repository: https://github.com/RooCodeInc/Roo-Code-Marketplace
2. Click "Pull Requests" and then "New Pull Request"
3. Click "Compare across forks"
4. Select your fork as the head repository
5. Click "Create Pull Request"
6. Provide a clear title and description of your package
7. Submit the pull request

7. Review Process

After submitting your pull request:

1. Maintainers will review your package
2. They may request changes or improvements
3. Once approved, your package will be merged into the main repository
4. Your package will be available to all users of the Marketplace

Best Practices

• Clear Documentation: Include detailed documentation in your README.md
• Descriptive Metadata: Write clear, informative descriptions
• Appropriate Tags: Use relevant tags to make your package discoverable
• Testing: Thoroughly test your package before submitting
• Localization: Consider providing metadata in multiple languages
• Semantic Versioning: Follow semantic versioning for version numbers
• Consistent Naming: Use clear, descriptive names for components

Example package metadatas

Data Science Toolkit

Here's an example of a data science package:

data-science-toolkit/metadata.en.yml:

name: "Data Science Toolkit"
description: "A comprehensive collection of tools for data science workflows"
version: "1.0.0"
type: "package"
tags:
    - data
    - science
    - analysis
    - visualization
    - machine learning

data-science-toolkit/modes/data-scientist-mode/metadata.en.yml:

name: "Data Scientist Mode"
description: "A specialized mode for data science tasks"
version: "1.0.0"
type: "mode"
tags:
    - data
    - science
    - analysis

data-science-toolkit/prompts/data-cleaning/metadata.en.yml:

name: "Data Cleaning Prompt"
description: "A prompt for cleaning and preprocessing datasets"
version: "1.0.0"
type: "prompt"
tags:
    - data
    - cleaning
    - preprocessing

Previous: Working with Package Details | Next: Adding Custom Sources