Hermes SkillForge — Universal Agent Skill Converter

Convert any skill, repository, or tool into an install-ready Hermes Agent skill.

Agent Skills → Claude Skills → Codex → Cursor Rules → MCP Servers → Prompt Packs → GitHub Repos → Plugins → Hermes Skills

Installation · Quick Start · Features · Docs · Contributing · License

What is Hermes SkillForge?

Hermes SkillForge is an open-source, zero-dependency conversion engine that transforms diverse AI-agent source formats into valid, install-ready Hermes Agent skills that follow the official authoring standards and pass automated validation and testing.

Whatever you have — an agentskills.io skill, a Claude or Codex skill, Cursor rules, an MCP server manifest, a GitHub repository containing an agent workflow, a plugin, a prompt pack, or a script collection — SkillForge analyzes it, maps its capabilities, generates a compliant SKILL.md, builds a per-skill test suite, and installs it into ~/.hermes/skills/.

Live demo (real output)

$ skillforge convert ./examples/agentskills-source

== Source analysis ==
Format: agent_skills (confidence: medium, score: 2.0)
  - SKILL.md at SKILL.md
  - 1 Python file(s) with function definitions
Capabilities:
  commands: 0, dependencies: 0, scripts: 1, API endpoints: 0, config keys: 1

== Conversion complete ==
Generated: /tmp/hermes-demo1/skillforge/text-transform-pipeline
Dirs created: ['scripts/', 'references/', 'tests/']

== Validation ==
VALID

== Tests ==
passed: 18/18

Action: fresh -> ~/.hermes/skills/software-development/text-transform-pipeline
Installed. Active in a new session; run /reset for the current one.

Features

Core capabilities

| Feature | Description | |---|---| | Universal format detection | Scored multi-evidence classifier recognizes 20+ formats including SKILL.md, mcp-server.json, plugin.yaml, .mdc Cursor rules, *.mcp.json, and GitHub repo conventions | | Official Hermes SKILL.md generation | Modern section order (When to Use → Procedure → Verification), frontmatter, and the 60-character description budget enforced automatically | | Per-skill test generation | Every converted skill ships a tests/ pytest suite covering structure, scripts, dependencies, invalid inputs, and missing files | | 0–100 quality scoring | Validation state, test pass rate, frontmatter completeness, and description budget compliance are scored numerically | | Auto-repair engine | Iterates targeted fixes (name collisions, frontmatter fences, missing references, placeholder scripts) with a full attempt history and blocker report | | Secret detection & redaction | API keys, tokens, and passwords are detected, redacted from output, and reported in references/security-findings.md | | Safe placeholder handling | Host-dependent scripts (rsync, npm, kubectl, GUI tools) are statically validated instead of executed, so conversion never fails on unrunnable workflows | | MCP-to-skill conversion | Tools are extracted from manifests and surfaced in the skill's Procedure; secret-backed config keys become metadata.hermes.config prompts | | Zero dependencies | The engine is pure Python 3.10+ stdlib — no pip install required, no network calls at runtime | | Rollback & conflict safety | Installs snapshot previous versions and detect naming conflicts before overwriting |

Supported source formats

| Category | Formats | |---|---| | Agent skill standards | agentskills.io SKILL.md, Claude Skills, Codex skills, Cursor rules (.mdc), .claude/.codex/.agents conventions | | Repository sources | GitHub repos with agent workflows, plugin repositories (plugin.yaml, register()), script collections | | Integrations | MCP server manifests (mcp-server.json, *.mcp.json, mcpServers/tools JSON), REST API specs | | Knowledge sources | Prompt packs, rules files, markdown documentation, YAML/JSON configs | | Existing skills | Already-valid Hermes skills (re-import, upgrade, or validate) |

Architecture

The pipeline flows analyze → convert → validate → repair → test → install. The repair stage loops back to validate until the skill is clean or a genuine blocker is reported, and every unmapped capability is preserved in README.md and references/unmapped-functionality.md — nothing is ever silently dropped.

Installation

SkillForge is distributed on npm under @uthyagent/hermes-skillforge and can be installed with any major JavaScript/Node toolchain. Python ≥ 3.10 is the only runtime requirement (the engine itself is stdlib-only).

npm

npm install -g @uthyagent/hermes-skillforge
skillforge --help

Yarn

yarn global add @uthyagent/hermes-skillforge
skillforge --help

pnpm

pnpm add -g @uthyagent/hermes-skillforge
skillforge --help

Bun

bun add -g @uthyagent/hermes-skillforge
skillforge --help
# or run directly from this repo:
bun run main.bun.js convert <source>

Deno

# No install needed — run directly against the repo:
git clone https://github.com/uthumany/hermes-skillforge.git
cd hermes-skillforge
deno run --allow-read --allow-write --allow-env Deno.ts convert <source>

