Add bizeros-knowledge agent skill (Hermes / OpenClaw / Claude Code compatible)

[kelsi-bizer]

Summary

Packages the agent integration as a portable skill so the user-facing setup becomes the two steps you outlined:

1. Install the image (Phase 3 already shipped this)
2. Install the skill — drop into the agent's skill directory

The skill follows the agentskills.io open standard, which means the same skill works natively in Hermes Agent, OpenClaw, and Claude Code — no per-framework forking. The frontmatter also includes ClawHub publishing metadata, so we can clawhub skill publish later and let any ClawHub-connected agent install it by name.

Deliverable

.agents/skills/bizeros-knowledge/
├── SKILL.md                    # The skill (agentskills.io format)
└── tools/
    ├── definitions.json        # 4 tools, JSON Schema (portable)
    ├── brain_tools.py          # Reference Python implementation
    └── .gitignore              # __pycache__ + .pyc

SKILL.md

Frontmatter:

• name: bizeros-knowledge
• description — when an agent should use this skill
• tags — knowledge-management, notes, markdown, bizeros
• metadata.openclaw — declares BRAIN_DIR as the primary env var so ClawHub's security analysis sees what the skill actually touches

Body sections (the agentskills.io standard structure):

• When to Use — captures, recall queries, recurring entities, summaries
• Quick Reference — the four tools, folder conventions (daily/YYYY-MM-DD.md, pages/<Topic>.md), wiki-link rules
• Procedure — concrete patterns for capturing, updating, recalling, restructuring
• Pitfalls — write_note replaces (always read first), preserve user wording, one topic per note, basename wiki links, YYYY-MM-DD date format
• Verification — how to confirm a write landed correctly and a recall is grounded in real notes

Stays under 5 KB so harnesses with a token budget on skill prompts can load it without truncation.

tools/definitions.json

Four tools as JSON Schema, OpenAI/Anthropic-compatible function-calling shape:

Tool	Purpose
list_notes()	Enumerate every .md path
search_notes(query, limit?)	Substring search across paths and contents
read_note(path)	Full contents; not_found on miss
write_note(path, content)	Atomic replace; creates parent folders

tools/brain_tools.py

Reference implementation (~150 lines, stdlib only). Reads BRAIN_DIR env var, defaults to /srv/bizeros/brain. Properties:

• Path traversal blocked via Path.resolve() + relative_to() check; null bytes rejected
• Atomic writes — tmp + replace, so a half-finished write never appears
• Consistent return shape — {ok: True, ...} or {ok: False, error: "..."}; never raises through to the model
• Dispatcher — TOOLS dict and call(name, args) for harnesses that want a single entry point
• No external deps — drop the file in, register the four functions, done

Architectural choice: filesystem, not HTTP

The skill talks to the filesystem directly rather than calling the file-api over HTTP. Three reasons that match the deployment shape:

1. Lower latency. No socket, no JSON serialization, just read_text / write_text.
2. No auth needed. Filesystem permissions on the VM are the boundary.
3. Simpler harness setup. No BRAIN_API_URL, no token, no retries.

If a future agent runs off the VM, it can use the file-api's HTTP endpoints — same contract, same paths, same conventions. But that's a different deployment shape and not the one we've committed to.

Smoke test (passed locally)

write daily/2026-05-09.md   ok=true bytes=59
write pages/Sarah.md         ok=true bytes=44
write pages/Project Aurora.md ok=true bytes=42
list_notes                   3 files in expected order
search 'Sarah'               2 hits with line snippets
read pages/Sarah.md          ok=true content matches
read pages/Nope.md           ok=false error=not_found
write ../etc/passwd.md       ok=false error="path escapes brain root"
read  ../etc/passwd          ok=false error="path escapes brain root"
call('list_notes', {})       returns the same as direct call
call('bogus', {})            ok=false error="unknown tool: bogus"

Installation (after this merges)

For each VM that runs Hermes or OpenClaw:

# Clone the bizeros-knowledge repo onto the VM (anywhere)
git clone https://github.com/kelsi-bizer/bizeros-knowledge.git /opt/bizeros-knowledge

# Symlink the skill into the agent's skill directory
ln -s /opt/bizeros-knowledge/.agents/skills/bizeros-knowledge ~/.hermes/skills/bizeros-knowledge
# or for openclaw:  ~/.openclaw/skills/

# Tell the harness to use the Python tool implementation (one-time wiring):
#   import sys; sys.path.insert(0, '/opt/bizeros-knowledge/.agents/skills/bizeros-knowledge/tools')
#   from brain_tools import TOOLS, call
# then register `call(name, args)` as the dispatch for the four tools.

# Set the brain dir for the agent process (matches the docker volume mount):
export BRAIN_DIR=/srv/bizeros/brain

Once published to ClawHub, this collapses to:

clawhub skill install bizeros-knowledge

Test plan

• Drop the skill into ~/.hermes/skills/ on a Hermes VM, give Hermes a capture task, verify the resulting .md file appears in /srv/bizeros/brain/ and shows up in the notes-app UI within ~1s
• Same with OpenClaw
• Ask the agent a recall question that requires reading 2-3 prior notes — verify quotes are grounded in actual file contents, not invented
• Try a path traversal in a tool call (../../etc/passwd) — verify the tool returns the error rather than executing
• When ready: clawhub skill publish .agents/skills/bizeros-knowledge from a maintainer machine

Out of scope

• delete_note and move_note tools — left out by design; agents shouldn't delete or rename without an explicit human-confirmed reason. If you want them later, easy add.
• Streaming/incremental write tools — full-file replace is sufficient for the brain-sized writes agents do.
• HTTP-based variant of brain_tools for agents that run off the VM — easy follow-on if needed.
• Auth on the file-api — irrelevant for this skill (filesystem-direct), still a Phase 5 item for the HTTP path.

---

Generated by Claude Code