install-agent-skills
Install external Agent Skills repos collision-free.
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- install-agent-skills
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "skills", "install", "github", "collision-detection", "agent-skills" ], "related_skills": [ "hermes-agent-skill-authoring", "find-skills" ] } }
- description
- Install external Agent Skills repos collision-free.
02 资源文件 2
- 参考文档references/manim-install-example.md2.8 KB
- 脚本scripts/detect_skill_collisions.py3.7 KB
03 SKILL.md 正文
Installing External Agent Skills into Hermes
Overview
Agent Skills (Anthropic open-standard SKILL.md repos — e.g. manim, iart-ai,
Claude-plugin marketplaces) drop into ~/.hermes/skills/<category>/<name>/.
Installing looks trivial (git clone + copy) but has one sharp edge: two
skill directories that resolve to different real paths but share the same
frontmatter name: break skill loading (the loader refuses to guess and
returns "Ambiguous skill name"). This skill makes installs collision-safe and
symlink-aware so a future session starts already knowing the trap.
When to Use
- User pastes one or more GitHub URLs and says "install this" / "add these skills".
- You are wiring an external skill repo (manim, iart-ai packs, claude-plugin marketplaces) into the local library.
- You need to refresh an already-installed skill from upstream.
Don't use for: authoring a brand-new skill from scratch (see
hermes-agent-skill-authoring) or discovering which skill to use (see
find-skills). This skill is the mechanics of getting an external repo's
skills onto disk safely.
Workflow (ordered, with completion criteria)
-
Clone shallow into a temp dir — never clone into
~/.hermes/skillsdirectly.cd /tmp && rm -rf skill_install && mkdir skill_install && cd skill_install git clone --depth 1 <url> repo && echo CLONEDDone when
find repo -name SKILL.mdlists the skill folders. -
Enumerate candidate skills. A "skill" is any directory containing a
SKILL.md. Repos often nest them underskills/. Done when you have the list of candidate<dir>/SKILL.mdpaths. -
Read each candidate's
name:frontmatter field (firstname:line in the YAML header). Thisname— NOT the directory name — is the loader key. Done when every candidate has a resolvedname. -
Build the installed name→realpath map (resolve symlinks!). Run
scripts/detect_skill_collisions.pyfrom this skill. It walks~/.hermes/skills, follows symlinks viaos.path.realpath, and reports anynamethat points to more than one distinct real path. Done when you have the collision report (or "NO COLLISIONS"). -
Decide refresh vs new for each candidate:
- Name already maps to an installed realpath → it's an UPDATE. Copy the
fresh repo content onto the canonical directory (the realpath the
symlink points to), do NOT create a parallel real directory.
cp -rT "$CANDIDATE/." "$INSTALLED_REALPATH/" - Name is new → install under a category folder with a disambiguated dir
name (repo + skill) to avoid dir collisions:
mkdir -p ~/.hermes/skills/creative/<repo>-<skillname> cp -rT "$CANDIDATE/." ~/.hermes/skills/creative/<repo>-<skillname>/
Done when every candidate is either refreshed in place or installed once.*
- Name already maps to an installed realpath → it's an UPDATE. Copy the
fresh repo content onto the canonical directory (the realpath the
symlink points to), do NOT create a parallel real directory.
-
Remove any duplicate you created. If step 5 left a stray parallel copy (e.g. you copied into
creative/before realizing the name was symlinked elsewhere),rm -rfthe duplicate so only the canonical copy remains. Done whendetect_skill_collisions.pyreturns "NO COLLISIONS".* -
Verify loads. For each installed/updated skill, call
skill_view(name=<name>)(or the categorized path if ambiguous) and confirmreadiness_status: available. Done when all targets load without "Ambiguous" errors.*
Common Pitfalls
-
Name collision breaks loading. The loader keys on
name:, not the folder. Two real dirs sharing aname→ "Ambiguous skill name … Refusing to guess." Always mapname→realpath before copying. (Real case: themanimce-best-practicesrepo skill collided with a priornpx skills addcopy; refreshing the canonical dir + deleting the parallel copy fixed it.) -
.agents/skillsis the canonical install root fornpx skills add.npx skills add …writes the real skill to~/.agents/skills/<name>/and symlinks it into~/.hermes/skills/<name>. If youfindthat path and see "no files" butdiffstill reads it, it's a symlink —findwithout-Ldoes not descend into symlinked dirs. Resolve withreadlink -f/os.path.realpathbefore deciding where to write, and refresh the canonical target rather than creating a second real directory. -
findsymlink confusion. Diagnostic trap:find dir -type freports nothing for a symlinked skill dir, yetdiff/catread it fine. Trustreadlink -f, notfind, to locate the real content. -
execute_codemay be gated in some sessions (cron-mode approval). If it returns a BLOCKED error, run the collision mapper as terminal python instead — same logic, no dependency on the code tool. -
Refreshing wipes nothing important if you
cp -rT.-rT(no trailing slash on source,--target-directory) mirrors the source dir's contents onto the destination, overwriting like-named files and leaving extras. It is non-destructive to files the source doesn't contain — safe for a refresh.
Verification Checklist
- [ ] Cloned with
--depth 1into/tmp, not into~/.hermes/skills - [ ] Every candidate
name:parsed from frontmatter (not from dir name) - [ ]
scripts/detect_skill_collisions.pyrun against installed library - [ ] Updates copied onto the canonical realpath (resolved symlink target)
- [ ] New skills installed once, under a disambiguated dir name
- [ ] Any parallel duplicate removed
- [ ]
detect_skill_collisions.pynow reports "NO COLLISIONS" - [ ] Each target
skill_view(name=…)returnsreadiness_status: available
Support files
scripts/detect_skill_collisions.py— re-runnable probe: maps every installed skillname→realpath and prints collisions. Add--candidates <dir> …to pre-test cloned repo skills before copying.references/manim-install-example.md— the worked manim/iart/yusuke install that drove this skill: the exact collision found and how it was resolved.
04 同仓库更多 Skills
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
gemini-vision-fallback
Vision fallback: Gemini REST API if vision_analyze blocked.
twitter-cli
Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
prism-scan
Structural analysis through dynamically generated cognitive lenses. Generates the optimal analytical lens for the specific code/artifact, then executes it. Finds conservation laws, structural invariants, and concrete bugs that vanilla analysis misses. Use on any code file, system design, or text artifact.
prism-reflect
Constraint transparency: analyzes an artifact structurally, then analyzes what its own analysis concealed. Produces a conservation law AND a constraint report showing what was maximized, what was sacrificed, and what to investigate next. The only AI skill that knows what it can't see.
prism-full
Full Prism: multi-pass structural analysis with mandatory adversarial self-correction. Designs custom analytical passes, executes them with chaining, then attacks its own findings before synthesizing. Use for maximum depth on important code or artifacts.