Hermes Profile Template

Build high quality Hermes Agent profile distributions quickly.

This repository is for people who want to create custom Hermes profiles that are installable, safe to publish, easy to maintain, and friendly to AI coding agents. Use it to create a new profile from a few parameters, validate the result, install it locally, then publish it for others to install with hermes profile install.

What you can do with it

• Create a complete Hermes profile distribution from command-line flags.
• Create a deterministic profile from a reusable YAML params file.
• Install this repository as a Hermes profile that helps you create other profiles interactively.
• Validate a profile before publishing it.
• Publish generated profiles so other users can install them from GitHub.

Requirements

• Hermes Agent installed and available as hermes.
• Python 3.10 or newer.
• pyyaml for validation and generation:

python3 -m pip install pyyaml

Option 1: Use this as a GitHub template

Open:

https://github.com/codegraphtheory/hermes-profile-template

Click Use this template, create a new repository, then clone your new repo:

git clone https://github.com/YOUR_ORG/YOUR_PROFILE_REPO.git
cd YOUR_PROFILE_REPO
python3 scripts/validate_profile.py .

Edit the profile files, then validate again before publishing.

Option 2: Create a profile from command-line flags

git clone https://github.com/codegraphtheory/hermes-profile-template.git
cd hermes-profile-template

python3 scripts/new_profile.py \
  --name security-reviewer \
  --display-name "Security Reviewer" \
  --description "Reviews code and architecture for security risk" \
  --output ../security-reviewer

cd ../security-reviewer
python3 scripts/validate_profile.py .

Install it locally:

hermes profile install . --alias
security-reviewer chat

Option 3: Create a profile from a params file

Copy the sample params file:

git clone https://github.com/codegraphtheory/hermes-profile-template.git
cd hermes-profile-template
cp templates/profile.params.yaml /tmp/my-profile.params.yaml

Edit /tmp/my-profile.params.yaml, then generate:

python3 scripts/generate_profile.py \
  --params /tmp/my-profile.params.yaml \
  --output ../my-profile

cd ../my-profile
python3 scripts/validate_profile.py .

This is the best path when you want reproducible profile creation. The params file becomes the source of truth for the starter profile.

Generated profiles can include explicit template lineage through the template_source field in the params file. GitHub only shows native generated from or forked from linkage when a repository is created through those GitHub flows, so this template records lineage in distribution.yaml, .github/template-source.yml, and the generated README.

Option 4: Install this repo as an interactive profile builder

Install the template itself as a Hermes profile:

hermes profile install github.com/codegraphtheory/hermes-profile-template \
  --name profile-architect \
  --alias

profile-architect chat

Then ask it to create a profile:

Create a Hermes profile for a database migration reviewer. It should inspect SQL diffs, flag destructive migrations, and generate rollback checklists.

The installed profile will use the included generator, write a starter profile, and run validation.

Make the profile easy to discover

Before publishing, prepare both the installable distribution and small catalog-native snippets:

• Use templates/catalog/flat-profile.md.tmpl for profile catalogs that store one Markdown file per profile.
• Use templates/catalog/manifest-profile.yaml.tmpl for manifest-driven profile kits.
• Keep catalog PRs useful in the target repo format: identity, voice, skills, triggers, constraints, and a standalone install link.
• Add GitHub topics that cover Hermes, the domain, and installability. Good defaults are hermes-agent, ai-agents, agent-profile, profile-distribution, and one or more domain topics.
• Keep github-repo-metadata.yaml current so descriptions, homepage, and topics can be applied repeatably.

Preview metadata changes:

python3 scripts/apply_github_metadata.py --repo YOUR_ORG/YOUR_PROFILE_REPO

Apply metadata after reviewing the dry run:

python3 scripts/apply_github_metadata.py --repo YOUR_ORG/YOUR_PROFILE_REPO --apply

Validate before publishing

Run this from the profile repository root:

python3 scripts/validate_profile.py .
scripts/smoke_install.sh

The smoke script validates the repository, compiles Python scripts without writing bytecode, generates and validates a profile from templates/profile.params.yaml, and installs into a temporary HERMES_HOME when the Hermes CLI is available.

Release discipline

For any change that affects profile behavior, generated files, config, docs, skills, scripts, or distribution metadata:

1. Bump version in distribution.yaml.
2. Add a matching ## <version> entry to CHANGELOG.md.
3. Run the release guard before opening a pull request:

python3 scripts/check_release_version.py --base origin/main

The GitHub Actions release guard enforces this on pull requests.

Publish a generated profile

From the generated profile directory:

git init -b main
git add .
git commit -m "feat: initial profile"
git remote add origin git@github.com:YOUR_ORG/YOUR_PROFILE_REPO.git
git push -u origin main

Users can install it with:

hermes profile install github.com/YOUR_ORG/YOUR_PROFILE_REPO --alias

What to customize

Most users should start with these files:

• SOUL.md: the profile's identity, mission, boundaries, and output style.
• distribution.yaml: name, version, description, env vars, and distribution-owned files.
• config.yaml: model, toolsets, terminal behavior, memory, security, and approval defaults.
• .env.EXAMPLE: documented environment variables with placeholder values only.
• skills/: bundled reusable procedures the profile can load.
• AGENTS.md: instructions for AI coding agents that maintain the profile repository.
• CONTRIBUTING.md: contributor workflow, profile quality bar, and PR checklist.
• SECURITY.md: vulnerability reporting and secret-handling policy.
• github-repo-metadata.yaml: repeatable GitHub description, homepage, and topic metadata.
• templates/catalog/: snippets for adding the profile to external Hermes profile catalogs without looking like a generic link drop.

Never commit .env, API keys, OAuth tokens, credentials, memories, sessions, logs, runtime databases, or private user data.

License

MIT. See LICENSE.