Gemini CLI supports the open Agent Skills format and discovers skills at user, workspace, extension, and built-in levels. A skill can stay as Markdown-only guidance or carry scripts, references, and assets. Gemini shows a consent prompt before activating a skill and granting access to its directory.

Use the right discovery path

Workspace skills live under .gemini/skills/<name>/SKILL.md or the compatible .agents/skills/ path. Personal skills live under ~/.gemini/skills/ or ~/.agents/skills/. A workspace must be trusted before local skills load. Keep each package one directory below the skills root; deeper nesting is not discovered.

Make activation predictable

The description is Gemini’s pre-activation routing signal. Include the task, likely user words, and a scope boundary. Distinct descriptions reduce collisions when a library grows. You can inspect current skills with /skills list and use /skills reload after changes.

---
name: endpoint-auditor
description: Test local or remote API endpoints for status, latency, response shape, and unsafe error exposure. Use for endpoint checks and API smoke tests.
---

Ask for the target URL and expected response. Run the bundled auditor, explain failures in plain language, and avoid printing tokens or private headers.

Match instruction freedom to the task

Gemini’s best-practice guidance recommends high freedom for work with several valid approaches, medium freedom when a preferred pattern exists, and low freedom for fragile sequences. A writing skill may need principles and examples. A deployment skill should usually name exact commands, checks, and stop conditions.

Bundle only resources that earn their context

Put long reference material outside the main body. Use scripts when the same deterministic work would otherwise be rewritten. Keep script output concise enough for the model to read and give failures stable exit codes. Templates belong in assets/. Never hardcode credentials, and review any third-party script before granting the skill access to the workspace.

Understand precedence

Gemini’s tiers run from built-in through extension and user to workspace, with the more local definition taking precedence when names collide. This is useful for adapting a personal skill to one repository, but duplicate names can also hide the version you meant to test. Inspect the skill list and source path before judging behavior.

Use a should-trigger request, a near miss, and an incomplete-input request. Confirm the consent screen names the expected folder. Check that the skill reads only the intended resources and produces the promised artifact. When sharing a skill, publish a readable repository with the exact files the user will install and document any host-specific fields.