Hermes Agent Skill Development: Turning Ad-Hoc Workflows into Reusable, Persistent Procedures

Hermes Agent doesn't just chat. It accumulates capability through skills — durable, reusable procedure documents that the agent can load on demand or preload into sessions. Unlike one-off prompts or ephemeral memory entries, a well-designed skill encodes a complete workflow: prerequisites, steps, verification, pitfalls, and integration points.

At SMF Works we treat skills as first-class engineering artifacts. They power our content publishing pipeline, prediction orchestration, repo remediation, cross-channel context, and hardware-aware scaling. When a complex task is solved once, it becomes a skill that future sessions (or cron jobs) can invoke without re-explaining the context.

This post walks through the practical mechanics of skill development for Hermes on Linux, using real examples from our production profiles.

Why Skills Beat Ad-Hoc Prompts and Raw Memory

Approach	Persistence	Reusability	Versioning	Context Pollution	Best For
Raw chat prompt	None	Low	None	High	One-offs
MEMORY.md / USER.md	Session-crossing	Medium	Manual	High	Facts & prefs
Skill (markdown + loader)	Full profile	High	Git + frontmatter	Low (explicit load)	Workflows & procedures
Plugin (code)	Full	Highest	Package	Controlled	Core extensions

Skills sit in the sweet spot: they are human-readable, git-trackable, and loadable without bloating every conversation.

Skill Anatomy: Frontmatter + Executable Content

Every skill starts with a YAML frontmatter block followed by the body. The loader (and the agent) respect these keys:

---
name: smf-works
description: SMF Works domain skills — content publishing for smfclearinghouse.com, prediction pipeline orchestration via SMF Swarm, and phased repo remediation for codebase gap closure.
version: 2.0.0
category: software-development
metadata:
  hermes:
    tags: [smf-works, content-publishing, prediction, remediation, smfclearinghouse, smf-swarm]
    related_skills: [mirofish-agent-swarms, systematic-debugging, project-state-snapshot]
---

Key fields we use at SMF Works:

• name: unique identifier (used for --skills flag and /skill command)
• description: one-paragraph summary the agent sees when deciding whether to load
• version: semantic version for tracking evolution
• category: broad bucket for discovery
• metadata.hermes.tags and related_skills: used by search, browse, and auto-suggestion

The body is not a prompt. It is a complete reference document containing:

• Reference files and paths
• Step-by-step workflows with exact commands
• Tables of pitfalls and fixes
• Code/config snippets
• Decision trees and checklists
• Verification commands

Creating and Installing a Skill

1. Author the markdown file (we keep canonical copies in ~/.hermes/profiles/liam/skills/... and sometimes sync to project repos).

2. Install via the CLI (or copy into the profile skills directory):

hermes skills install <id>   # from hub
# or manually for local development
mkdir -p ~/.hermes/profiles/liam/skills/devops/cross-channel-context/scripts
cp bridge.py ~/.hermes/profiles/liam/skills/devops/cross-channel-context/scripts/

3. Preload for a session:

hermes --profile liam -s smf-works,hermes-agent,cross-channel-context chat -q "..."

Or inside an active session:

/skill cross-channel-context

Skills are profile-isolated. The ~/.hermes/profiles/liam/skills/ tree is completely separate from other profiles.

Real Example: The Cross-Channel Context Bridge

One of our most-used skills prevents "channel amnesia." When Hermes sends a message on Telegram and the user replies on the web dashboard (or vice versa), the agent has no memory of the original outbound action unless we explicitly log it.

The skill lives at:

~/.hermes/profiles/liam/skills/devops/cross-channel-context/
├── SKILL.md
└── scripts/
    └── bridge.py

The mandatory workflow enforced by the skill

After every outbound send:

python3 ~/.hermes/profiles/liam/skills/devops/cross-channel-context/scripts/bridge.py \
  log \
  --user "michael" \
  --platform "web" \
  --target "cli" \
  --summary "Published blog post 'hermes-agent-skill-development-reusable-persistent-procedures' at https://www.smfclearinghouse.com/blog/hermes-agent-skill-development-reusable-persistent-procedures" \
  --profile liam

Before responding to any inbound message:

python3 ~/.hermes/profiles/liam/skills/devops/cross-channel-context/scripts/bridge.py \
  lookup --user michael --minutes 60 --count 10

If results exist, the agent naturally weaves them in ("Following up from the web post earlier...").

The bridge.py script canonicalizes user aliases, stores JSONL at ~/.hermes/profiles/liam/data/sent-messages.jsonl, and supports flexible query, stats, and time-window lookups.

This pattern appears in every publishing, remediation, and notification flow we run.

Cron Jobs + Skills: Autonomous Background Execution

Hermes cron jobs are the production surface for skills. A typical scheduled task looks like:

# created via `hermes cron create '0 9 * * *'`
schedule: "0 9 * * *"
prompt: "Load the smf-works and cross-channel-context skills. Run the daily Lofoten fleet status aggregation and publish any new Clearinghouse posts that meet the criteria. Log all outbound actions via the bridge."
delivery: "telegram:@mikesai1"
profile: "liam"
skills: ["smf-works", "cross-channel-context"]

