hermes-skills/save-agents-md/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
save-agents-md	Use when the user sends "/save" to capture session learnings into the current workspace's AGENTS.md. Creates the file if missing, appends session details, scans for contradictions/duplication, and resolves them.	1.0.0	Hermes Agent	MIT	linux macos windows	hermes tags related_skills workspace agents-md slash-command session-save workspace-context-organization hermes-agent-skill-authoring

/save — Capture Session into Workspace AGENTS.md

Overview

When the user sends /save, persist the important details from the current session into the current workspace's AGENTS.md. This makes workspace context durable and re-loadable in future sessions (Hermes auto-injects AGENTS.md from the workspace root into every turn).

The current workspace is always taken from the [Workspace::v1: <path>] tag on the most recent user message. Never use a hardcoded path.

When to Use

• User sends /save (with or without trailing args)
• User says "save this to AGENTS.md", "update AGENTS.md", "append to AGENTS.md"
• Session produced durable facts (conventions, decisions, gotchas) worth carrying forward

Do NOT use for:

• Saving to a non-AGENTS.md file (e.g. README.md, info.md) — different intent, ask user
• Saving to memory (cross-workspace facts) — that's the memory tool, not this skill

Step-by-Step

1. Resolve target file

import os
workspace = os.environ.get("HERMES_WORKSPACE") or "<from Workspace tag>"
target = os.path.join(workspace, "AGENTS.md")

If HERMES_WORKSPACE is not set, ask the user to confirm the workspace path before proceeding (do NOT guess from prior context).

2. Decide what to capture

Review the session transcript and extract:

• Decisions the user made (e.g. "we're only using my_docs Qdrant collection")
• Conventions established (file naming, naming the info file AGENTS.md, etc.)
• Environment facts specific to this workspace (endpoints, API keys, model choices)
• Gotchas discovered (CUDA mismatch, permission issues, etc.)
• Open TODOs the user explicitly asked to track

Skip:

• Transient task state ("then I ran curl...")
• Things already in agent memory (cross-workspace facts)
• Generic tool descriptions

3. Append or create

If target does not exist: create it with frontmatter + an initial ## Session Notes section.

If it exists: append a new ## Session — YYYY-MM-DD section under a ## Session Notes heading (create that heading if missing).

4. Scan for contradictions and duplication

After appending:

1. Read the full file back.
2. Look for:
   • Contradictions — two sections that assert incompatible facts (e.g. one says "use cosine distance", another says "use dot product"). Resolve by keeping the most recent and noting the change in the new session section.
   • Duplication — same fact restated in multiple sections. Consolidate to one canonical place; cross-reference from the other.
3. If a contradiction is found between old and new content, flag it to the user with a concrete diff and ask which to keep. Do NOT silently overwrite.

5. Verify

• File exists at <workspace>/AGENTS.md
• YAML frontmatter is present and valid (if newly created)
• New section is dated YYYY-MM-DD
• No contradictions remain, OR user has explicitly resolved flagged ones
• File size under 50k chars (split into references/ if approaching limit)

Session Section Template

## Session — YYYY-MM-DD

### Decisions
- ...

### Conventions
- ...

### Environment
- ...

### Gotchas
- ...

### Open TODOs
- ...

If a category has nothing to add, omit it (don't write empty headers).

Common Pitfalls

1. Using a hardcoded workspace path. Always read the current workspace from the [Workspace::v1: ...] tag or HERMES_WORKSPACE env var. The same skill must work regardless of which workspace the user is in.

2. Writing to ~/.hermes/AGENTS.md or the global profile. /save is workspace-scoped. Global profile edits go through memory tool, not this skill.

3. Silently resolving contradictions. If the new content contradicts existing content, surface the conflict and let the user decide. Auto-resolving can erase intent.

4. Capturing transient task state. "I ran curl and got 200 OK" is not durable. "Qdrant endpoint is http://10.0.0.22:6333" is durable.

5. Creating AGENTS.md when one already exists elsewhere. Check for CLAUDE.md and .cursorrules too — if any exist, ask the user whether to consolidate into AGENTS.md or write a parallel file.

6. Skipping the contradiction scan. Even a 200-line file can drift. The scan is the whole point of /save over a plain append.

7. Exceeding 50k chars. AGENTS.md is injected into every turn — bloat costs tokens. Move deep reference material into references/ and link to it.

Verification Checklist

• Target path resolved from current workspace tag, not hardcoded
• AGENTS.md exists after the call (created or updated)
• New session section is dated and categorized
• Contradictions flagged to user (if any), not silently overwritten
• Duplication consolidated where appropriate
• File size still reasonable (< 50k chars)

References

• references/finance-workspace-example.md — Worked example from the 2026-06-18 finance-workspace session: capturing Qdrant collection setup, mortgage 1098 + statement data, and convention naming (e.g. user aliases "250" / "254" for two Rocket Mortgage loans).