Hermes Agent PR Submission Guidelines

Load this skill before creating or updating a PR to the NousResearch/hermes-agent repo. Covers all hard requirements from CONTRIBUTING.md and the PR template checklist.

When to Use

• Creating a new PR to hermes-agent
• Fixing a PR after review feedback
• Deciding whether to write a Skill vs Tool
• Writing commit messages for hermes-agent contributions

Commit Conventions (mandatory)

Format: <type>(<scope>): <description>

Common scopes: cli, gateway, tools, skills, agent, install, security

Examples:

fix(cli): prevent crash in save_config_value when model is a string
feat(gateway): add WhatsApp multi-user session isolation
test(tools): add unit tests for file_operations

One logical change per PR. Do not mix bug fix + refactor + feature.

Branch Naming

fix/description        # Bug fixes
feat/description       # New features
docs/description       # Documentation
test/description       # Tests
refactor/description   # Code restructuring

PR Template Checklist

Every PR must satisfy these when submitting:

1. Read the Contributing Guide
2. Commit messages follow Conventional Commits
3. Searched for existing PRs — not a duplicate
4. Only related changes — no unrelated commits
5. pytest tests/ -q all pass (or scripts/run_tests.sh)
6. Added tests for changes (required for bug fixes)
7. Tested on declared platform
8. Updated relevant documentation — or N/A

PR description must include:

• What changed and why
• How to test (reproduction steps for bugs, usage for features)
• What platforms tested on
• Reference any related issues (e.g., Fixes #12345)

Testing

# Preferred — matches CI (hermetic env)
scripts/run_tests.sh

# Alternative (activate venv first)
pytest tests/ -q

# For new skills:
scripts/run_tests.sh tests/skills/test_<name>_skill.py -q

Tests for skills must use stdlib + pytest + unittest.mock only. No live network calls. Use monkeypatch and tmp_path for env/filesystem deps.

Skill vs Tool Decision

This is the most common contributor question. Answer is almost always Skill.

Write a Skill when:

• Can be expressed as instructions + shell commands + existing tools
• Wraps an external CLI or API called via terminal or web_extract
• Does NOT need custom Python integration or API key management

Write a Tool when:

• Requires end-to-end auth flows, API key management, or multi-component config
• Needs custom processing logic that must execute precisely every time
• Handles binary data, streaming, or real-time events

Bundled vs Optional vs Hub:

Skill Authoring Hardline Rules (8 rules — reviewers reject violations)

Rule 1: Description ≤ 60 characters

One sentence, ends with period. No marketing words ("powerful", "comprehensive", "seamless"). Don't repeat the skill name.

# ✅ Good
description: "Search arXiv papers by keyword, author, category, or ID."

# ❌ Rejected
description: "A powerful and comprehensive skill for searching arXiv academic papers"

Rule 2: Use Hermes native tool names in prose

Rule 3: platforms: gating

Skills using POSIX-only primitives must declare platform support:

platforms: [macos]            # macOS only
platforms: [macos, linux]     # macOS + Linux
platforms: [windows]          # Windows only

Omit for cross-platform skills.

Rule 4: author credits human first

# ✅ Correct
author: "Jane Doe (jane-doe)"

# ❌ Rejected
author: "Hermes Agent"     # Tool credit, not human

Rule 5: Fixed section order

# Skill Title (2-3 sentence intro)
## When to Use
## Prerequisites
## How to Run
## Quick Reference
## Procedure
## Pitfalls
## Verification

Rule 6: Scripts/references/templates in named subdirectories

skills/my-skill/
├── SKILL.md
├── scripts/       # Helper scripts
├── references/    # API docs, examples
└── templates/     # Config templates

Rule 7: Tests at tests/skills/test_<skill>_skill.py

Stdlib + pytest only. No network calls. Hermetic CI.

Rule 8: .env.example additions isolated

Only add a clearly delimited block. Don't touch surrounding content (stale versions dropped during salvage).

Cross-Platform Gotchas (Top 5)

If you can't test on Windows, avoid these:

Run before submitting: scripts/check-windows-footguns.py

Dependency Pinning (Supply Chain)

All new PyPI deps require upper bounds:

# ✅ Correct — post-1.0
"openai>=2.21.0,<3"

# ✅ Correct — pre-1.0 (tight ±2 minor window)
"asyncpg>=0.29,<0.32"

# ❌ Rejected
"some-package>=1.2.3"        # No upper bound
"some-package==1.2.3"        # Too tight
"some-package>=0.20,<1"      # Too loose for pre-1.0

The Salvage Pattern

Hermes maintainers may salvage your PR into a larger combined PR after review approval. This is normal — not a rejection.

Signs of salvage:

• PR marked "Closed" by a maintainer (teknium1, etc.)
• Comment mentions another PR number: "Salvaged into #XXXXX"
• Your authorship preserved via Co-authored-by

What you should NOT do: reopen, rebase, or push more commits. What you should do: nothing. The maintainer handles it.

See references/salvage-example-40264.md for the full timeline of a real salvage (PR #40264 → #40625).

Pitfalls

• Don't mix changes in one PR. Bug fix + refactor + feature = rejected.
• Don't skip tests. Bug fixes require tests. Features strongly encouraged.
• Don't use @ in branch names (e.g., fix/@mention-sanitize). Use fix/mention-sanitize.
• Don't add tools for things that should be skills. Tools are rarely needed.
• Don't add memory providers to plugins/memory/. They are no longer accepted — publish as standalone plugin.
• Skill descriptions over 60 chars get rejected. Count before pushing.
• Using grep/sed/cat in SKILL.md prose instead of Hermes tool names gets requested changes.
• CI passes locally but fails remotely? Check .gitignore isn't silently blocking source files. See github-workflows for CI troubleshooting patterns including the .gitignore anchoring pitfall.
• Files that exist locally but weren't committed cause CI build failures. This is the #1 cause of "passes locally, fails CI". Always verify with git ls-files <path>/ before pushing. Real-world example: internal/l3/tdigest_tracker.go existed locally, passed go vet ./..., but was never committed — CI failed with undefined: tdigestTracker across 5 packages (PR #smart_routing, 2026-06-06).
• Detached HEAD state causes silent push failures. git push in detached HEAD only updates the remote ref if explicitly specified. Always check git status and git branch before pushing. Use git checkout main (or the target branch) first.

Verification Checklist

Before opening PR:

• scripts/run_tests.sh passes
• All commits follow type(scope): description
• Branch name follows type/description
• PR description has What + Why + How to test + Platform
• New deps have upper bounds (>=x,<next_major)
• If adding a skill, all 8 hardline rules checked
• Cross-platform impact considered
• No unrelated changes included