# External-to-Hermes Tool Mapping Table

Complete reference for translating tool calls, file paths, and concepts from other agent ecosystems into Hermes-native equivalents.

## Tool Name Mappings

### Claude Code → Hermes

| Claude Code Tool | Hermes Equivalent | Notes |
|---|---|---|
| `Skill` (invoke skill) | `skill_view(name=...)` | Hermes loads skill content into context |
| `Agent` / sub-agent dispatch | `delegate_task(goal=..., context=...)` | Batch mode: `tasks=[...]` for parallel |
| `Read` / file read | `read_file(path=...)` | Line-numbered, paginated |
| `Write` / file write | `write_file(path=..., content=...)` | Overwrites entire file |
| `Edit` / file edit | `patch(mode='replace', path=..., old_string=..., new_string=...)` | Fuzzy-matched find-and-replace |
| `Grep` / `rg` | `search_files(pattern=..., path=...)` | Ripgrep-backed, prefer over shell grep |
| `Glob` / `find` | `search_files(pattern=..., target='files')` | File discovery by glob |
| `Bash` / shell | `terminal(command=...)` | Persistent cwd, env vars persist |
| `WebSearch` | `web_search` / `web_extract` | Hermes web tools |
| `Browser` / Puppeteer | `browser_navigate`, `browser_click`, `browser_snapshot` | Hermes browser tool suite |
| `TodoWrite` | `todo(todos=[...])` | Task list management |
| `execute_code` (Python) | `execute_code(code=...)` | Same — but `delegate_task` NOT callable from inside |
| `Vision` / image analysis | `vision_analyze(image_url=..., question=...)` | Load image into conversation |
| `Memory` / `Remember` | `memory(action='add', target='memory')` | Persistent cross-session memory |

### Cursor → Hermes

| Cursor Concept | Hermes Equivalent | Notes |
|---|---|---|
| `@codebase` context | `search_files` + `read_file` | Explicit search, not implicit |
| `@file` references | `read_file(path=...)` | Direct file reads |
| `@web` search | `web_search` | |
| Cursor Rules (`.cursorrules`) | `AGENTS.md` / `CLAUDE.md` / skill files | Hermes reads project instruction files |
| Composer (multi-file edit) | Multiple `patch` or `write_file` calls | No single multi-file edit tool |

### Copilot CLI → Hermes

| Copilot Concept | Hermes Equivalent | Notes |
|---|---|---|
| `@workspace` | `search_files` + `read_file` | |
| `#file` references | `read_file(path=...)` | |
| GitHub Actions integration | `terminal` with `gh` CLI | Use `github-*` skills |
| Copilot Chat participants | `delegate_task` subagents | Role-based dispatch |

### Windsurf → Hermes

| Windsurf Concept | Hermes Equivalent | Notes |
|---|---|---|
| Cascade (agentic mode) | Main agent loop | Hermes is always agentic |
| `@codebase` | `search_files` + `read_file` | |
| `.windsurfrules` | `AGENTS.md` / skill files | |

## File Path Conversions

| External Path | Hermes Equivalent | Notes |
|---|---|---|
| `docs/plans/` | `.hermes/plans/` | Hermes plan directory (used by `plan` skill) |
| `docs/solutions/` | `docs/solutions/` | Keep as-is — used by `compound-learning` skill |
| `docs/specs/` | `docs/superpowers/specs/` | Used by `brainstorming` skill |
| `STRATEGY.md` | `STRATEGY.md` | Project-level, keep as-is |
| `CONCEPTS.md` | `CONCEPTS.md` | Project-level, keep as-is |
| `CLAUDE.md` | `AGENTS.md` | Hermes reads `AGENTS.md` (also reads `CLAUDE.md` for compat) |
| `.cursorrules` | `AGENTS.md` | Convert to Hermes convention |
| `~/.claude/skills/` | `~/.hermes/skills/` | Local skill directory |
| `<repo>/skills/` | `<repo>/skills/` | In-repo skills (same pattern) |

## Dispatch Mechanism Conversion

### External sub-agent patterns → `delegate_task`

**Claude Code pattern:**
```
Dispatch a sub-agent to: [task description]
```

**Hermes equivalent:**
```python
delegate_task(
    goal="[task description]",
    context="[background info the subagent needs]",
    toolsets=["terminal", "file"]
)
```

**Parallel dispatch (multiple sub-agents):**
```python
delegate_task(tasks=[
    {"goal": "Task A description", "context": "...", "toolsets": ["terminal"]},
    {"goal": "Task B description", "context": "...", "toolsets": ["file"]},
    {"goal": "Task C description", "context": "...", "toolsets": ["web"]},
])
```

Key differences:
- Hermes `delegate_task` runs in background — results return as a new message
- Max 3 concurrent children (configurable via `delegation.max_concurrent_children`)
- Nested delegation is OFF by default (`max_spawn_depth=1`)
- Subagents CANNOT use: `clarify`, `memory`, `send_message`, `execute_code` (leaf role)
- Pass ALL context via `context` field — subagents have NO conversation history

## Rendering Conversions

| External Pattern | Hermes Equivalent | Notes |
|---|---|---|
| HTML artifacts | Markdown tables, code blocks | Remove all HTML |
| Mermaid diagrams | ASCII art or `browser_vision` | No native mermaid rendering |
| React components | Plain markdown | No JSX rendering |
| Visual mockups | `browser_vision` screenshots | Take screenshot, attach to context |
| Syntax highlighting | ` ```language ` code blocks | Native in markdown |

## Skill Structure Differences

| Element | Claude Code | Hermes |
|---|---|---|
| Frontmatter start | `---` (same) | `---` (same) |
| Required fields | `name`, `description` | `name`, `description` |
| Recommended fields | varies | `version`, `author`, `license`, `metadata.hermes.tags`, `metadata.hermes.related_skills` |
| Description max | varies | 1024 chars |
| File max | varies | 100,000 chars |
| Support files | `references/`, `scripts/` | `references/`, `templates/`, `scripts/`, `assets/` |
| Skill loading | `Skill` tool | `skill_view(name=...)` |
| Cross-references | implicit | `metadata.hermes.related_skills` (explicit) |

## Common Adaptation Pitfalls

1. **Forgetting `delegate_task` is not in `execute_code`** — orchestration of sub-agents must happen from the main conversation, not from Python scripts.
2. **Leaving `docs/plans/` references** — Hermes uses `.hermes/plans/`. Update all path references.
3. **Keeping `Skill` tool references** — replace with `skill_view(name=...)` throughout.
4. **Not updating `related_skills`** — when merging, the existing skill may need new cross-references to newly created skills.
5. **Porting bulk instead of concepts** — a 60k external skill often has 5k of unique value. Extract the concept, write a concise Hermes-native skill, put detail in `references/`.
6. **HTML/JSX leftovers** — remove all non-markdown rendering. Use `browser_vision` for visual content.
7. **Missing verification step** — always `skill_view` after creating/modifying. Broken frontmatter = silent load failure.