Sharing Skills on GitHub

Public Repository Structure

A publicly shared skills repository follows a layout that makes skills discoverable and installable without guidance from the author. Each skill lives in its own directory named by its slug. A library-level README explains what the repository contains and how to install each skill:

my-skills/
├── README.md               # What skills are here, how to install
├── CHANGELOG.md            # Library-level changes
├── review-pr/
│   ├── SKILL.md
│   └── references/
│       └── checklist.md
├── deploy-vercel/
│   ├── SKILL.md
│   └── scripts/
│       └── pre-deploy.sh
└── research/
    └── SKILL.md

One skill per directory, named by its slug. The library-level README explains install commands, prerequisites, and what each skill does — a consumer should be able to read it and decide whether any skill in the repo fits their need before installing. High-churn skills get their own CHANGELOG.md inside the skill directory; stable skills reference the library-level log.

The compatibility and license Fields

Two portable frontmatter fields communicate requirements and terms to anyone considering installing the skill:

compatibility declares what the skill requires — platform version, OS, required CLI tools, required accounts. The field accepts up to 500 characters. Most skills don't need it. When a skill has genuine environment requirements, be specific:

---
name: deploy-vercel
compatibility: Requires Vercel CLI >=34.0, Node.js >=18. macOS or Linux only. Requires a Vercel account.
license: MIT
---

Vague declarations ("works with most setups") give consumers no useful information. Specific ones let a consumer verify their environment before installing rather than discovering incompatibility at runtime.

license specifies the legal terms covering the skill. Use a standard SPDX identifier for clarity: MIT, Apache-2.0, CC-BY-4.0. Without a license declaration, the legal status of a shared skill is ambiguous for anyone who wants to use, modify, or redistribute it. Skills published to community registries are expected to carry a license field.

Contributing to the Skills Hub

The Skills Hub indexes skills from GitHub repositories, skills.sh, ClawHub, LobeHub, and .well-known endpoint indexes. Two paths make a skill available through the Hub:

GitHub tap (Hermes): Push your skill directory to a public GitHub repository. Other Hermes users add it as a tap source with one command:

hermes skills tap add owner/repo

Once added as a tap, individual skills install directly:

hermes skills install owner/repo/review-pr

Claude Code: Commit the skill to .claude/skills/ in a public repository. The repo becomes discoverable as a tap that anyone can add. Team members who clone the repo get project skills automatically with no tap setup required.

To publish your skill to the Hub from GitHub, use the Hermes publish command: hermes skills publish skills/my-skill --to github --repo owner/repo. This makes the skill available for others to install via the hermes skills tap add and hermes skills install commands.

Skills start at community tier by default. Trusted status in the Hub registry requires a contribution to the relevant registry's core. All Skills Hub installations trigger automated security scanning — exfiltration patterns, prompt injection payloads, and destructive command sequences are all checked. Results are written to an append-only lock file with content hashes, creating an auditable installation record.

Writing for Portability

If a skill targets both Claude Code and Hermes, write the base SKILL.md using only the six portable fields from the agentskills.io standard: name, description, license, compatibility, metadata, and allowed-tools. Platform-specific behavior lives in optional companion files:

• SKILL.claude.md — Claude Code extensions: hooks, paths, when_to_use, model, effort
• SKILL.hermes.md — Hermes extensions: platforms, requires_toolsets, metadata.hermes.*

Alternatively, maintain a single file with clearly commented platform-specific sections. Either approach prevents the base skill from failing on a platform that doesn't recognize extension fields it hasn't implemented.

Making Skills Installable

A skill with undocumented setup requirements is effectively broken for anyone who installs it. Three practices prevent silent install failures:

• Clear install instructions in README. State the exact commands: hermes skills tap add owner/repo then hermes skills install owner/repo/skill-name for Hermes; for Claude Code, copy to .claude/skills/skill-name/ or clone the repo with .claude/skills/ committed.
• Self-contained SKILL.md. Every dependency — API keys, CLI tools, required accounts — must appear in the compatibility field or the README. Undocumented dependencies are the leading cause of community skills that install without errors and then fail silently the first time they run.
• Makefile or install script for multi-skill repos. When a repository contains multiple skills, a script removes the manual step of copying the right directory to the right location — a step consumers frequently get wrong on the first attempt.