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