botmaker README

The project's README from github.com/techjanitor/botmaker. As one markdown file: README.md.

botmaker

A Hermes Agent skill + SOUL for a bot whose only job is minting other specialist bots.

The loop it enforces:

interview → one-screen SOUL draft → human sign-off → scaffold (--no-skills, pinned brain, file-level skill links) → certification in the child's own chat → documentation in the vault

Seeding files is not a bot.

Why

A SOUL.md dump on a cloned profile is a costume. A specialist has one job, a brain pinned off its own failure path, earned constraints, and a memory it wrote itself. Botmaker exists to make the second kind and refuse the first.

What Hermes is

Hermes Agent is Nous Research's open-source agent framework: profiles (bots), skills, SOULs, persistent memory, bot-to-bot messaging. Docs: https://hermes-agent.nousresearch.com. This repo is a skill and a SOUL for Hermes, not a fork of it.

What's in the repo

profile/SOUL.md                          the botmaker SOUL — fill the <placeholders>, install per below
profile/config.yaml                      example profile config — the headless-provisioning security flag, explained
profile/profile.yaml                     example roster metadata — the one-liner other bots read, plus the UI title
skills/autonomous-ai-agents/botmaker/
├── SKILL.md                             the runbook: interview, scaffold, certification, failure-mode index
├── references/soul-craft.md             what goes in a SOUL, and the human gate
├── references/process.md                independence pin, --no-skills, shared-skill mechanics, kanban intake
├── references/vault.md                  documenting the fleet (after certification, never before)
├── scripts/link_skill_tree.py           file-level symlink linker for shared skills
└── scripts/drift_check.py               doc-drift tripwire — run after every mint

The skills/ subtree mirrors the canonical Hermes tree, so every path referenced inside the docs is true after install.

Prerequisites

Install

Installing botmaker is your first supervised run of its own method.

  1. Alias preflight for the name botmaker (or whatever you call yours) — the two checks from SKILL.md:

    zsh -lc 'which -a botmaker'
test -e "$HOME/.local/bin/botmaker" || test -L "$HOME/.local/bin/botmaker"

    If either finds anything, create with --no-alias. (Why this matters: Hermes writes an alias wrapper into ~/.local/bin, Path.write_text() follows symlinks, and that combination has overwritten a real installed CLI binary. The skill tells the whole story.)

  2. Copy the canonical skill tree into the default Hermes home:

    cp -R skills/autonomous-ai-agents/botmaker ~/.hermes/skills/autonomous-ai-agents/botmaker

  3. Create the profile:

    hermes profile create botmaker --no-skills --description "Designs, scaffolds, certifies, and documents specialist Hermes bots."

  4. Pin the brain and clear any model block inherited from your default profile:

    hermes -p botmaker config set model.provider <provider>
