Agent Skills

Fresh

Skills are reusable packages that extend the agent's capabilities. Each skill is defined by a SKILL.md file and can include supporting scripts, examples, and resources.

Locations

Level	Path	Scope
Workspace	.agents/skills/	Available in the current workspace only
Global	~/.gemini/antigravity/skills/	Available across all workspaces

Skill Structure

my-skill/
  SKILL.md          # Required -- skill definition
  scripts/           # Optional -- executable scripts
  examples/          # Optional -- usage examples
  resources/         # Optional -- reference data, templates

SKILL.md Frontmatter

---
name: my-skill          # Optional, defaults to folder name
description: Brief description of what this skill does  # Required
---

Progressive Disclosure

Skills follow a three-phase lifecycle:

Phase	Description
Discovery	The agent finds the skill based on its name and description.
Activation	The agent reads the full SKILL.md content when the skill is relevant.
Execution	The agent uses the skill's instructions, scripts, and resources to complete the task.

Best Practices

• Keep skills focused -- one skill per domain or task type
• Write clear descriptions -- the agent uses descriptions to decide when to activate a skill
• Treat scripts as black boxes -- scripts should be self-contained and executable
• Include decision trees -- help the agent decide between approaches within the skill

TIP

Skills are the primary way to teach the agent domain-specific knowledge. A well-written skill with decision trees and examples dramatically improves agent performance on specialized tasks.