hermes-skills/software-development/adapting-external-skills/SKILL.md

name, description, version, author, license, metadata

name	description	version	author	license	metadata
adapting-external-skills	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.	1.0.0	Hermes Agent	MIT	hermes tags related_skills skills import adaptation migration cross-platform compound-engineering 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

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

# 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