Issue Station
Sign In
Tools hereToolbox

gemini-cli - ✅(Solved) Fix [Bug] Skills discovery fails when 'description' in SKILL.md frontmatter is a single line [1 pull requests]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

The Gemini CLI skill discovery mechanism fails to recognize local skills in .agents/skills/ or .gemini/skills/ if the description field in the SKILL.md YAML frontmatter is written as a single line.

Changing the description to a multi-line block (using the YAML > operator) immediately resolves the issue and allows the skill to be discovered by /skills list.

Root Cause

The Gemini CLI skill discovery mechanism fails to recognize local skills in .agents/skills/ or .gemini/skills/ if the description field in the SKILL.md YAML frontmatter is written as a single line.

Changing the description to a multi-line block (using the YAML > operator) immediately resolves the issue and allows the skill to be discovered by /skills list.

Fix Action

Fix / Workaround

Additional Context

This bug significantly impacts the developer experience as many users intuitively write short, single-line descriptions. The workaround (using >) suggests a specific issue in how the CLI parses YAML frontmatter in SKILL.md files during the initial scanning phase.

PR fix notes

PR #25728: fix(core): improve SKILL.md frontmatter parsing robustness

Description (problem / solution / changelog)

Summary

This PR improves the robustness of `SKILL.md` frontmatter parsing to resolve issues where skill discovery would fail due to common but "invisible" file characteristics, such as UTF-8 Byte Order Marks (BOM) or trailing spaces after markers.

Details

  • Regex Update: Modified `FRONTMATTER_REGEX` to support an optional UTF-8 BOM (`\uFEFF`) and optional trailing horizontal whitespace (`[ \t]*`) after the triple-dash markers.
  • Improved Fallback Parser: Enhanced `parseSimpleFrontmatter` to:
    • Be case-insensitive for `name:` and `description:` keys.
    • Support optional spaces before the colon (e.g., `name :`).
    • Correctly identify the end of a multi-line description by checking if the next indented line looks like a new key, preventing it from swallowing the rest of the metadata.
  • YAML Robustness: Added a fallback for `js-yaml` when non-string values (like numbers or booleans) are provided in the frontmatter, ensuring they are treated as strings by the simple parser instead of causing discovery to fail.

Related Issues

Fixes #25693

How to Validate

  1. Create a skill directory: `.gemini/skills/test-spaces`

  2. Create `SKILL.md` with a trailing space after the first `---`: ```

    name: test-spaces description: Testing trailing spaces.

    ```
  3. Run `npm run start -- skills list`.
  4. Verify `test-spaces` is discovered.

Repeat with a file containing a UTF-8 BOM at the start.

Pre-Merge Checklist

  • Updated relevant documentation and README (if needed)
  • Added/updated tests (if needed)
  • Noted breaking changes (if any)
  • Validated on required platforms/methods:
    • MacOS
      • npm run
      • npx
      • Docker
      • Podman
      • Seatbelt

Changed files

  • packages/core/src/skills/skillLoader.test.ts (modified, +96/-0)
  • packages/core/src/skills/skillLoader.ts (modified, +11/-5)

Code Example

---
   name: test-skill
   description: A single line description that is relatively long and contains some punctuation.
   ---
   # Test Skill
   Content here.

---

---
   name: test-skill
   description: >
     A multi-line description that is relatively long 
     and contains some punctuation.
   ---
   # Test Skill
   Content here.
RAW_BUFFERClick to expand / collapse

title: "[Bug] Skills discovery fails when description in SKILL.md frontmatter is a single line" labels: ["area/extensions", "status/need-triage"]

Description

The Gemini CLI skill discovery mechanism fails to recognize local skills in .agents/skills/ or .gemini/skills/ if the description field in the SKILL.md YAML frontmatter is written as a single line.

Changing the description to a multi-line block (using the YAML > operator) immediately resolves the issue and allows the skill to be discovered by /skills list.

Steps to Reproduce

  1. Create a folder .agents/skills/test-skill/.
  2. Create a SKILL.md with the following content: 
    ---
name: test-skill
description: A single line description that is relatively long and contains some punctuation.
---
# Test Skill
Content here.
  3. Run gemini chat and type /skills list.
  4. Actual Result: test-skill is missing from the list.
  5. Modify SKILL.md to use multi-line YAML scalar: 
    ---
name: test-skill
description: >
  A multi-line description that is relatively long 
  and contains some punctuation.
---
# Test Skill
Content here.
  6. Run /skills list again.
  7. Expected Result: test-skill should be visible in both cases. Currently, it only works with the multi-line format.

Environment

  • OS: Windows 11 (PowerShell 7)
  • Gemini CLI Version: 0.38.2
  • Runtime: Node.js / Bun

Additional Context

This bug significantly impacts the developer experience as many users intuitively write short, single-line descriptions. The workaround (using >) suggests a specific issue in how the CLI parses YAML frontmatter in SKILL.md files during the initial scanning phase.

extent analysis

TL;DR

The issue can be fixed by modifying the description field in the SKILL.md YAML frontmatter to use a multi-line block with the YAML > operator.

Guidance

  • Verify that the description field is the cause of the issue by testing with a multi-line description using the > operator.
  • Check the Gemini CLI documentation for any specific guidelines on formatting the SKILL.md file, particularly for the description field.
  • Consider reporting this issue to the Gemini CLI developers, as it may be a bug in the YAML parsing logic.
  • As a temporary workaround, use the multi-line description format with the > operator to ensure skills are discovered correctly.

Example

---
name: test-skill
description: >
  A multi-line description that is relatively long 
  and contains some punctuation.
---
# Test Skill
Content here.

Notes

This issue may be specific to the Gemini CLI version (0.38.2) and Node.js/Bun runtime. The workaround may not be necessary in future versions if the bug is fixed.

Recommendation

Apply the workaround by using the multi-line description format with the > operator, as it is a simple and effective solution to ensure skills are discovered correctly.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#dependency conflict#environment setup#docker error#permission error#memory optimization

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING