Sharing with the Community

+15 Mana ✨
Publishing a Custom Tap(DOCUMENTATION)skills.sh Submission Guide(TOOL)

Introduction

Once a skill works for you, sharing it is mostly a packaging decision. Hermes does not have a centralized publish command. Instead it integrates a handful of distribution shapes: custom GitHub taps, direct URLs, well-known endpoints, marketplaces. Each shape fits a different audience and a different trust model. Pick the one that matches your reach.

Key Concepts

  • Custom GitHub tap: A GitHub repo that holds many skills. Subscribers run hermes skills tap add <owner/repo> and get all of them.
  • Direct URL: A single SKILL.md hosted at any HTTPS URL. Subscribers run hermes skills install <url>.
  • Well-known endpoint: A site that publishes /.well-known/skills/index.json. Subscribers run hermes skills search <url> --source well-known.
  • Marketplace: A registry like skills.sh, LobeHub, or ClawHub that lists skills with discoverable metadata.
  • Trust: Community by default for taps, URLs, well-known. Trusted for the small known list of taps (openai/skills, anthropics/skills, huggingface/skills).

Real World Context

A platform team publishes their team-internal runbooks via a private GitHub tap (my-org/hermes-skills). Engineers add the tap, install runbooks, and the team can update them with regular Git workflows. The same team open-sources one general-purpose skill (pg-explain-review) by publishing it on skills.sh. A solo developer publishes their personal git-commit-style skill as a direct URL on their blog so any reader can install it in one line. Three distribution shapes, three audiences, all from the same standard.

Deep Dive

The most flexible distribution is a custom GitHub tap. The repo layout is small:

text
my-org/hermes-skills
├── README.md
└── skills/
    ├── deploy-runbook/
    │   └── SKILL.md
    ├── pg-explain-review/
    │   ├── SKILL.md
    │   └── references/
    │       └── lock-modes.md
    └── release-notes/
        └── SKILL.md

The skills/ path is the default; you can configure a different path per-tap if needed. Each subdirectory is one skill. The directory name becomes the install slug.

Subscribers add the tap once:

bash
hermes skills tap add my-org/hermes-skills
hermes skills search release
hermes skills install my-org/hermes-skills/release-notes

For a single-skill direct URL, drop the file anywhere HTTPS-reachable:

bash
# Publisher: just host the file
# https://example.com/git-commit-style/SKILL.md

# Subscriber: install with the URL
hermes skills install https://example.com/git-commit-style/SKILL.md
hermes skills install https://example.com/SKILL.md --name my-skill

Direct URLs are single-file only. If your skill has scripts or references, use a GitHub tap instead.

For a well-known endpoint, you publish /.well-known/skills/index.json on your site. Hermes can discover and install from it:

bash
hermes skills search https://your-docs.example.com --source well-known
hermes skills install well-known:https://your-docs.example.com/.well-known/skills/your-skill

This shape is best for vendors who already have a docs site and want skill discovery to follow the same URL.

For wider reach, publish to skills.sh, ClawHub, or LobeHub. Each has its own onboarding flow, but the underlying skill format does not change. The same SKILL.md that works as a tap entry works as a marketplace entry.

A few sharing considerations:

  • Trust starts at community for everything you publish. Subscribers will see a third-party warning panel on first install. That is appropriate. The exception is the small set of repos hardcoded to trusted trust (openai/skills, anthropics/skills, huggingface/skills).
  • Versioning is your responsibility. Bump the version field in your SKILL.md when you change behavior. Subscribers running hermes skills check will see drift and decide whether to update.
  • Document prerequisites loudly. If your skill requires an env var, a specific toolset, or an MCP server, say so in both the frontmatter and the body. Subscribers should not have to read your code to figure that out.
  • Pin a license. Add a LICENSE file to the tap repo so subscribers know the legal status.

Common Pitfalls

  1. Sharing without versioning: Subscribers cannot tell if a skill changed. Bumping version is two characters and saves confusion.
  2. Bundling secrets: Never commit API keys, even into private taps. Use required_environment_variables and let subscribers provide their own.

Best Practices

  1. Start with a private tap: It is the simplest path and gives you full review control. Move to a public marketplace only when you have a skill stable enough to deserve wider reach.
  2. Treat the README as a directory: One line per skill linking to its SKILL.md. Reviewers can scan the whole tap in seconds.

Summary

  • Hermes has no single publish command; distribution is a packaging choice.
  • Custom GitHub taps are the most flexible: many skills, one subscribe command.
  • Direct URLs distribute single-file skills via HTTPS.
  • Well-known endpoints embed skill discovery in an existing docs site.
  • Marketplaces (skills.sh, ClawHub, LobeHub) extend reach but use the same SKILL.md format.

Code Examples

bash
# Publishing a tap (the publisher's perspective)
cd ~/code
git init my-org-hermes-skills
cd my-org-hermes-skills
mkdir -p skills/release-notes skills/pg-explain-review
# ... copy SKILL.md files in ...
git add . && git commit -m 'initial tap'
gh repo create my-org/hermes-skills --public --source=. --remote=origin
git push -u origin main

# Subscribing (anyone running Hermes)
hermes skills tap add my-org/hermes-skills
hermes skills list --source hub
hermes skills install my-org/hermes-skills/release-notes

# Update flow (publisher pushes, subscribers pull)
hermes skills check
hermes skills update
✓ Completed