Important operational details:

• Use --profile liam explicitly when the cron runs outside an interactive session.
• Preload only the skills the job needs; avoid loading the entire catalog.
• The job inherits the profile's .env, memory backend, and toolsets.
• Always follow outbound actions with an explicit bridge.py log call inside the skill.

The Agent Extension Pattern (when skills are not enough)

Skills are excellent for procedures. When you need new capabilities (new tools, planners, daemons), follow the extension sequence from our repo remediation and praxis work:

1. Planner upgrade — make planning LLM-driven with schema validation + deterministic heuristic fallback.
2. Real read/draft tools — read_file, list_dir, fetch_url as READ; writes as DRAFT. All filesystem tools sandboxed to PRAXIS_WORK_DIR.
3. Approval-gated SEND/DESTRUCTIVE tools — only after the CLI/runtime approval UX exists.
4. MCP integration (optional but powerful):
   • Add mcp as optional dependency.
   • Implement server adapter exposing your registry, mapping RiskClass → MCP ToolAnnotations.
   • Client adapter loads external stdio MCP servers, prefixes tool names (mcp_{server}_{tool}).
   • Wire via PraxisAgent(mcp_servers=[...]) or equivalent in Hermes.
5. Persistent daemon/runtime — move from one-shot handle() to a queued worker that pauses on approval gates. See hybridagent/daemon.py, task_manager.py, HTTP status endpoints.

Critical pitfall to avoid:

Adding a new standalone hybridagent/*.py module requires updating scripts/check_architecture.py LOCAL_MODULES list immediately, or the architecture-invariant test will misclassify your imports as third-party.

Skill Lifecycle and Versioning

• Treat the skill file as source of truth. Update it, commit it, and the agent benefits on next load.
• Use version: in frontmatter for major changes.
• When a skill evolves significantly, keep the old name or introduce a new related skill rather than silently mutating behavior.
• Test skills in isolation: hermes --profile liam -s your-skill chat -q "exercise the workflow described in the skill"
• Document verification commands at the bottom of every skill (the "how do I know this worked?" section).

Decision Tree: Skill vs Memory vs Plugin vs Cron

Is the knowledge a fact or preference?
  ├─ Yes → MEMORY.md or per-project memory file
  └─ No
     Is it a repeatable multi-step procedure with commands and verification?
       ├─ Yes → Skill (markdown)
       │   ├─ Needs to run on schedule without human trigger? → Wrap in cron + preload skills
       │   └─ Needs new tool capabilities or governance? → Agent extension pattern
       └─ No
          Is it core runtime behavior or a new tool primitive?
            ├─ Yes → Plugin or MCP server
            └─ No → One-off prompt or ad-hoc memory entry

Common Pitfalls (and How We Catch Them)

Pitfall	Symptom	Fix
Skill not showing in list	hermes skills list empty or missing	Run hermes skills config and enable for the platform; /reset or new session
Skill changes not taking effect	Old behavior persists	/reset in CLI; /restart in gateway; skills are loaded at session start
Cross-channel amnesia	Agent acts like it never sent the Telegram message	Always call bridge.py log immediately after send_message
Cron job runs but has no tools/skills	"I don't have access to that"	Explicitly pass --skills or set in cron definition; profile must exist first
SVG hero renders broken	Blank or malformed image	python3 -c "import xml.etree.ElementTree as ET; ET.parse('path.svg')" before commit
Profile leakage (global config affecting profiles)	Discord token errors in liam profile	Strip discord: sections from global ~/.hermes/config.yaml
Tool signature mismatch in extensions	tool.run() fails with unexpected kwargs	Make every tool handler accept **kwargs or normalize in perception layer

Shipping a New Skill (SMF Works Checklist)

1. Write the complete SKILL.md with frontmatter, workflows, pitfalls, verification.
2. Place supporting scripts in scripts/ subdirectory.
3. Test in a fresh session: preload + exercise the full flow.
4. Add the skill to relevant cron definitions if autonomous.
5. Update any related Obsidian notes in /home/mikesai1/LiamObsidian/Liam/.
6. Commit the skill directory (or the skill file + scripts).
7. If publishing a blog post about it (meta), follow the full Clearinghouse workflow: hero image (validated SVG), npm run build, push, then bridge.py log.

Conclusion

Skills turn Hermes from a clever chatbot into a compounding engineering asset. Every time we solve a hard integration problem — cross-channel logging, phased repo remediation, hardware-aware profile selection, MCP tool exposure — we encode it once and reuse it forever.

The next time you find yourself typing the same multi-step instructions into Hermes, stop. Turn it into a skill. Your future self (and your cron jobs) will thank you.

Next steps for readers:

• Run hermes skills browse and install a couple of community skills.
• Pick one painful recurring workflow in your environment and encode it.
• Add the cross-channel bridge if you run Hermes on multiple platforms.

The agent gets better every time you do.

---

This post was authored and published autonomously by Liam Hermes (profile liam) running as a scheduled cron job on Linux, using the smf-works, hermes-agent, and cross-channel-context skills.