Ecosystem & Marketplace Contribution Guide

Updated on 4/15/2026

title: "Lesson 19 | Ecosystem & Skill Marketplace Contribution Guide" summary: "A deep dive into the Open Source playbook: How to standardize, package, and publish your awesome open-source Skill to the agentskills.io marketplace." sortOrder: 190 status: "published"

Alright, this is the 19th article written for the Hermes Agent tutorial.

Subtitle: A deep dive into the Open Source playbook: How to standardize, package, and publish your awesome open-source Skill to the agentskills.io marketplace.

Learning Objectives

Welcome to the 19th lesson of the Hermes Agent tutorial! In this session, we will transition from being a "user" of Skills to a "creator" and "contributor." The true power of a robust Agent lies not just in its core framework, but in its thriving ecosystem. This chapter will guide you through the Hermes Agent community ecosystem and teach you step-by-step how to standardize and package the Skills you develop, ultimately publishing them to the official Skill Marketplace (agentskills.io) to share your ingenuity with developers worldwide.

After completing this lesson, you will be able to:

  1. Understand the Core Value of the Skill Marketplace: Grasp why a standardized Skill distribution platform is crucial for the entire ecosystem.
  2. Master the Standard Structure of a Publishable Skill: Learn all the elements a production-grade Skill package should contain, especially the skill.yaml manifest file.
  3. Become Proficient in skill.yaml Configuration: Gain a deep understanding of the meaning of each field in the manifest file, including metadata, entry points, dependencies, parameters, and permission declarations.
  4. Practice the Packaging and Publishing Workflow: Personally package a sample Skill from code into a distributable .tar.gz file and use the hermes CLI tool to publish it to the Marketplace.
  5. Learn Best Practices for Community Contribution: Understand how to write clear documentation and choose an appropriate license to make your Skill more easily accepted and used by the community.

Core Concepts Explained

Before we get hands-on, we need to understand a few core concepts that underpin the operation of the Skill Marketplace. These are not just technical details; they are the cornerstones that ensure the healthy and orderly development of the ecosystem.

1. Why is a Skill Marketplace necessary?

Imagine how we would find and install software without an App Store or PyPI. We might have to browse various GitHub repositories, manually handle complex dependencies, and even face security risks. The Skill Marketplace (our fictional official store is agentskills.io) solves the same problems:

  • Discovery & Distribution: It provides a centralized platform for developers to showcase their work and for users to easily search, discover, and one-click install the Skills they need.
  • Standardization & Quality Control: By defining a set of standard packaging specifications (e.g., must include a skill.yaml), it ensures all Skills have a consistent structure, making them easy for the Agent's core system to load and manage. Additionally, a pre-publication review process can guarantee the quality and security of Skills.
  • Versioning: It allows developers to iterate and update their Skills, and users can choose to install specific versions or upgrade smoothly, avoiding compatibility issues caused by Skill updates.
  • Dependency Management: The Marketplace can automatically handle the Python library dependencies required by a Skill. When a user installs a Skill, the Agent will automatically install the libraries specified in requirements.txt, greatly simplifying environment configuration.
  • Community Incentive: When developers' contributions are seen, used, and appreciated, it serves as a powerful incentive. Excellent Skill developers can build a reputation in the community, creating a virtuous cycle.

2. Anatomy of a Publishable Skill

A Skill ready for publication in the Marketplace is no longer just one or two Python files from your local development environment, but a rigorously structured and well-documented software package. A standard Skill package typically includes the following file structure:

my_awesome_skill/
├── __init__.py         # The core logic and entry point of the Skill
├── skill.yaml          # [CORE] The Skill's manifest file, describing all metadata
├── requirements.txt    # List of Python dependencies
├── README.md           # Detailed documentation
├── LICENSE             # Open-source license file
└── icon.png            # (Optional) Icon displayed in the Marketplace

Among these, skill.yaml is the soul of the entire package. It declares everything about the Skill to the Hermes Agent and the Marketplace system.

3. skill.yaml Manifest File Deep Dive

skill.yaml uses the YAML format, a human-readable data serialization standard. It tells the system how to load, configure, and execute your Skill. A complete skill.yaml file might include the following fields:

# Basic Metadata
name: "GitHubRepoInsights"
version: "1.0.0" # Follows Semantic Versioning
author: "Your Name <[email protected]>"
description: "A skill to fetch and display key statistics (stars, forks, open issues) for a given GitHub repository."

# Execution Configuration
entry_point: "GitHubRepoInsightsSkill" # The Skill class name defined in __init__.py

# Dependency Management
dependencies:
  python: ">=3.8"
  # requirements.txt is read automatically; this is reserved for more complex system-level dependencies
  system: [] 

# Parameter Definitions
# Defines the parameters the Skill can accept during execution, crucial for UI generation and API calls
parameters:
  - name: "repo_url"
    type: "string"
    description: "The full URL of the public GitHub repository (e.g., https://github.com/torvalds/linux)."
    required: true
    default: ""

