RSS 中文
⌕

Lesson 19 | Community Ecosystem & Skill Marketplace Contribution Guide

20 MIN READ | UPDATED: 2026-05-07

title: "Lesson 19 | Community Ecosystem & Skill Marketplace Contribution Guide" summary: "A deep dive into Open Source practices: 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 Open Source Practices: How to Standardize, Package, and Publish Your Awesome Open-Source Skill to the agentskills.io Marketplace.

Learning Objectives

Welcome to Lesson 19 of the Hermes Agent tutorial! In this lesson, we will transition from being "users" of Skills to "creators" and "contributors." 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 provide a step-by-step guide on how to standardize and package your self-developed Skill, ultimately publishing it to the official Skill Marketplace (agentskills.io) to share your ingenuity with developers worldwide.

Upon 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-ready Skill package should contain, especially the skill.yaml manifest file.
  3. Become Proficient in skill.yaml Configuration: Deeply understand the meaning of each field in the manifest file, including metadata, entry points, dependencies, parameters, and permission declarations.
  4. Practice Packaging and Publishing: Hands-on experience packaging an example Skill from code into a distributable .tar.gz package and publishing it to the Marketplace using the hermes CLI tool.
  5. Learn Best Practices for Community Contribution: Learn how to write clear documentation and choose appropriate licenses to make your Skill more easily accepted and used by the community.

Core Concepts Explained

Before we dive into hands-on work, we need to understand several core concepts that underpin the operation of the Skill Marketplace. These are not just technical details, but cornerstones for ensuring a healthy and orderly ecosystem.

1. Why Do We Need a Skill Marketplace?

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

  • Discovery & Distribution: Provides a centralized platform for developers to showcase their work, and allows 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., requiring skill.yaml), it ensures consistent structure across all Skills, making them easy for the Agent's core system to load and manage. Simultaneously, a pre-publication review process helps guarantee Skill quality and security.
  • Versioning: Allows developers to iterate and update their Skills, and users can choose to install specific versions or smoothly upgrade, avoiding compatibility issues caused by Skill updates.
  • Dependency Management: The Marketplace can automatically handle Python library dependencies required by Skills. When users install a Skill, the Agent will automatically install the libraries specified in requirements.txt, greatly simplifying environment configuration.
  • Community Incentive: Developers' contributions being seen, used, and appreciated is itself a powerful incentive. Excellent Skill developers can build reputation within the community, forming a virtuous cycle.

2. Anatomy of a Publishable Skill

A Skill ready for publication to the Marketplace is no longer just one or two Python files you developed locally, but a rigorously structured, comprehensively informed software package. A standard Skill package typically includes the following file structure:

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

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

3. skill.yaml Manifest File Deep Dive

skill.yaml uses 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 contain the following fields:

# 基础元数据 (Basic Metadata)
name: "GitHubRepoInsights"
version: "1.0.0" # 遵循语义化版本 (Semantic Versioning)
author: "Your Name <your.email@example.com>"
description: "A skill to fetch and display key statistics (stars, forks, open issues) for a given GitHub repository."

# 执行配置 (Execution Configuration)
entry_point: "GitHubRepoInsightsSkill" # 在 __init__.py 中定义的 Skill 类名

# 依赖管理 (Dependency Management)
dependencies:
  python: ">=3.8"
  # requirements.txt 会被自动读取，这里是为更复杂的系统级依赖预留
  system: [] 

# 参数定义 (Parameters Definition)
# 定义 Skill 在执行时可以接收的参数，这对于 UI 生成和 API 调用至关重要
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)
# 明确声明 Skill 需要的权限，增强安全性
permissions:
  - "network.http_request" # 声明需要访问外部网络的权限
  - "filesystem.read"      # (示例) 声明需要读取本地文件的权限
  • name: The unique identifier for the Skill, usually in CamelCase.
  • version: Must follow the SemVer (Semantic Versioning) specification (MAJOR.MINOR.PATCH). For example, 1.0.0. This is crucial for dependency management and updates.
  • author & description: Self-explanatory, author information and a functional summary.
  • entry_point: Specifies the name of the main class in the __init__.py file that inherits from BaseSkill. The Agent will use 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. Parameters defined here can automatically generate input fields in the Agent's UI, or serve as required arguments when calling the Skill via API. Each parameter includes attributes like name, type, description, required, etc.
  • permissions: Security comes first. Explicitly declare what permissions your Skill needs here. For example, if your Skill needs internet access, you must declare network.http_request. During installation, users will be prompted to authorize these permissions, giving them ultimate control.

💻 Hands-on Demonstration

Now, let's start from scratch and create a Skill called GitHubRepoInsights that can receive a GitHub repository URL and then return the repository's star count, fork count, and open issue count. We will go 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 necessary files
touch __init__.py skill.yaml requirements.txt README.md LICENSE

Now your directory looks like this:

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

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

Open the __init__.py file, where we will write the Python code to interact 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 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)}")

Key points of the code:

  • We inherit from BaseSkill and implement 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.
  • The requests library is used to call the GitHub API, which is precisely the dependency we need to declare in requirements.txt.
  • A SkillResult object is returned, containing the success status, a message for the user (message), and structured data (data) that can be used by other Skills.
  • Detailed error handling and logging are included, which is 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 in the crucial manifest file. Edit skill.yaml:

    name: "GitHubRepoInsights"
version: "1.0.0"
author: "Hermes AI Labs <contact@hermes-ai.dev>"
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: Complete Documentation and License

  1. README.md: A good README file makes 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 can be easily found 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 skill_name-version.tar.gz format.

Go back to the parent directory of github_repo_insights and execute 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 execution, you will see a file named github_repo_insights-1.0.0.tar.gz, which is our Skill package ready for publication.

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 agentskills.io 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 smoothly, 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 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 in the Marketplace.

Commands Involved

# Create 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 (execute in the parent directory of github_repo_insights)
tar -czvf github_repo_insights-1.0.0.tar.gz github_repo_insights/

# Log in to Hermes developer account
hermes login

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

Key Takeaways

  • Ecosystem is Core: The Skill Marketplace is a bridge connecting developers and users, and is key to the prosperity of the Hermes Agent ecosystem.
  • skill.yaml is the Soul: This manifest file defines everything about the Skill and is the sole basis for the Agent to understand and run your Skill. Ensure its content is accurate and complete.
  • Standardized Structure: Follow the standard file structure of __init__.py, skill.yaml, requirements.txt, README.md, LICENSE; this is a common language in the community.
  • Security First: Explicitly declare the permissions required by the Skill via the permissions field, respecting user privacy and security.
  • Documentation is King: A clear README.md is the most effective way for your Skill to be understood and used by others.
  • hermes CLI is Your Tool: Be proficient in using 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 allows you to find a sense of belonging and accomplishment in the community. We look forward to seeing more awesome Skills you develop on agentskills.io!

References