npx (no install at all)

npx -y @uthyagent/hermes-skillforge convert <source>

Rush

# Add to your monorepo rush.json projects:
#   { "packageName": "@uthyagent/hermes-skillforge", "projectFolder": ".", "shouldPublish": true }
rush add -p @uthyagent/hermes-skillforge

Lerna

# Inside a Lerna monorepo, add to package.json dependencies:
npm install @uthyagent/hermes-skillforge
npx lerna run test --scope @uthyagent/hermes-skillforge

Volta (version-pinned)

volta install node
volta install @uthyagent/hermes-skillforge
skillforge --help

Install directly from GitHub (Python)

git clone https://github.com/uthumany/hermes-skillforge.git
cd hermes-skillforge/skill
python3 scripts/skillforge.py convert <source>

Quick Start

# Analyze any source (URL, repo, directory, or ZIP)
skillforge analyze <url-or-path>

# Full pipeline: import → analyze → convert
skillforge import <url-or-path>

# Convert only, then validate and test
skillforge convert <source>
skillforge validate
skillforge test

# Preview the generated SKILL.md
skillforge preview

# Install into ~/.hermes/skills/<category>/
skillforge install

# Convert every convertible source under a directory
skillforge batch ./my-sources/

# Rolled back? Restore a previous install
skillforge rollback

Every converted skill lands in ~/.hermes/skills/<category>/ and becomes active in the next Hermes Agent session (run /reset for the current one).

Usage Examples

Example 1 — Convert an agentskills.io skill

skillforge convert ./examples/agentskills-source
skillforge validate            # VALID
skillforge test                # passed: 18/18
skillforge install             # -> ~/.hermes/skills/software-development/text-transform-pipeline

Example 2 — Convert a GitHub repo with an agent workflow

git clone <agent-workflow-repo>
skillforge convert ./agent-workflow-repo
# Detected: shell scripts + workflow README
# Generated SKILL.md preserves review.sh / post-comment.sh,
# redacts GH_TOKEN, and lists the remote deploy steps as references

Example 3 — Convert an MCP server into a Hermes skill

skillforge convert ./examples/mcp-source
# Detected: mcp_server (high confidence, score 4.5)
# tools weather_current / weather_forecast extracted into the Procedure;
# WEATHER_API_KEY surfaced as a config prompt in SKILL.md frontmatter

Folder Structure

hermes-skillforge/
├── bin/skillforge              # CLI entrypoint (npm bin)
├── docs/architecture.d2|svg    # Pipeline architecture diagram
├── examples/                   # Example source fixtures
│   ├── agentskills-source/     # agentskills.io-compatible skill
│   ├── workflow-repo-source/   # GitHub-style repo with agent workflow
│   └── mcp-source/             # MCP server manifest (mcp-server.json)
├── skill/                      # The installable Hermes skill
│   ├── SKILL.md                # Main skill document
│   ├── scripts/skillforge.py   # Conversion engine (stdlib-only, ~2,150 lines)
│   ├── references/             # Format detection, conversion rules, validator rules,
│   │   │                       # MCP conversion, installation guides
│   ├── templates/              # Packaging scaffolding
│   ├── tests/                  # Engine self-suite (10/10 passing)
│   └── README.md
├── scripts/skillforge          # Shell wrapper
├── Deno.ts                     # Deno runner
├── main.bun.js                 # Bun runner
├── rush.json                   # Rush monorepo manifest
├── package.json                # npm manifest
├── .github/                    # CI workflow, issue/PR templates, funding, security
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE                     # MIT

Documentation

| Document | Contents | |---|---| | CONTRIBUTING.md | How to contribute and add new formats | | CHANGELOG.md | Version history | | SECURITY.md | Security policy and vulnerability reporting | | skill/references/format-detection.md | Format scoring and evidence rules | | skill/references/conversion-rules.md | Capability extraction and mapping rules | | skill/references/validator-rules.md | Hermes SKILL.md validation rules | | skill/references/mcp-conversion.md | MCP manifest → skill conversion | | skill/references/installation.md | Hermes skill installation details | | docs/architecture.svg | Pipeline architecture diagram |

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct first. Quick summary: fork → branch → test → PR (use the PR template). Adding a new source format takes roughly five focused changes — the guide walks you through them.

Badges & Keywords

This repository is optimized for discoverability with the following keywords and topics: hermes-agent, hermes-skill, agentskills.io, claude-skills, codex, cursor-rules, mcp-server, mcp, ai-agent, agent-skill, skill-converter, automation, claude, llm-tools, prompt-engineering, devtools.

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgements

Built on the Hermes Agent skill architecture and the agentskills.io open standard.