How can a single SKILL.md file turn a general command-line assistant into an on-demand specialist? The short answer is that Gemini CLI’s Agent Skills system reads a tiny, directory-based package and, when matched, runs bundled scripts or loads reference material to provide deterministic workflows. The minimal package is one folder containing a SKILL.md whose YAML frontmatter supplies the name and description the agent uses to match requests, plus optional scripts/, references/, and assets/ subfolders for executable logic and documentation. Start an interactive session and run /skills list to confirm discovery, or follow the troubleshooting checklist below if the skill doesn't appear.

Why does Gemini CLI treat a lone SKILL.md file as the boundary between a generic assistant and a task specialist? Because the system is intentionally simple and deterministic: the agent looks for a specific file layout and a precise YAML frontmatter block so it can decide when to prompt to activate a skill without having to inspect large amounts of contextual text or unreliable heuristics.

The Agent Skills model is file-system based. At a minimum a skill is a directory that contains a single required file, SKILL.md, and that file must begin immediately with a YAML frontmatter block delimited by three hyphens on their own lines. The frontmatter must include both Name: and Description: keys. If either is missing, or if any characters or blank lines precede the opening delimiter, the file is ignored. That strictness is intentional: the matcher needs a reliable, machine-readable header to map user requests to a skill without ambiguity.

Authoring behaviour follows two clear options. One, hand-write the SKILL.md and the recommended directory layout and place supporting files alongside it. Two, use the built-in meta-skill named Skill-creator, which will scaffold a complete skill directory and correct frontmatter for you after a few clarifying questions. Both approaches are supported by the Gemini CLI documentation on geminicli.com and the project’s GitHub docs.

Designing the package with deterministic activation and execution in mind improves reliability. The recommended subfolders are Scripts/ for executable code, References/ for schemas or documentation the agent can load on demand, and Assets/ for templates or binary files. The canonical example in the documentation shows a Scripts/review.js that accepts a filename argument and prints a deterministic result. When the skill runs that script, Gemini executes it from the skill path, for example Node .gemini/skills/code-reviewer/scripts/review.js index.js. That relative invocation keeps runtime semantics predictable across environments.

The CLI discovers skills automatically at session start by scanning a few specific directories. For a project-scoped skill, place the folder inside .gemini/skills/<skill-name>/ in the project root. For user-scoped skills, the path is ~/.gemini/skills/<skill-name>/. The CLI also recognises a compatibility alias, so skills stored under .agents/skills/ will be discovered as well.

Community guides describe using those aliases to share a single source across multiple agents.

To confirm discovery, start an interactive Gemini CLI session and run the command /skills list. If you add or change a skill after the session began, run /skills reload to refresh the discovery list without restarting the session. When the agent identifies a user request that matches a skill’s Description, it asks for permission to activate the skill, then runs any bundled scripts or produces outputs based on the SKILL.md instructions.

Two operational details are important here. First, workspace skills under a project’s .gemini/skills are only loaded when the workspace is marked as trusted. If a project-scope skill doesn't appear in the list, check the workspace trust setting. Second, the CLI uses the Name: field from SKILL.md as the visible skill name; the directory name isn't the canonical identifier.

Common discovery pitfalls and how to avoid them

Community write-ups, the Agensi guide, and the GitHub documentation converge on a short troubleshooting checklist that will catch the vast majority of discovery failures.

Mastheads

First, check filename and capitalization. The SKILL.md filename must be exactly SKILL.md, with capitalization preserved on case-sensitive file systems. Variants such as Skill.md or Skill.md are ignored. Second, ensure the frontmatter block is the very first thing in the file, beginning with three hyphens on their own lines and containing both Name: and Description: keys. Third, confirm the folder depth: files nested more than one directory deep within the skill folder won't be discovered. Fourth, for project-scoped skills, verify the workspace has been marked as trusted. If a skill still doesn't appear in /skills list, restart the session or run /skills reload after correcting the layout.

Those steps reflect repeated community experience. The docs on geminicli.com and the GitHub guide include example commands for creating the recommended directory structure on macOS and Linux, for example Mkdir -p .gemini/skills/code-reviewer/scripts, and on Windows PowerShell, for example New-Item -ItemType Directory -Force -Path ".gemini\skills\code-reviewer\scripts". Using the CLI’s scaffold generator avoids many of these mistakes because it produces a valid SKILL.md with the required frontmatter and the standard subfolders.

Authoring skills that are reliable in the wild

