Submitting an Entry

Step-by-step guide to adding your project to Awesome OpenCode

Follow these steps to submit your project, plugin, theme, agent, or resource to Awesome OpenCode.

Prerequisites

Before submitting, ensure:

• You have a GitHub account
• Your project is publicly accessible
• Your repository has been active within the last 6 months
• You’ve reviewed the contribution guidelines

Submission Process

1. Fork the Repository

   Fork the awesome-opencode repository to your GitHub account:

   # Navigate to GitHub and fork the repository
   # https://github.com/awesome-opencode/awesome-opencode
   

   Then clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/awesome-opencode.git
   cd awesome-opencode
   
2. Create a New Branch

   Create a descriptive branch name for your submission:

   git checkout -b add-my-project-name
   

   Use a branch name that describes what you’re adding, for example:

   • add-security-agent
   • add-dark-ocean-theme
   • add-database-mcp-server
3. Choose the Correct Category

   Determine which category folder your entry belongs in:

   • data/plugins/ - OpenCode plugins and extensions (JS/TS modules)
   • data/themes/ - Color schemes and visual themes
   • data/agents/ - AI agents and skills
   • data/projects/ - Standalone tools, GUIs, integrations
   • data/resources/ - Guides, templates, configurations, MCP servers
4. Create Your YAML File

   Create a new YAML file with a kebab-case name in the appropriate category folder:

   # Example for a plugin
   touch data/plugins/my-plugin-name.yaml
   

   File naming conventions:

   • Use lowercase with hyphens (kebab-case)
   • Be descriptive but concise
   • Match your project name when possible
   • Use .yaml extension (not .yml)
5. Add Required Fields

   Open your YAML file and add the four required fields:

   name: Your Project Name
   repo: https://github.com/owner/repo-name
   tagline: Short description under 120 characters
   description: Longer description explaining what it does and why it's useful.
   

   See the Schema Reference for all available fields.

6. Add Optional Fields

   Enhance your entry with optional fields:

   With Installation Instructions

   name: Database MCP Server
   repo: https://github.com/example/mcp-database
   tagline: MCP server for database access and querying
   description: A Model Context Protocol server for database access.
   
   scope:
     - global
     - project
   
   tags:
     - mcp-server
     - database
     - postgresql
   
   min_version: "1.0.0"
   
   homepage: https://example.com/docs
   
   installation: |
     ## Prerequisites
     - Node.js 18+
     - Database credentials
     
     ## Installation
     ```bash
     npm install -g @example/mcp-database
   
7. Validate Your Entry

   Run the validation script to ensure your YAML is valid:

   npm install
   node scripts/validate.js data/category/your-file.yaml
   

   The validator checks:

   • YAML syntax is correct
   • Required fields are present
   • Field types match the schema
   • Tagline is 120 characters or less
   • URLs are valid
   • Version format is correct (if specified)

   Fix all validation errors before submitting. GitHub Actions will automatically validate your submission and reject invalid entries.

8. Commit Your Changes

   Add and commit your new YAML file:

   git add data/category/your-file.yaml
   git commit -m "docs: add your-project-name to category"
   

   Use a clear commit message that follows the pattern:

   • docs: add project-name to plugins
   • docs: add theme-name to themes
   • docs: add agent-name to agents
9. Push to Your Fork

   Push your branch to your GitHub fork:

   git push origin add-my-project-name
   
10. Open a Pull Request

    1. Go to the awesome-opencode repository
    2. Click “Pull requests” → “New pull request”
    3. Click “compare across forks”
    4. Select your fork and branch
    5. Create the pull request with a clear title

    PR title examples:

    • “Add Security Agent to agents”
    • “Add Dark Ocean Theme to themes”
    • “Add Database MCP Server to resources”
11. Wait for Review

    A maintainer will review your submission:

    • Automated checks run first (validation, formatting)
    • Manual review follows (relevance, quality, completeness)
    • You may receive feedback requesting changes
    • Once approved, your entry is merged
    • The README.md automatically updates to include your entry

    Response time is typically 1-3 days.

After Your PR is Merged

Once merged:

• Your entry appears in the main README.md
• The Awesome OpenCode list is updated
• Your project gains visibility in the OpenCode community

Do NOT edit README.md directly. It is automatically generated from the YAML files. Your changes will be overwritten.

Updating Your Entry

To update an existing entry:

1. Follow the same fork and branch process
2. Edit your existing YAML file in data/category/
3. Update the fields that need changes
4. Validate, commit, and submit a new PR
5. Use a commit message like docs: update project-name description

Common Issues

Validation Fails

If validation fails:

• Read the error message carefully
• Check the Schema Reference for field requirements
• Ensure tagline is ≤ 120 characters
• Verify repository URL is valid and accessible
• Confirm all required fields are present

PR is Declined

Common reasons for declined PRs:

• Project is not relevant to OpenCode
• Repository has not been updated in 6+ months
• Entry is a duplicate
• Required fields are missing or incomplete
• Poor quality description or documentation

Review the guidelines and resubmit with improvements.

Need Help?

• Review example YAML files
• Check existing entries for reference
• Read the Schema Reference
• Open an issue to ask questions