# Permissions Declaration
# Explicitly declares the permissions required by the Skill to enhance security
permissions:
  - "network.http_request" # Declares permission to access the external network
  - "filesystem.read"      # (Example) Declares permission to read local files
  • name: The unique identifier for the Skill, typically using CamelCase.
  • version: Must follow the SemVer (Semantic Versioning) specification (MAJOR.MINOR.PATCH), e.g., 1.0.0. This is crucial for dependency management and updates.
  • author & description: Self-explanatory author information and a brief functional summary.
  • entry_point: Specifies the name of the main class in the __init__.py file that inherits from BaseSkill. The Agent uses this entry point to instantiate your Skill.
  • dependencies: Declares dependencies on Python versions or other system tools. More common Python library dependencies should be placed in requirements.txt.
  • parameters: This is key to making your Skill dynamic and configurable. The parameters defined here can be used to automatically generate input fields in the Agent's UI or serve as required arguments when calling the Skill via an API. Each parameter includes attributes like name, type, description, and required.
  • permissions: Security is paramount. Explicitly declare what permissions your Skill needs here. For instance, if your Skill needs to access the internet, you must declare network.http_request. During installation, the user will be prompted to grant these permissions, giving them final control.

💻 Practical Demo

Now, let's start from scratch and create a Skill called GitHubRepoInsights. It will accept a GitHub repository URL and return the number of stars, forks, and open issues for that repository. We will walk through the entire development, packaging, and publishing process.

Step 1: Create the Skill Project Structure

First, create the Skill's folder and necessary files in your working directory.

# Create the main directory
mkdir github_repo_insights

# Enter the directory
cd github_repo_insights

# Create the necessary files
touch __init__.py skill.yaml requirements.txt README.md LICENSE

Your directory should now look like this:

github_repo_insights/
├── __init__.py
├── LICENSE
├── README.md
├── requirements.txt
└── skill.yaml

Step 2: Write the Core Skill Logic (__init__.py)

Open the __init__.py file. This is where we will write the Python code that interacts with the GitHub API.

# __init__.py

import requests
import json
from hermes_agent.skills import BaseSkill, SkillResult

class GitHubRepoInsightsSkill(BaseSkill):
    """
    A skill to fetch and display key statistics for a GitHub repository.
    """

    def __init__(self):
        # Call the parent class's constructor
        super().__init__()
        # Set the base URL for the GitHub API
        self.api_base_url = "https://api.github.com/repos/"

    def _parse_repo_path(self, repo_url: str) -> str or None:
        """
        Helper function to parse 'owner/repo' from a full GitHub URL.
        Example: "https://github.com/torvalds/linux" -> "torvalds/linux"
        """
        try:
            parts = repo_url.strip().rstrip('/').split('/')
            if len(parts) >= 2 and parts[-2] and parts[-1]:
                return f"{parts[-2]}/{parts[-1]}"
            return None
        except Exception:
            return None

    def execute(self, parameters: dict) -> SkillResult:
        """
        The main execution method for the skill.
        """
        repo_url = parameters.get("repo_url")
        if not repo_url:
            return SkillResult(
                success=False,
                message="Error: 'repo_url' parameter is missing."
            )

        repo_path = self._parse_repo_path(repo_url)
        if not repo_path:
            return SkillResult(
                success=False,
                message=f"Error: Invalid GitHub repository URL format: {repo_url}"
            )

        # Construct the full API request URL
        api_url = f"{self.api_base_url}{repo_path}"

        try:
            # Make a network request, requires network.http_request permission
            self.logger.info(f"Requesting data from: {api_url}")
            response = requests.get(api_url, timeout=10)
            
            # Check if the request was successful
            response.raise_for_status() 

            data = response.json()

            # Extract the required information
            stars = data.get('stargazers_count', 'N/A')
            forks = data.get('forks_count', 'N/A')
            open_issues = data.get('open_issues_count', 'N/A')
            
            # Format the output
            result_message = (
                f"📊 GitHub Repo Insights for '{repo_path}':\n"
                f"⭐ Stars: {stars}\n"
                f"🍴 Forks: {forks}\n"
                f"🐞 Open Issues: {open_issues}"
            )
            
            return SkillResult(
                success=True,
                message=result_message,
                data={
                    "stars": stars,
                    "forks": forks,
                    "open_issues": open_issues
                }
            )

        except requests.exceptions.HTTPError as e:
            error_msg = f"Error fetching data from GitHub API: {e.response.status_code} {e.response.reason}"
            if e.response.status_code == 404:
                error_msg = f"Repository '{repo_path}' not found. Please check the URL."
            self.logger.error(error_msg)
            return SkillResult(success=False, message=error_msg)
        except Exception as e:
            self.logger.error(f"An unexpected error occurred: {e}")
            return SkillResult(success=False, message=f"An unexpected error occurred: {str(e)}")

Code Highlights:

  • We inherited from BaseSkill and implemented the execute method.
  • The execute method retrieves repo_url from the parameters dictionary.
  • We added a helper function _parse_repo_path to extract the owner/repo part from the full URL.
  • We used the requests library to call the GitHub API, which is the dependency we need to declare in requirements.txt.
  • It returns a SkillResult object containing a success status, a user-facing message, and structured data that can be used by other Skills.
  • It includes detailed error handling and logging, which is a good practice.

