Skip to content

bug: custom Claude Code skill descriptions show generic fallback on Linux/WSL (case-sensitive filesystem) #706

@jSydorowicz21

Description

@jSydorowicz21

Bug Description

Custom Claude Code skills always display "A Claude Code Skill" or "Agent command" as their description in Maestro, instead of the actual description from the skill's frontmatter.

Root Cause

In src/main/ipc/handlers/claude.ts line 1672, the skill scanner looks for skill.md (lowercase):

const skillPath = path.join(dir, entry.name, 'skill.md');

But Claude Code skills use uppercase: SKILL.md (e.g., ~/.claude/skills/Research/SKILL.md).

On case-sensitive filesystems (Linux, WSL), skill.md != SKILL.md, so the lookup silently fails. The skill name is discovered via the init message's slash_commands array, but without a matching description from the file, the UI falls back to generic text.

Full Chain

  1. Claude Code reports skill names via init message (slash_commands: ["Research", ...])
  2. agents:discoverSlashCommands in agents.ts:1067 returns just { name } without descriptions
  3. Renderer's getSlashCommandDescription() doesn't find custom skills in its hardcoded builtin list
  4. Falls back to generic "Agent command" description

Files Affected

  • src/main/ipc/handlers/claude.ts:1672 - Case-sensitive skill.md lookup
  • src/main/ipc/handlers/agents.ts:1067 - Missing description in skill discovery
  • src/renderer/hooks/agent/useAgentListeners.ts:988 - Uses fallback instead of actual descriptions

Proposed Fix

  1. Try SKILL.md first, fall back to skill.md (or do a case-insensitive directory listing)
  2. When reporting skills from slash_commands, fetch descriptions from disk and return { name, description }
  3. Use actual descriptions in the renderer instead of getSlashCommandDescription() fallback

Environment

  • Platform: Linux/WSL (case-sensitive filesystem)
  • macOS may also be affected depending on filesystem configuration
  • Windows NTFS is case-insensitive so this works there by accident

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions