Skip to content

Self-improving AI Employees for everyone

docs(plugins): make the tool_name/skill-icon contract unmissable; lock it with a test

trohitg2e1e334ad912
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 0a7e6acd..77799fb9 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -207,6 +207,7 @@ What you **do** still write:
- Drop `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders) and `meta.json` (`{"color": "#xxx"}`) inside the plugin folder. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.
- An entry in `server/nodes/visuals.json` ONLY if you want an emoji or `lobehub:<brand>` icon (no folder SVG). Post-F1/F7 visuals.json carries zero `asset:<key>` values.
+- A **lowercase alias entry in `visuals.json` keyed by the LLM `tool_name`** whenever you set `tool_name` to something other than `<snake_case_of_node_type>` AND ship a paired skill. The skill icon resolver maps the SKILL.md `allowed-tools` token (= the tool name) through snake→camel into `visuals.json`; a custom tool name misses the node-type key and the Master Skill row renders a blank icon. The alias carries the same icon plus the plugin's `meta.json` color — precedent: `"github": {"icon": "lobehub:Github", "color": "#8250df"}`, `"vercel": {"icon": "lobehub:Vercel", "color": "#666666"}`. Locked by `server/tests/test_skill_icon_resolution.py`.
- An entry in `server/nodes/groups.py` if you introduce a new palette group.
## Where to look next
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index 5cb784ef..b96ea7a9 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -1300,6 +1300,23 @@ registered. Stick to `<snake_case_of_node_type>` unless you're
prepared to maintain alias entries in `visuals.json`. See
[`server/skills/GUIDE.md → Tool naming`](../server/skills/GUIDE.md#tool-naming--snake_case--camelcase-contract).
+This is not hypothetical: `githubAction` / `vercelAction` deliberately
+use the short LLM tool names `github` / `vercel`, and their Master
+Skill rows shipped with blank icons until lowercase alias entries were
+added. The alias must carry BOTH `icon` and `color` — color normally
+comes from the plugin's `meta.json`, which is keyed by node type and
+therefore also misses for a custom tool name:
+
+```json
+"github": { "icon": "lobehub:Github", "color": "#8250df" },
+"vercel": { "icon": "lobehub:Vercel", "color": "#666666" }
+```
+
+The invariant is locked by
+`server/tests/test_skill_icon_resolution.py` — every shipped skill must
+resolve a non-empty icon, so a new plugin/skill pairing that breaks
+this contract fails CI instead of shipping a blank row.
+
### When to use the framework
Use it for any new event-source plugin:
diff --git a/server/nodes/README.md b/server/nodes/README.md
index b511be10..e759bda1 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -347,6 +347,19 @@ Full reference: [docs-internal/plugin_system.md → "Self-contained plugin folde
`model_dump(by_alias=True)`. `displayOptions.show["driver_field"]` must
match a property name in the same `Params` class — the frontend's
visibility evaluator looks up that exact key.
+- **A custom `tool_name` breaks the paired skill's icon unless you add a
+ `visuals.json` alias.** The skill icon resolver
+ (`SkillLoader._parse_skill_metadata`) maps each SKILL.md
+ `allowed-tools` token — which is the LLM tool name — through
+ snake→camel into a `visuals.json` lookup. Keep `tool_name =
+ "<snake_case_of_node_type>"` and this just works. If you deliberately
+ pick a short brand name (`github` for `githubAction`, `vercel` for
+ `vercelAction`), you MUST add a `visuals.json` entry keyed by that
+ tool name carrying the same icon plus the plugin's `meta.json` color:
+ `"github": {"icon": "lobehub:Github", "color": "#8250df"}`. Otherwise
+ the Master Skill row renders a blank icon and no color. Locked by
+ `tests/test_skill_icon_resolution.py` (every shipped skill must
+ resolve a non-empty icon).
- **LLM tool schemas must be flat.** If your Params uses nested
Pydantic models or `Union`, the LLM-schema emission will add `$defs`
and fail the invariant. Keep tool-facing Params flat; move nested
diff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.md
index cf1ae274..928ca10d 100644
--- a/server/skills/GUIDE.md
+++ b/server/skills/GUIDE.md
@@ -136,6 +136,8 @@ The skill resolver (`SkillLoader._parse_skill_metadata`) takes each `allowed-too
**Common pitfall:** picking a "creative" LLM tool name that doesn't snake-back to the node type. For example, calling a `stripeAction` node's tool `stripe_cli` (because it wraps a CLI) breaks the convention — `stripe_cli` snakes to `stripeCli`, not `stripeAction`, so `visuals.json` lookup fails. Stick to `<node_type_in_snake_case>` unless you're prepared to also add an alias entry to `visuals.json`.
+**If you do keep a short tool name, the alias entry is mandatory, not optional.** Real precedent: `githubAction` / `vercelAction` use the tool names `github` / `vercel`, and their skills rendered blank Master Skill rows until `visuals.json` gained lowercase alias entries keyed by the tool name. The alias must carry both `icon` and `color` (the color fallback via the plugin's `meta.json` is keyed by node type, so it misses too): `"github": {"icon": "lobehub:Github", "color": "#8250df"}`. Every shipped skill must resolve a non-empty icon — locked by `server/tests/test_skill_icon_resolution.py`, so a mismatch fails CI with a message pointing back here.
+
## Optional Supporting Files
Skills can include additional files that are loaded alongside the main instructions:
diff --git a/server/tests/test_skill_icon_resolution.py b/server/tests/test_skill_icon_resolution.py
new file mode 100644
index 00000000..0c457ef3
--- /dev/null
+++ b/server/tests/test_skill_icon_resolution.py
@@ -0,0 +1,65 @@
+"""Every shipped skill must resolve a non-empty icon.
+
+The Master Skill panel derives each skill row's icon from its SKILL.md
+``allowed-tools`` token: ``SkillLoader._parse_skill_metadata`` runs the
+token through snake -> camel and looks the result up in ``visuals.json``
+(or the plugin folder's ``icon.svg`` via the node-type registry). When a
+plugin's LLM ``tool_name`` differs from ``<snake_case_of_node_type>``
+(github, vercel), that lookup silently misses unless a lowercase alias
+entry keyed by the tool name exists in ``visuals.json`` — the Master
+Skill row then renders a blank icon. This is the silent-miss case the
+naming contract in docs-internal/plugin_system.md ("Tool / skill /
+visuals naming contract") warns about.
+
+This suite locks the invariant so a new skill/plugin pairing that breaks
+the contract fails CI instead of shipping a blank Master Skill row.
+Fix options when a test here fails:
+
+1. Name the plugin's ``tool_name`` ``<snake_case_of_node_type>`` so the
+ skill's ``allowed-tools`` token resolves through the node-type key.
+2. Keep the short tool name and add a ``visuals.json`` alias entry keyed
+ by it, carrying the same icon plus the plugin's ``meta.json`` color —
+ precedent: ``"github": {"icon": "lobehub:Github", "color": "#8250df"}``.
+3. Orphan skills (no backing node) declare inline ``metadata.icon`` /
+ ``metadata.color`` in the SKILL.md frontmatter.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from services.skill_loader import SkillLoader
+
+SKILLS_DIR = Path(__file__).resolve().parents[1] / "skills"
+SKILL_MDS = sorted(SKILLS_DIR.glob("*/*/SKILL.md"))
+
+_loader = SkillLoader()
+
+
+def test_skill_corpus_discovered() -> None:
+ """Guard the glob itself — a layout change must not silently skip skills."""
+ assert len(SKILL_MDS) >= 60, (
+ f"Only {len(SKILL_MDS)} SKILL.md files matched "
+ f"{SKILLS_DIR}/*/*/SKILL.md — the skills layout moved and this "
+ "suite's glob needs updating."
+ )
+
+
+ "skill_md",
+ SKILL_MDS,
+ ids=lambda p: f"{p.parent.parent.name}/{p.parent.name}",
+)
+def test_skill_resolves_icon(skill_md: Path) -> None:
+ meta = _loader._parse_skill_metadata(skill_md)
+ resolved = meta.metadata or {}
+ assert resolved.get("icon"), (
+ f"{skill_md.relative_to(SKILLS_DIR.parent)} resolves an EMPTY icon "
+ f"(allowed-tools={meta.allowed_tools!r}). The Master Skill row will "
+ "render blank. Either name the plugin's tool_name "
+ "<snake_case_of_node_type>, add a visuals.json alias entry keyed by "
+ "the tool name (icon + color, like the \"github\"/\"vercel\" "
+ "entries), or declare inline metadata.icon for orphan skills. See "
+ "docs-internal/plugin_system.md -> Tool / skill / visuals naming "
+ "contract."
+ )