hermes -p botmaker config set model.default <model>
hermes -p botmaker config unset model.base_url
hermes -p botmaker config unset model.api_key
hermes -p botmaker config get model   # must print only default + provider

  5. Install the SOUL. Fill the <placeholders> in profile/SOUL.md (table below), then write it to ~/.hermes/profiles/botmaker/SOUL.md. If you do this through the bot's own tools, Hermes will prompt you to approve the write — that prompt is the human gate working. Approve it yourself; don't disable it for interactive use. (Provisioning bots headless from kanban cards is the one scenario that needs the gate's tooling half off — see profile/config.yaml and the security note below.)

  6. Link the skill into the profile with its own linker (file-level symlinks — a directory symlink is invisible to Hermes's skill discovery on Python 3.11):

    python3 ~/.hermes/skills/autonomous-ai-agents/botmaker/scripts/link_skill_tree.py \
  ~/.hermes/skills/autonomous-ai-agents/botmaker \
  ~/.hermes/profiles/botmaker/skills/autonomous-ai-agents/botmaker

  7. Smoke test. Open the bot's chat and ask it to mint something deliberately fuzzy ("a bot to help with my projects"). It should refuse to scaffold and ask one sharp question. Give it a sharp job; it should stop at the sign-off gate with a one-screen draft.

  8. Drift tripwire. python3 ~/.hermes/skills/autonomous-ai-agents/botmaker/scripts/drift_check.py should exit clean; run it after every mint and every doc patch. Point BOTMAKER_VAULT_GUIDE at your vault's Bots/making-bots.md to enable the roster-vs-profiles check. The design it enforces: every rule has one home — method in the skill tree, fleet state in the vault roster, history in the changelog.

What to customize

Placeholder Where Meaning
<model> / <provider> profile/SOUL.md, throughout the skill The independence pin. Choose a provider that survives the failure your bots must outlive.
<your-vault-path> references/vault.md, SKILL.md prerequisites Your fleet's documentation home. Any markdown directory works; Obsidian conventions are shown.
<peer> / <peer-url> / <keyfile> "site-specific" blocks in SKILL.md and process.md Our external peer bridge, shown as a worked example. Adapt if your fleet has bot-to-bot peers outside Hermes; delete if not.
<review-skill> process.md Placeholder for any skill your automation injects with --skills.
Honcho sections SKILL.md, process.md Only if you use the Honcho memory provider; delete otherwise.
security.protected_instruction_files profile/config.yaml false is what lets botmaker provision bots unattended from kanban cards; leave the default true if you run it interactively. See the security note below.
author: frontmatter SKILL.md Make it yours once you've adapted the skill.

Other angle-bracket tokens (<category>, <name>, <bot>, NAME) are per-command values, the same convention the Hermes docs use.

Field notes

The pitfalls list in SKILL.md is earned, not hypothetical. Three of the scars, in brief:

Security note

Hermes protects agent-instruction files: writes to a profile's SOUL.md prompt the human by default (security.protected_instruction_files: true). That default is correct — the prompt is this method's human gate materialized in tooling.

profile/config.yaml shows the one deliberate exception: botmaker's own profile runs with the flag set to false, because that is what allows it to provision bots from kanban cards unattended — a headless worker has no approval surface, so with the flag on, the child's SOUL.md write blocks on a prompt nobody can see, times out, and ships a stub. With the flag off, the signed spec on the kanban card becomes the only gate: no signature, no write. If you run botmaker interactively instead, leave the default alone — and never set the flag fleet-wide.

License

MIT — see LICENSE.

botmaker (techjanitor/botmaker)

Searching Database…

286 ·GitHub
Botmaker
What is this?Botmaker is a skill plus SOUL profile for Hermes Agent whose only job is to mint other specialist bots. It enforces a strict loop — interview, a one-screen SOUL draft, human sign-off, scaffolding, certification in the child's own chat, and documentation in a vault — instead of just cloning a persona file.
Is botmaker a standalone agent, or does it plug into another system?It is not standalone. It is a skill and SOUL that run inside Hermes Agent, Nous Research's open-source agent framework, which provides the profiles, skills, persistent memory, and bot-to-bot messaging botmaker relies on.
How do I get botmaker running?Write the provided SOUL.md to ~/.hermes/profiles/botmaker/SOUL.md inside an existing Hermes installation, approve Hermes's write prompt for the new profile, then link the skill into the profile with file-level symlinks (a directory symlink is invisible to Hermes's skill discovery on Python 3.11).
Do I need Hermes Agent already set up before using this?Yes, botmaker only exists as a skill and profile layered on top of Hermes Agent, so you need a working Hermes installation with profiles and the skill linker first.
What happens if I ask it something vague?It is built to refuse: giving it a deliberately fuzzy request like 'a bot to help with my projects' should make it stop and ask one sharp question instead of scaffolding a bot, while a sharp job gets it as far as the sign-off gate with a one-screen draft.
What mistakes does botmaker's design protect against?The README's field notes describe real failures it guards against: a profile sharing a name with an installed CLI overwrote a 107MB binary via a ~/.local/bin symlink, a freshly cloned profile silently kept talking to the original's local GPU model, and an operator bot shipped literally voiced as 'Grok' instead of doing its actual job.
Am I locked into a specific AI provider?No, the SOUL template leaves the model/provider as a placeholder you fill in yourself — the guidance is to 'choose a provider that survives the failure your bots must outlive' — so it isn't tied to one backend.
How do I check a minted bot hasn't drifted from its spec?Run the bundled driftcheck.py script after every mint and every documentation patch; pointing an environment variable at your vault's bots doc also enables a roster-versus-profiles consistency check.
What are similar projects?awesome-hermes-agent, hermes-workspace, Raven, hermes-agent, Orbital, brigade, EverOS, Agentlas-OS
Which topics is it in?nous-research, obsidian, hermes-agent, knowledge-management, autonomous-agents, agent-memory, agent-orchestration, skill, skills, agentic-ai, multi-agent, documentation
Creator
techjanitor
Size
<0.1 MB
Stars
286
Updated
CommitSep 01
Age
1mo
Commits · 90 Days