fix(skills): resolve skill_view by frontmatter name when dir name differs

[vinsew]

Problem

skill_view(name) resolves a skill by matching name against the on-disk directory name / path (Strategies 1-3). But skills are listed and displayed by their frontmatter name field (_find_all_skills, skills_tool.py — frontmatter.get("name", skill_dir.name)).

When a skill's directory name differs from its frontmatter name, the name an agent sees in listings is exactly the one skill_view cannot resolve:

• listing shows name: 我的笔记 (frontmatter)
• on disk the dir is productivity/getnote
• skill_view("我的笔记") → Skill '我的笔记' not found

The not-found payload then lists available_skills using the same frontmatter display names (truncated to the first 20), so the agent has no way to discover the dir/path form it would need. The skill becomes effectively uncallable by the only name it is shown under. This affects any skill whose directory name and frontmatter name diverge (e.g. a skill whose directory was renamed/normalized on disk while keeping a human-facing display name).

Fix

Add a Strategy 4 to skill_view: when none of the path/dir strategies match, fall back to matching the skill's frontmatter name.

Constraints kept to make this safe and backward-compatible:

• Path precedence preserved — Strategy 4 only runs when candidates is empty, so directory/path matches always win and existing resolution is unchanged.
• Listing-consistent — platform-mismatched skills are filtered with the same skill_matches_platform check _find_all_skills uses, so a skill the agent never sees in listings can't resolve to a misleading "unsupported platform" error.
• No silent guessing — multiple skills sharing a frontmatter name fall through to the existing collision/ambiguity guard.
• Matching mirrors the display rule (str(name)[:MAX_NAME_LENGTH]) so what the agent sees is what it can call.

Tests

tests/test_plugin_skills.py:

• resolves by frontmatter name when dir name differs
• dir/path name still takes precedence over frontmatter name
• ambiguous frontmatter name refuses
• platform-mismatched skill stays "not found" via the fallback

Known tradeoff

_find_all_skills dedupes display names by first-seen, while Strategy 4 surfaces every frontmatter-name match. A name that looks unique in listings can therefore report ambiguity if two skills genuinely share it — intentional: refusing is safer than guessing which one the listing happened to show.

[alt-glitch]

Duplicate fix — this is the same frontmatter-name fallback addressed by the existing chain:

• Root issue: skill_view resolves by directory name but skills_list displays frontmatter name — mismatch causes 'not found' #17914
• Prior fix PRs: fix(skills): resolve skill_view by frontmatter name #17918 (closed), fix(skills): skill_view fallback to frontmatter name lookup (fixes #18872) #18879 (closed/dup), fix(skills): add frontmatter-name fallback in skill_view to resolve name mismatch #18901 (open/dup), fix: resolve skills by frontmatter name #28305 (open/dup)

Please coordinate with the authors of #18901 and #28305 to consolidate into a single PR.

[Morad37]

Nice fix. The frontmatter-name fallback is exactly what's needed for the curator-renamed-directory case -- I've hit this myself where skills listed one name but skill_view couldn't find it.

Particularly like the edge case coverage:

• Ambiguous resolution refusal (two skills with same frontmatter name but different dirs) -- avoids silent wrong answers
• Platform filter gates the fallback -- consistent with listings behaviour
• Dir-name takes precedence so existing path lookups don't break

The test structure is well organised. The resolves_by_frontmatter_name_when_dir_differs test is the core regression case and the setup is clean -- temp dir with isolated SKILL.md, monkeypatch the SKILLS_DIR. Good testing pattern.

One question out of curiosity: does the frontmatter-name fallback also handle the case where the frontmatter name is defined but empty (e.g. someone writes name: with no value)? Might be a YAML parser edge case worth a guard, though probably out of scope for this PR.

[Morad37]

Agreed, this is the same fix as #18901 and #28305 for the root issue #17914. I'll track those PRs and consolidate if they still need help. No action needed on this one from my side.

[vinsew]

Closing as superseded by the implementation now on main: 9caa12f

The current upstream code and regression coverage preserve the intended frontmatter-name fallback, so keeping this older branch open would duplicate the same fix.