[BUG] Skill with paths frontmatter is completely undiscoverable

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/41721

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

The paths field causing a skill to be entirely undiscoverable — excluded from / autocomplete and returning "Unknown skill" on direct invocation — is a capability declaration bug. The paths field is documented to control when the skill auto-activates, not whether the skill exists.

From an agent capability perspective, this is the same broken capability claim pattern as the plugin MCP tools regression (#49019) — a skill is configured but silently excluded from the capability set based on a field that should not affect discoverability.

The correct semantics for paths:

• With paths: "*.rs,Cargo.toml": Skill is discoverable in all contexts, but only auto-activates when the current file matches the path pattern
• Without paths: Skill is discoverable and activates in all contexts

The current behavior treats paths as an exclusion filter — if the current context does not match the pattern, the skill is hidden. This is the wrong behavior for a declarative "when to auto-activate" field.

The fix: paths should affect auto-activation only, not discovery. The skill should always appear in:

• / autocomplete
• Skill listing
• Direct /skill-name invocation

When invoked outside the matching path pattern, the skill should either run normally (ignoring the path restriction for explicit invocations) or warn: "This skill is configured for Rust projects. Continue anyway?"

Workaround: Remove the paths field. The skill will be universally available but you lose the auto-activation targeting.

This is indeed a duplicate, but the original issue is not very detailed.

Confirmed still broken in v2.1.145 — empirical sentinel test

Ran a minimal A/B test against Claude Code v2.1.145 (released 2026-05-15) on 2026-05-20 to validate this issue is still active:

Setup — created two skills with identical structure, differing only in the paths: field:

# ~/.claude/skills/test-paths-bug-49835/SKILL.md
---
name: test-paths-bug-49835
description: Sentinel skill validating bug 49835.
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# ~/.claude/skills/test-noFlag-bug-49835/SKILL.md (control)
---
name: test-noFlag-bug-49835
description: Control skill — no paths: frontmatter.
---

Result — the Skill tool's available-skills listing (returned by the Claude Code runtime on session bootstrap) contains:

• test-noFlag-bug-49835 ✅ present (control behaves correctly)
• test-paths-bug-49835 ❌ absent (sentinel confirms bug)

Invoking test-paths-bug-49835 directly via the Skill tool also fails with "Unknown skill" — matches the original report.

Impact on downstream plugins

This bug forces plugin authors to drop one of the spec'd skill-discovery levers entirely. In my case (maxvision-orchestration plugin) the workaround is to:

1. Strip every paths: field from shipped SKILL.md frontmatter.
2. Encode the same path-scoping intent in the description field ("Use when editing .ts or .tsx files") so the model picks it up via standard skill matching.
3. Add a CI guard that fails any PR introducing paths: in a SKILL.md frontmatter, so the regression cannot reappear:

- name: Block 'paths:' in skill frontmatter (anthropics/claude-code#49835)
  run: |
    bad=0
    for file in skills/*/SKILL.md; do
      frontmatter=$(awk '/^---$/{c++; if(c==2)exit; next} c==1' "$file")
      hits=$(echo "$frontmatter" | grep -nE '^paths:([[:space:]]|$)' || true)
      if [ -n "$hits" ]; then
        echo "::error file=$file::skill frontmatter contains 'paths:' — triggers bug #49835"
        bad=1
      fi
    done
    [ "$bad" -eq 0 ]

I'm leaving the workaround in place permanently for now. Happy to remove it the moment a fix ships — please ping this issue when there is movement.

Suggestion for fix scope

The original report covers the visibility side (skill absent from listings + "Unknown skill" on direct invocation). I have not tested whether the paths: glob itself is wired to anything when present, or whether the field is being parsed and immediately discarded. If it is the latter, treating an unknown frontmatter field as a no-op (warn but ship the skill) would unblock everyone using paths: accidentally, even before the field's intended semantics are implemented.

Thanks for the work on Claude Code — happy to share the sentinel test fixtures if useful for regression coverage on your side.

Following up to check status as of June 2026. This was confirmed still broken on v2.1.145 (comment from 2026-05-20). Is there a fix in progress or a target release?

Context: paths: is now documented in the official frontmatter reference at code.claude.com/docs/en/skills, which makes it more likely users will adopt it and hit this silently. The combination of “documented feature + silent breakage + no warning in the UI” makes it a high-priority DX issue.

Also related: #62049 tracks the separate case where the skill IS discoverable but the trigger never fires. Are these tracked together internally?

This is important for muti repos setup as it can avoid triggering on the wrong repos when you place your skill in a root folder.

Confirming this issue is still present in v2.1.144

This is a major issue affecting existing Skill repos including Patterns.dev, effectively making installed skills that use paths invisible.

Confirmation test

1. Install Patterns.dev skills:

``sh
npx skills add PatternsDev/skills/react
``

1. Start Claude Code
2. Call /skills
3. Installed skills do not show up in index, and do not trigger on slash command

BUT: If you _manually invoke_ the skill by referencing it in a prompt and Claude Code uses it, the skill shows up in the index the next time you call /skills and becomes available through the slash command _in the current session only._

Possible culprit: Quotes interpreted as literals

In experimentation I found that _stripping the comments from the globs_ made the skill register correctly in the index and become callable through slash commands:

paths:
  - **/*.js
  - **/*.ts

However, this is syntactically incorrect and conflicts with Claude Code docs here and here. It also prevents the skill from loading in other AI agents, so it's not a workable solution.

Interim hack

Doubling up on comments and non-comments does work, but is a standards crime:

paths:
  # Quoted: valid YAML for standards-compliant consumers
  - "**/*.tsx"
  - "**/*.jsx"

  # Unquoted: required by affected Claude Code versions
  - **/*.tsx
  - **/*.jsx

Corroborating this from another downstream case, plus two details I haven't seen mentioned in the thread yet.

Context: working on a package that installs skill files across multiple AI tools (Claude Code, Cursor, Copilot) from one canonical source. Its Claude renderer copies paths: through verbatim into .claude/skills/<id>/SKILL.md, on the assumption that Claude Code handles it the same way as Cursor's Auto Attached .mdc rules or Copilot's applyTo-scoped instructions. It doesn't — same symptoms as everyone else here: absent from /skills, "Unknown skill" on direct invocation, present in neither the model's awareness nor the slash-command registry until a matching file is read.

Discoverability vs. activation is a solved problem in the other two tools this package targets, which makes the current behavior stand out more:**

• Cursor: glob-scoped ("Auto Attached") .mdc rules are listed unconditionally in Cursor Settings → Rules regardless of whether a matching file has been opened. The glob only gates whether the rule's content is injected into a given request.
• Copilot: same separation. /instructions lists every discovered instruction file for the session; applyTo only gates which file's content applies to a given completion.

Both keep "is this installed" and "is this active right now" as separate, independently-checkable states. Claude Code currently conflates them for paths-scoped skills — there's no way to distinguish "not installed" from "installed but not yet triggered."

Workaround we landed on (same as what's already reported upthread): strip paths: in the Claude-targeted output and fold the scoping hint into description instead (e.g. "...for conf/**/*.yml files. Use when..."). Loses the deterministic glob gating, but restores normal /skills visibility and manual invocation, and the model still picks up the file-type signal from description matching.

Claude Code version tested: 2.1.220 (macOS/Linux, both claude -p non-interactive and fresh interactive sessions) — still reproducing as of today, so this is current on top of the confirmations already in this thread through v2.1.144/145.