mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-10-08 03:07:53 +00:00

Smartsheet-JB-Brown 39332513ae documentation updates

2025-04-14 15:00:14 -07:00

8.6 KiB

Raw Blame History

Adding Packages

This guide explains how to create and contribute your own packages to the Roo Code Package Manager. By following these steps, you can share your components with the community and help expand the ecosystem.

Package Structure and Metadata

Each package in the Package Manager requires specific metadata files and follows a consistent directory structure.

Directory Structure

The basic structure for a package is:

package-name/
├── metadata.en.yml       # Required metadata file (English)
├── metadata.fr.yml       # Optional localized metadata (French)
├── README.md             # Documentation for the package
├── modes/                # Directory for mode components
│   └── my-mode/
│       └── metadata.en.yml
├── mcp servers/          # Directory for MCP server components
│   └── my-server/
│       └── metadata.en.yml
└── prompts/              # Directory for prompt components
    └── my-prompt/
        └── metadata.en.yml

Metadata File Format

Metadata files use YAML format and must include specific fields:

name: "My Package"
description: "A detailed description of what this package does"
version: "1.0.0"
type: "package" # One of: package, mode, mcp server, prompt
tags:
    - tag1
    - tag2
items: # Only for packages AND when a subcomponent isn't located in the packages directory tree
    - type: "prompt"
      path: "../shared-prompts/data-analysis" # Reference to component outside package directory

Package Example in Source Tree

Here's how a package might look in the actual source tree:

Roo-Code-Packages/
├── shared-prompts/                # Shared prompts directory
│   └── data-analysis/
│       └── metadata.en.yml
│
└── data-toolkit/                  # Your package directory
    ├── metadata.en.yml            # Package metadata
    ├── metadata.fr.yml            # Localized metadata
    ├── README.md                  # Documentation
    ├── modes/                     # Modes directory
    │   └── data-analyst/
    │       └── metadata.en.yml
    └── mcp servers/               # MCP servers directory
        └── data-processor/
            └── metadata.en.yml

Required Fields

name: A clear, descriptive name for your component
description: A detailed explanation of what your component does
version: Semantic version number (e.g., "1.0.0")
type: Component type (one of: "package", "mode", "mcp server", "prompt")
tags: (Optional) Array of relevant tags for filtering
items: (Only for packages) Array of subcomponents with their type and path - when the path is not in the packages directory tree

The Items Array and External References

The items array in a package's metadata serves only one important purposes:

External Component References: It allows referencing components that exist outside the package's directory tree.

Components that are within the package's directory tree are implicitly included and will be found at runtime.

Referencing External Components

You can reference components from anywhere in the repository by using relative paths:

items:
    # Component within the package directory
    - type: "mode"
      path: "modes/my-mode"

    # Component outside the package directory (using relative path)
    - type: "prompt"
      path: "../shared-prompts/data-analysis"

    # Component from a completely different part of the repository
    - type: "mcp server"
      path: "../../other-category/useful-server"

This allows you to:

Create shared components that can be used by multiple packages
Organize components logically while maintaining package relationships
Reference existing components without duplicating them

How It Works

The path is relative to the package's directory
The Package Manager resolves these paths when loading the package
Components referenced this way appear as part of the package in the UI
The same component can be included in multiple packages

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 Package Manager 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

Contributing Process

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

1. Fork the Repository

Visit the official Roo Code Packages repository: https://github.com/RooVetGit/Roo-Code-Packages
Click the "Fork" button in the top-right corner
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-Packages.git
cd Roo-Code-Packages

3. Create Your Package

Create a new directory for your package with an appropriate name
Add the required metadata files and component directories
Follow the structure and format described above
Add documentation in a README.md file

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 Package Manager:

In VS Code, open the Package Manager
Go to the "Settings" tab
Click "Add Source"
Enter your fork's URL (e.g., https://github.com/YOUR-USERNAME/Roo-Code-Packages)
Click "Add"
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

Go to the original repository: https://github.com/RooVetGit/Roo-Code-Packages
Click "Pull Requests" and then "New Pull Request"
Click "Compare across forks"
Select your fork as the head repository
Click "Create Pull Request"
Provide a clear title and description of your package
Submit the pull request

7. Review Process

After submitting your pull request:

Maintainers will review your package
They may request changes or improvements
Once approved, your package will be merged into the main repository
Your package will be available to all users of the Package Manager

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

Here's a comprehensive example of a data science package that includes both internal components and references to external components:

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
items:
    # External components (outside this package directory)
    - type: "prompt"
      path: "../shared-prompts/data-cleaning"
    - type: "mcp server"
      path: "../../ml-tools/model-trainer"
    - type: "mode"
      path: "../visualization-tools/chart-creator-mode"

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

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

8.6 KiB Raw Blame History