A drop-in agent skill for grading, reviewing, and rewriting Hermes Agent SOUL.md files with a research-backed rubric instead of vibes.

SOUL.md is the identity layer for a Hermes Agent profile: who the agent is, who it serves, what it must not become, what it can claim, what needs approval, and what “done” means. This skill gives an agent a concrete way to judge whether that identity file is actually load-bearing.

Unofficial community skill. This repo is not an official Nous Research or Hermes Agent release. It is a public-safe community skill by cobi / @cobi_bean.

Install

Hermes Agent

Clone this repository into the active Hermes profile's skills directory.

For the default profile:

mkdir -p ~/.hermes/skills/community
git clone https://github.com/cobibean/soul-grader-skill.git \
  ~/.hermes/skills/community/soul-grader

For a named profile:

profile="my-profile"
mkdir -p ~/.hermes/profiles/$profile/skills/community
git clone https://github.com/cobibean/soul-grader-skill.git \
  ~/.hermes/profiles/$profile/skills/community/soul-grader

Then start a fresh Hermes session or reload skills in a running session/gateway:

/reload-skills

Ask Hermes to load it directly when needed:

Use the soul-grader skill to grade this SOUL.md.

Codex / Claude / other Markdown skill-aware agents

Copy the whole repository into your agent's skill directory, keeping the bundled references/ folder next to SKILL.md:

mkdir -p ~/.codex/skills
git clone https://github.com/cobibean/soul-grader-skill.git \
  ~/.codex/skills/soul-grader

If your agent does not have a formal skill loader, paste the SKILL.md instructions into your project or agent instructions and keep the references/ files available.

Use it

Good prompts:

Use soul-grader to grade agents/my-agent/SOUL.md and tell me whether it is deployable.

Use soul-grader to compare these two SOUL.md drafts and recommend the stronger one.

Use soul-grader to rewrite this weak SOUL.md into a production-ready identity file, but do not invent access, credentials, live services, or authority.

The skill tells the agent to load the bundled grading standard first:

references/soul-md-grading-standard.md

Then it can use the full field guide and wording layer when it needs more detail or examples.

What it grades

The rubric scores a SOUL.md out of 100:

  • Mission clarity — who/what the agent serves and what outcome matters
  • Identity + negations — what the agent is and what it must not become
  • Core thesis — the durable decision lens for the user/domain/problem
  • Optimization hierarchy — ranked tradeoffs instead of virtue soup
  • Hard constraints — real gates with approval or evidence semantics
  • Soft preferences — defaults that do not become brittle bans
  • Authority + escalation — allowed / ask-before / never boundaries
  • Voice + truthfulness — tone, evidence thresholds, and banned claims
  • Success / artifacts — durable, verifiable completion criteria
  • Artifact separation — SOUL stays identity, not runbook/state dump
  • Runtime hygiene — correct Hermes loading, session-cache, and frontmatter assumptions

Automatic blockers include secrets, false access/deployment claims, ungated publishing/spend/production mutation, cross-client contamination, wrong Hermes frontmatter assumptions, and contradictions with nearby operating docs.

What's included

SKILL.md
references/
  soul-md-grading-standard.md
  soul-md-field-guide.html
  soul-md-wording-verbiage-layer.md
  fleet-soul-grading-workflow.md
  research-deliverable-and-fleet-remediation.md
agents/
  openai.yaml
scripts/
  validate_skill.py
assets/readme/
  soul-grader-repo-card.png
.github/workflows/
  validate.yml

Grading model

The core idea:

A good SOUL.md is a compact constitution, not a costume.

Every line should catch a future drift. If a sentence cannot change behavior under pressure, cut it or rewrite it.

The bundled standard intentionally keeps the source hierarchy narrow: the target SOUL.md is evidence, but the bundled references are the normative source for quality judgments. That keeps the grader from importing random prompt-engineering advice, personal taste, or “helpful assistant” vibes.

Public safety

The examples and references in this repository are intended to be public-safe:

  • no API keys, tokens, passwords, private keys, or connection strings
  • no private customer names, hostnames, live IPs, or credential locations
  • no private transcripts or raw fleet deployment facts
  • no claims that this is an official Hermes Agent release

Run the local validator before publishing changes:

python3 scripts/validate_skill.py

The validator checks frontmatter, required references, unexpected file layout, and common secret/private-term patterns. It is a lightweight guard, not a substitute for human review.

Credits

Created by cobi for practical Hermes Agent and multi-agent operations work.

Find cobi on X/Twitter: @cobi_bean

Hermes Agent is created by Nous Research:

License

MIT. See LICENSE.