Using agent-skills with Gemini CLI

Setup

Option 1: Install as Skills (Recommended)

Gemini CLI has a native skills system that auto-discovers SKILL.md files in .gemini/skills/ or .agents/skills/ directories. Each skill activates on demand when it matches your task.

Install from the repo:

gemini skills install https://github.com/addyosmani/agent-skills.git

Or install from a local clone:

git clone https://github.com/addyosmani/agent-skills.git
gemini skills install /path/to/agent-skills

Install for a specific workspace only:

gemini skills install /path/to/agent-skills --scope workspace

Skills installed at workspace scope go into .gemini/skills/ (or .agents/skills/). User-level skills go into ~/.gemini/skills/.

Once installed, verify with:

/skills list

Gemini CLI injects skill names and descriptions into the prompt automatically. When it recognizes a matching task, it asks permission to activate the skill before loading its full instructions.

Option 2: GEMINI.md (Persistent Context)

For skills you want always loaded as persistent project context (rather than on-demand activation), add them to your project's GEMINI.md:

# Create GEMINI.md with core skills as persistent context
cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md > GEMINI.md
echo -e "\n---\n" >> GEMINI.md
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> GEMINI.md

You can also modularize by importing from separate files:

# Project Instructions

@skills/test-driven-development/SKILL.md
@skills/incremental-implementation/SKILL.md

Use /memory show to verify loaded context, and /memory reload to refresh after changes.

Skills vs GEMINI.md: Skills are on-demand expertise that activate only when relevant, keeping your context window clean. GEMINI.md provides persistent context loaded for every prompt. Use skills for phase-specific workflows and GEMINI.md for always-on project conventions.

Recommended Configuration

Always-On (GEMINI.md)

Add these as persistent context for every session:

incremental-implementation — Build in small verifiable slices
code-review-and-quality — Five-axis review

On-Demand (Skills)

Install these as skills so they activate only when relevant:

test-driven-development — Activates when implementing logic or fixing bugs
spec-driven-development — Activates when starting a new project or feature
frontend-ui-engineering — Activates when building UI
security-and-hardening — Activates during security reviews
performance-optimization — Activates during performance work

Usage Tips

Prefer skills over GEMINI.md — Skills activate on demand and keep your context window focused. Only put skills in GEMINI.md if you want them always loaded.
Skill descriptions matter — Each SKILL.md has a description field in its frontmatter that tells Gemini when to activate it. The descriptions in this repo are already optimized for auto-activation.
Use agents for review — Copy agents/code-reviewer.md content when requesting structured code reviews.
Combine with references — Reference checklists from references/ when working on specific quality areas like testing or performance.

3.3 KiB Raw Blame History