docs(cli): add skill discovery troubleshooting checklist to tutorial#26018
Conversation
Adds a five-point troubleshooting checklist to the "How to verify discovery" section of the skills getting-started tutorial, covering the most common reasons a newly-created skill doesn't appear in `/skills list`. The checklist is grounded in the actual behavior of `packages/core/src/skills/skillLoader.ts` and `skillManager.ts`: - Workspace skills require a trusted folder (skillManager.ts gates them on `isTrusted` and silently skips otherwise) - Glob pattern is `SKILL.md` and `*/SKILL.md` only — one level deep - Filename is matched case-sensitively - Frontmatter must contain both `name` and `description` fields - The skill identifier in `/skills list` comes from the `name:` field (sanitized), not the parent directory name
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request improves the developer experience for the CLI by providing clear, actionable guidance for common issues encountered when creating new skills. By documenting these constraints, it reduces the need for users to debug silent failures or rely on trial-and-error, ensuring a smoother onboarding process for new skill developers. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request introduces a troubleshooting section to the skills getting started tutorial, providing a checklist for users whose skills are not appearing. The review feedback identifies two technical inaccuracies regarding the implementation: the discovery logic actually supports SKILL.md files in the root directory, and the frontmatter must be positioned at the very beginning of the file to be correctly parsed.
Note: Security Review has been skipped due to the limited scope of the PR.
| 2. **Check the path layout.** `SKILL.md` must live exactly one directory deep, | ||
| like `.gemini/skills/<skill-name>/SKILL.md`. Files placed directly in | ||
| `.gemini/skills/SKILL.md`, or nested more than one directory deep, are not | ||
| discovered. |
There was a problem hiding this comment.
The troubleshooting guide states that SKILL.md files placed directly in .gemini/skills/ are not discovered. However, the implementation in packages/core/src/skills/skillLoader.ts uses the glob pattern ['SKILL.md', '*/SKILL.md'] (line 127), which explicitly includes the root directory. This factual error could mislead users who are troubleshooting a valid (though non-recommended) layout. Please ensure documentation is consistent with the implementation.
| 2. **Check the path layout.** `SKILL.md` must live exactly one directory deep, | |
| like `.gemini/skills/<skill-name>/SKILL.md`. Files placed directly in | |
| `.gemini/skills/SKILL.md`, or nested more than one directory deep, are not | |
| discovered. | |
| 2. Check the path layout. SKILL.md should live one directory deep, like | |
| .gemini/skills/<skill-name>/SKILL.md. While files placed directly in | |
| .gemini/skills/SKILL.md are technically discovered, using a subdirectory | |
| is the recommended structure for organization and script bundling. Files | |
| nested more than one directory deep are not discovered. |
References
- Maintain consistency in documentation. When information about a feature is present in multiple documents, ensure all instances are updated or removed together to avoid contradictions.
There was a problem hiding this comment.
Thanks — both correct. Addressed in 5a441ef.
For point 2: kept the subdirectory layout as the recommended structure (so we still nudge users in that direction for script bundling) but no longer present it as a hard requirement, since SKILL.md directly under the skills directory is in fact discovered by the ['SKILL.md', '*/SKILL.md'] glob.
Reworded slightly to match the bold-lead-in tone of the surrounding checklist instead of using your suggestion verbatim — same substance.
Address two technical inaccuracies flagged by the bot review on google-gemini#26018: - Point 2 (path layout): the glob in skillLoader.ts:127 is `['SKILL.md', '*/SKILL.md']`, so a SKILL.md placed directly under `.gemini/skills/` IS discovered. The recommendation to use a subdirectory per skill is preserved as a best-practice note rather than presented as a hard requirement. - Point 4 (frontmatter): the FRONTMATTER_REGEX in skillLoader.ts:34 is anchored with `^---` (no `m` flag), so the opening delimiter must be the very first thing in the file. Any preceding text — an H1 title, a comment, or even a blank line — causes the skill to be silently skipped. Added this constraint explicitly.
|
|
||
| ### If your skill doesn't appear | ||
|
|
||
| If `/skills list` doesn't show your skill, run through this checklist: |
There was a problem hiding this comment.
| If `/skills list` doesn't show your skill, run through this checklist: | |
| If `/skills list` doesn't show your skill, check the following: |
| (`.gemini/skills/<skill-name>/SKILL.md`). The recommended layout uses a | ||
| subdirectory per skill so you can bundle scripts and other resources | ||
| alongside it. Files nested more than one directory deep are not discovered. | ||
| 3. **The filename must be `SKILL.md` exactly.** Capitalization matters on |
There was a problem hiding this comment.
| 3. **The filename must be `SKILL.md` exactly.** Capitalization matters on | |
| 3. **The filename must be exactly `SKILL.md`.** Capitalization matters on |
Address two suggestion edits from jkcinouye on google-gemini#26018: - Reword the lead-in for the troubleshooting list ("check the following:" instead of "run through this checklist:"). - Move "exactly" before the filename in point 3 so the emphasis lands on the literal `SKILL.md` rather than the adverb. Also reflow point 4 to satisfy the prettier check that was failing on the prior wording.
Closes #24169.
Summary
Adds a 5-point troubleshooting checklist under the existing "How to verify discovery" section of
docs/cli/tutorials/skills-getting-started.md, so a beginner whose newly-created skill doesn't show up in/skills listhas somewhere to look.26 lines added, 1 file modified, no code changes.
What the checklist covers
packages/core/src/skills/skillManager.ts:75-80SKILL.mdnested more than one directory deepskillLoader.ts:127glob pattern is['SKILL.md', '*/SKILL.md'](root and one-level deep are both discovered)globrespects FS case-sensitivityname:/description:, or any text (title/comment/blank line) before the opening---skillLoader.ts:34regex is anchored with^---and has nomflag;skillLoader.ts:106-108returnsnullif either field is absentname:fieldskillLoader.ts:181-187uses sanitized frontmatternameas the displayed identifierNote on the issue's suggested tips
The issue listed two suggested tips. I kept the spirit but adjusted one based on the code:
.gemini/skills/<name>/SKILL.mdexists" → kept (covered by points 2 + 3)namefield in SKILL.md" → inverted. ReadingskillLoader.ts:181-187, the directory name has no role in identification — the skill name is the sanitizedname:field from frontmatter. So point 5 of the checklist explains the actual relationship, rather than asserting a constraint that isn't enforced. Happy to revisit if a maintainer thinks the directory-name-must-match rule is intended even though the loader doesn't enforce it.What I deliberately did NOT include
A "use
DEBUG=1 geminito diagnose" tip. The diagnostic inskillLoader.ts:142-149only fires when the directory exists AND is non-empty AND no valid skills were found — covering one failure mode out of the five. For a beginner-facing tutorial, an inconsistent debug hint felt worse than no debug hint, so the checklist stands on its own.Revisions
The bot review on the initial commit caught two technical inaccuracies, both addressed in commit
5a441ef:SKILL.mdhad to be exactly one directory deep. PerskillLoader.ts:127, the glob['SKILL.md', '*/SKILL.md']also matches aSKILL.mddirectly under the skills directory. Reworded to recommend the subdirectory layout as best practice (for script bundling) without claiming it as a hard requirement.name:/description:and missing delimiters. PerskillLoader.ts:34, the regex is anchored with^---(nomflag), so the opening delimiter must be the very first thing in the file. Added the explicit constraint that any preceding text — H1 title, comment, even a blank line — silently breaks parsing.Pre-merge checklist
skillLoader.ts/skillManager.tsbehavior onmain(snapshot 42587de), revisions reflect bot review feedback