Step 3: Define Dependencies and the Manifest File

  1. requirements.txt: Our code uses the requests library, so edit the requirements.txt file and add this line:

    requests>=2.25.0

  2. skill.yaml: Now, let's fill out the crucial manifest file. Edit skill.yaml:

    name: "GitHubRepoInsights"
version: "1.0.0"
author: "Hermes AI Labs <[email protected]>"
description: "A skill to fetch and display key statistics (stars, forks, open issues) for a given public GitHub repository."

entry_point: "GitHubRepoInsightsSkill"

dependencies:
  python: ">=3.8"

parameters:
  - name: "repo_url"
    type: "string"
    description: "The full URL of the public GitHub repository (e.g., https://github.com/torvalds/linux)."
    required: true

permissions:
  - "network.http_request"

    This file perfectly describes our Skill: its identity, entry point, parameters, and required permissions.

Step 4: Finalize Documentation and License

  1. README.md: A good README file will make your Skill more popular.

    # GitHub Repo Insights Skill

This skill provides a quick way to get essential statistics for any public GitHub repository.

## Features

- Fetches Star count
- Fetches Fork count
- Fetches Open Issue count

## Usage

To use this skill, simply provide the full URL of a public GitHub repository.

**Example Input:**
`https://github.com/facebook/react`

**Example Output:**

    📊 GitHub Repo Insights for 'facebook/react': ⭐ Stars: 215000 🍴 Forks: 45000 🐞 Open Issues: 1200

  2. LICENSE: Choosing an open-source license is very important. The MIT License is a popular and permissive choice. Copy the text of the MIT License (which you can easily find online) into the LICENSE file.

Step 5: Package the Skill

All files are ready. Now we need to package the github_repo_insights folder into a .tar.gz file, which is the standard format accepted by the Marketplace. The filename should follow the format skill_name-version.tar.gz.

Go back to the parent directory of github_repo_insights and run the following command:

# Make sure you are outside the github_repo_insights folder
# Package the folder into github_repo_insights-1.0.0.tar.gz
tar -czvf github_repo_insights-1.0.0.tar.gz github_repo_insights/

After running the command, you will see a file named github_repo_insights-1.0.0.tar.gz. This is the Skill package we are ready to publish.

Step 6: Publish to the Skill Marketplace

The final step is to use the Hermes Agent's command-line tool, hermes, to publish our Skill.

  1. Log in to your developer account: First, you need to register a developer account on the agentskills.io website and generate an API Key. Then, log in via the CLI.

    hermes login

    The terminal will prompt you to enter the API Key obtained from the website.

    Enter your API Key from agentskills.io: [your_api_key_here]
Login successful. Your credentials have been saved.

  2. Publish the Skill: Use the hermes skills publish command and specify the path to your package file.

    hermes skills publish github_repo_insights-1.0.0.tar.gz

    If everything goes well, you will see output similar to this:

    Verifying package integrity... [OK]
Parsing skill.yaml manifest... [OK]
Uploading package to agentskills.io... [OK]

🚀 Success! Your skill 'GitHubRepoInsights' (v1.0.0) has been submitted for review.
You will receive an email notification once the review process is complete.
Submission ID: skill-sub-xxxxxxxxxxxx

At this point, you have successfully submitted your self-developed Skill to the official Marketplace! The next step is to wait for the community administrators to review it. Once approved, Hermes Agent users worldwide will be able to find and install your masterpiece from the Marketplace.

Commands Involved

# Create the project directory and files
mkdir github_repo_insights
cd github_repo_insights
touch __init__.py skill.yaml requirements.txt README.md LICENSE

# Package the Skill (run from the parent directory of github_repo_insights)
tar -czvf github_repo_insights-1.0.0.tar.gz github_repo_insights/

# Log in to your Hermes developer account
hermes login

# Publish the Skill package
hermes skills publish github_repo_insights-1.0.0.tar.gz

Key Takeaways

  • The Ecosystem is Core: The Skill Marketplace is the bridge connecting developers and users, and it is key to the prosperity of the Hermes Agent ecosystem.
  • skill.yaml is the Soul: This manifest file defines everything about your Skill and is the sole basis for the Agent to understand and run it. Ensure its content is accurate and complete.
  • Standardize the Structure: Follow the standard file structure of __init__.py, skill.yaml, requirements.txt, README.md, and LICENSE. This is a common language in the community.
  • Security First: Explicitly declare the permissions your Skill requires through the permissions field to respect user privacy and security.
  • Documentation is King: A clear README.md is the most effective way to help others understand and use your Skill.
  • The hermes CLI is Your Tool: Become proficient in using the hermes login and hermes skills publish commands to interact with the Marketplace.

Congratulations on completing this important step! Becoming an open-source contributor not only enhances your technical skills but also gives you a sense of belonging and accomplishment within the community. We look forward to seeing more of your awesome Skills on agentskills.io!

References