When you bundle executable logic with a skill, design for predictable invocation. Scripts should accept clear, predictable arguments and return deterministic outputs so the agent can rely on them for repeatable tasks. The documentation’s Node.js examples run via Node relative to the skill path, but any executable launched from the CLI environment is acceptable. That means you can use shell scripts, Node utilities, or other languages so long as they behave like a human-invoked command would.

Two pragmatic rules emerge from the docs and community advice. First, handle missing arguments and error states gracefully; the agent will run scripts with the same process semantics as a human would, so unhandled exceptions or opaque error messages make a skill brittle. Second, keep SKILL.md itself compact and use References/ and Assets/ for heavyweight material. That progressive disclosure reduces the agent’s active context size and keeps matching fast and reliable.

Test skills in isolated sessions. Use /skills list to confirm discovery and /skills reload to iterate quickly. If the skill executes scripts, run those scripts directly from the shell inside the skill path to validate their behaviour before relying on the agent to call them. The GitHub docs and third-party walkthroughs such as those on danicat.dev walk through these validation steps in more detail.

Sharing skills and cross-agent compatibility

The SKILL.md format is intentionally portable. The same frontmatter-based file is used by other agent CLIs, and community tutorials explain how to share skill folders across agents by creating symbolic links. A common example is linking a single skills source into each agent’s expected path, for example symlinking ~/.claude/skills into ~/.gemini/skills. The SKILL.md format remains identical across compatible agents; differences are limited to the local skills path and to how aggressively each agent’s matcher prompts to activate a skill. Marketplaces and community repositories that publish SKILL.md packages will typically mark compatibility with specific agent implementations.

That portability makes it straightforward to maintain a single skill library for multiple agents, so long as you keep the directory structure shallow and the SKILL.md frontmatter strict. When sharing, explicitly document the skill’s expected invocation pattern and any runtime dependencies in a References/ file so other agents and other users can reproduce the same behaviour.

Two practical authoring routes and when to use them

There are two supported ways to create skills: hand-authoring and using the integrated meta-skill Skill-creator. Hand-authoring is appropriate when you need exact control over the folder layout, script contents, or descriptive language. It's handy for experienced authors who already know the discovery rules and runtime expectations.

Using the Skill-creator is often faster for first-time authors. By issuing a natural-language request to Gemini CLI such as Create a new skill called "code-reviewer" that analyses local files for common errors and style violations, the meta-skill will scaffold a directory, produce a valid SKILL.md with the required frontmatter, and create the standard Scripts/, References/, and Assets/ directories. The meta-skill may ask clarifying questions before generating the boilerplate, which helps avoid frontmatter and layout mistakes.

Either route produces the same on-disk contract the agent expects. The documentation on geminicli.com and the project’s GitHub docs describe both workflows and include examples. Third-party walkthroughs such as danicat.dev provide step-by-step demonstrations of using the meta-skill to scaffold a functioning skill quickly.

When a skill misbehaves, the same short checklist will usually fix it. First, confirm the filename is exactly SKILL.md with the correct capitalization. Second, ensure the YAML frontmatter block begins on the first line and contains both Name: and Description:. Third, verify the skill is placed at the correct top-level location, either .gemini/skills/<skill-name>/, ~/.gemini/skills/<skill-name>/, or under the .agents/skills/ alias. Fourth, check folder depth and move any nested files so they're at most one level beneath the skill root. Fifth, for project-scoped skills, mark the workspace as trusted so the CLI will load them.

Keep SKILL.md concise and document complex inputs and schemas in References/ so the agent only loads large materials when the skill is activated. Make scripts robust to missing arguments and predictable in output. Test everything in a separate session, use /skills list to check discovery, and use /skills reload to accelerate iteration.

The Gemini CLI documentation on geminicli.com, the project’s GitHub docs, and community guides such as those from danicat.dev and Agensi all emphasise those same best practices. Following them reduces mistakes and keeps the agent’s matching and execution behaviour deterministic.

In short, building reliable Gemini CLI skills comes down to three practical moves. First, obey the discovery contract: correct filename, immediate YAML frontmatter, and shallow folder layout. Second, keep SKILL.md short and move heavy material into references and assets. Third, design scripts to accept predictable arguments and to return deterministic results so the agent can rely on them for repeatable tasks.

Related Articles

Start an interactive Gemini CLI session and run /skills list to confirm the skill appears. If it does not, run /skills reload, ensure SKILL.md begins immediately with a YAML frontmatter block containing name: and description:, check the filename is exactly SKILL.md with correct capitalization, and mark a project-scope skill’s folder as trusted so the CLI will load it.

This article was created with AI assistance.