dominik/hermes-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Hermes Agent Skills collection

Browse Source
This commit is contained in:
Debian
2026-07-12 19:02:59 +00:00
commit e9cc106625
789 changed files with 233126 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
software-development/adapting-external-skills/SKILL.md
+135
View File
@@ -0,0 +1,135 @@
---
name: adapting-external-skills
description: "Import and adapt skills from other agent ecosystems (Claude Code, Cursor, Copilot) into Hermes-compatible skills. Use when cloning an external plugin/skill repo and merging or porting its skills into the Hermes skill library."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [skills, import, adaptation, migration, cross-platform, compound-engineering]
related_skills: [hermes-agent-skill-authoring, using-superpowers, brainstorming, plan]
---
# Adapting External Skills to Hermes
Port skills from other agent ecosystems into Hermes-native skills. Other ecosystems use different tool names, file paths, dispatch mechanisms, and rendering — verbatim copies break.
## When to Use
- User clones an external skill/plugin repo (Claude Code, Cursor, Copilot, Windsurf, etc.)
- User asks to "merge", "port", or "adapt" external skills into existing Hermes skills
- User wants to compare external skills with installed Hermes skills and adopt useful concepts
## Workflow
### 1. Clone and Survey
```bash
git clone --depth 1 <repo-url> /tmp/<plugin-name>
find /tmp/<plugin-name> -name "SKILL.md" -o -name "*.yaml" -o -name "*.yml" | head -50
```
Catalog every skill file found. Note sizes — large skills (>40k chars) may need selective extraction rather than full port.
### 2. Read Source + Target Skills in Parallel
Batch all reads:
- `read_file` for every external SKILL.md
- `skill_view` for every potentially-overlapping Hermes skill
- Do this in one parallel batch — don't serialize
### 3. Classify Each External Skill
For each external skill, assign one of:
| Classification | Action | Criteria |
|---|---|---|
| **Merge** | `patch` existing Hermes skill | Covers territory an existing Hermes skill handles |
| **Create** | New Hermes skill via `skill_manage(action='create')` | Unique capability, no Hermes equivalent (check `skills_list` first) |
| **Skip** | Drop | Too ecosystem-specific (e.g., Xcode-only, Slack-API-only, proprietary internals) |
### 4. Adapt Tool Mappings
This is the critical step — external skills reference tools that don't exist in Hermes. See `references/tool-mapping-table.md` for the complete mapping.
Key substitutions:
| External (Claude Code) | Hermes Equivalent | Notes |
|---|---|---|
| `Skill` tool | `skill_view(name=...)` | Loading skills |
| Sub-agent dispatch | `delegate_task(goal=..., context=...)` | Batch mode for parallel |
| `execute_code` for tool orchestration | `execute_code` (same) | Available but `delegate_task` is NOT callable from inside it |
| Manual file reads | `read_file(path=...)` | Always prefer over `cat`/`head` |
| Manual file search | `search_files(pattern=..., path=...)` | Always prefer over `grep`/`find` |
| `docs/plans/` | `.hermes/plans/` | Hermes plan directory |
| HTML rendering / visual output | `browser_vision` or markdown tables | Remove HTML, use native MD |
| `STRATEGY.md` / `CONCEPTS.md` | Keep as-is | Project-level docs, not Hermes-specific |
### 5. For Merges — Patch Existing Skills
Use `skill_manage(action='patch')` to add new subsections, phases, or pitfalls to existing Hermes skills.
Rules:
- Mark added content with the source name: `(Compound Engineering)` or `(from <source>)` so origins are traceable
- Don't duplicate — add only what the existing skill doesn't cover
- Update `related_skills` in frontmatter if the merge introduces new cross-references
- Keep the existing skill's structure and tone intact
### 6. For New Skills — Write Full SKILL.md
Create with `skill_manage(action='create')`:
- Full Hermes frontmatter (`name`, `description`, `version`, `author`, `license`, `metadata.hermes.tags`, `metadata.hermes.related_skills`)
- All tool calls use Hermes-native names (`skill_view`, `delegate_task`, `search_files`, `read_file`, `write_file`, `terminal`)
- No references to external tool names
- Include `## When to Use` with triggers and counter-triggers
- Include `## Pitfalls` section
- Include `## Integration with Other Skills` cross-references
- Include `## Hermes Agent Integration` listing which Hermes tools the skill uses
### 7. Verify
```python
# For each modified or new skill:
skill_view(name="<skill-name>")
# Confirm: readiness_status == "available"
```
Session caching: newly created skills may not appear in `skills_list` until a new session. `skill_view` with the exact name still works.
## Pitfalls
- **Don't copy verbatim** — external skills reference tools, paths, and mechanisms that don't exist in Hermes. Every tool call must be translated.
- **Don't duplicate existing skills** — before creating, check `skills_list` and `skill_view` for overlapping coverage. Prefer merging into an existing skill.
- **Don't lose the source attribution** — mark merged content with the origin so future readers know where concepts came from.
- **Don't skip verification** — a skill with broken frontmatter or invalid tool references silently fails to load. Always `skill_view` after creating/modifying.
- **Don't forget `related_skills`** — new skills should cross-reference existing ones and vice versa. This is how the skill graph stays navigable.
- **`delegate_task` is NOT callable from `execute_code`** — if a skill instructs the agent to orchestrate sub-agents, the dispatch must happen from the main conversation, not from a Python script.
- **Large external skills** — a 60k-char external skill often has 5k of unique value. Extract the concept, don't port the bulk. Put detail in `references/` if needed.
## Integration with Other Skills
- **hermes-agent-skill-authoring** — the canonical reference for Hermes skill frontmatter, structure, and quality principles. This skill extends it for the cross-ecosystem import case.
- **brainstorming** — use before adapting if the merge strategy is unclear (which skills to merge vs create vs skip)
- **plan** — for large multi-skill imports, create a plan first
- **compound-learning** — capture what was learned during the adaptation for future imports
## Hermes Agent Integration
- `skill_manage(action='create')` — create new skills
- `skill_manage(action='patch')` — merge concepts into existing skills
- `skill_view(name=...)` — verify skills after creation/modification
- `skills_list` — check for existing coverage before creating
- `read_file` — read external skill files
- `terminal` — git clone, find, file size analysis
- `write_file` — write reference files under skills
- `delegate_task` — parallelize reading/comparison of large skill sets
## Remember
```
Translate every tool call
Merge > Create > Skip
Mark origins in merged content
Verify with skill_view after every change
Extract concepts, don't port bulk
```
software-development/adapting-external-skills/references/tool-mapping-table.md
+132
View File
@@ -0,0 +1,132 @@
# 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.