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

---
name: save-agents-md
description: 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.
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [workspace, agents-md, slash-command, session-save]
    related_skills: [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

```python
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

```markdown
## 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).