Skill Creation Standards

Create and manage Agent Skills for Antigravity/Gemini CLI.

About Agent Skills

Skills are modular packages that extend Antigravity with specialized expertise and workflows. They follow the open Agent Skills specification.

Skill Locations:

• Workspace skills: .agent/skills/

• project-specific, committed to version control

• Global skills: ~/.gemini/skills/

• personal skills across all workspaces

Skill Structure

skill-name/ ├── SKILL.md # Required - instructions and metadata ├── scripts/ # Optional - executable scripts ├── references/ # Optional - documentation to load as needed └── assets/ # Optional - templates, images, data files

SKILL.md Format

Frontmatter (required)

name: skill-name # Required: 1-64 chars, lowercase, hyphens only description: What skill does # Required: 1-1024 chars, include trigger keywords license: MIT # Optional: license identifier compatibility: Requires git # Optional: 1-500 chars, environment requirements metadata: # Optional: custom key-value pairs author: example-org version: "1.0" allowed-tools: Bash(git:*) Read # Experimental: pre-approved tools

Name rules:

• Lowercase alphanumeric and hyphens only (a-z , 0-9 , - )

• No starting/ending hyphens, no consecutive hyphens (-- )

• Must match parent directory name

Description tips:

• Include WHEN to use: specific scenarios, file types, or tasks

• Add keywords that help agents identify relevant tasks

Body Content

Markdown instructions for the agent. Keep under 5000 tokens for optimal context usage.

Include:

• Tool Usage Standards: Standard patterns for using Antigravity tools (run_command , read_file ) within this domain.

• Step-by-step workflows (Procedures, not Lifecycle Workflows)

• Code examples

• Edge cases and troubleshooting

Skill Design Principles

Strict Separation of Concerns:

• Skill = Knowledge: Capabilities, Standards, Best Practices, Reference Data.

• Workflow = Process: Steps, Sequences, Lifecycles, Timelines.

[!WARNING] Do NOT embed Workflows in Skills.

• ❌ Bad: A backend-developer skill defining a "Feature Implementation" lifecycle.

• ✅ Good: A backend-developer skill defining "API Design Standards" and asking the user to use a generic Workflow to execute it.

Progressive Disclosure

Skills use three-level loading to manage context efficiently:

• Metadata (~100 tokens): name

• description loaded at startup

• Instructions (<5000 tokens): Full SKILL.md body when skill activates

• Resources (as needed): scripts/, references/, assets/ loaded on demand

Creating a Skill

Step 1: Clarify Scope (Required)

Always ask the user to clarify the skill's scope before proceeding:

• What specific tasks should this skill handle?

• What tools, APIs, or frameworks does it involve?

• What are the expected inputs and outputs?

• Are there any existing workflows or patterns to follow?

Step 2: Research & Analysis

Use available tools to understand the full picture:

• Search tools: Use search_web , read_url_content to research official documentation

• Codebase analysis: Use grep_search , find_by_name to understand existing patterns

Analyze step-by-step:

• What are the core capabilities needed?

• What standard Antigravity tools are most relevant? (e.g., read_file for docs, run_command for CLI)

• What are common use cases and edge cases?

• What scripts or references would be reusable?

Step 3: Initialize

python scripts/init_skill.py <skill-name> --path .agent/skills

Step 4: Edit SKILL.md

• Complete the frontmatter metadata with accurate description

• Write clear, actionable instructions based on research

• Add scripts/references/assets as identified in analysis

Step 5: Validate

python scripts/quick_validate.py .agent/skills/<skill-name>

Resource Directories

scripts/

Executable code (Python/Node/Bash) for automation tasks.

• Include error handling and helpful messages

• Document dependencies in requirements.txt

references/

Documentation loaded into context when needed.

• API references, schemas, detailed guides

• Keep files focused (<5000 tokens each)

assets/

Files used in output, not loaded into context.

• Templates, images, fonts, boilerplate code

Expert Questioning Framework

When a user requests to create or upgrade a skill, the agent MUST gather requirements through 5 phases.

[!IMPORTANT] Do NOT just provide a generic questionnaire. You must generate domain-specific questions based on:

• The skill's domain (frontend, backend, AI, etc.)

• The user's specific request

• Your expert knowledge in that domain

Workflow:

• Analyze the request - Identify the skill domain and user's goal

• Generate custom questionnaire - Create an Artifact for the user to fill out.

• MUST customize questions for the specific domain/task.

• Use the template as a base but rewrite questions to be specific.

• Notify User - Use notify_user with PathsToReview pointing to the artifact.

• Wait for Input - User will edit the artifact directly.

• Read & Proceed - Read the filled artifact and start implementation.

Example - Designer Skill Upgrade:

Instead of generic "What constraints?", ask specific questions like:

• "Should the skill focus on Web, Mobile, or both?"

• "Which design systems to reference? (Material, Ant, custom)"

• "Accessibility standards: WCAG 2.1 AA or AAA?"

• "Dark mode support required?"

Phase 1: Discovery (Understand WHY & WHO)

• What specific problem needs to be solved?

• Who will use this skill? (agent, human, or both)

• What triggers the need to create/upgrade this skill?

Phase 2: Context (Understand WHAT & WHERE)

• What is the specific domain? (frontend, backend, devops, AI, etc.)

• What tech stack or frameworks are involved?

• What standard tool patterns apply? (e.g., File system ops vs Command line ops)

• What constraints must be followed? (time, resources, team size)

Phase 3: Scope (Define Boundaries)

[!CAUTION] ⚠️ NEVER decide scope on your own - always ask user for confirmation

• What is IN scope? What is OUT of scope?

• Minor update or Major upgrade?

• Dependencies with other skills/tools?

Phase 4: Quality (Define Quality Standards)

• What level of expertise to embody? (junior, senior, expert 20+ years)

• Which best practices must be followed?

• What edge cases need to be handled?

Phase 5: Validation (Define Success)

• What are the acceptance criteria?

• How do we know the skill works correctly?

• What metrics measure improvement?

Key Principles:

• 🔍 Research before asking - use tools to understand context

• 🎯 Purpose-driven questions - each question leads to a specific decision

• 📝 Document answers - record for reference during implementation

Upgrading Existing Skills

Step 1: Clarify User Intent

Apply the Expert Questioning Framework above. Position yourself as an expert in the skill's domain to ask guiding questions.

Step 2: Analyze Current Skill

Backup current skill

cp -r .agent/skills/<skill-name> .agent/skills/<skill-name>.backup

View structure

ls -la .agent/skills/<skill-name>/

Analyze:

• Read SKILL.md: frontmatter, body, sections

• Check scripts/, references/, assets/

• Count tokens, sections, capabilities

Step 3: Gap Analysis

Compare current state vs new requirements:

Requirement Current State Gap

... Yes/No Need to add/Exists/Duplicate

If duplicate: Notify user and ask if they want to enhance further

Step 4: Propose Changes

Present proposal and ask user for confirmation:

• Minor Update: Add notes, small fixes in SKILL.md

• Major Upgrade: Restructure, add scripts/references

• Restructure: Change architecture

Step 5: Implement & Report

After implementation, run:

python scripts/compare_skill.py .agent/skills/<skill-name>.backup .agent/skills/<skill-name>

Change Report Template

After upgrading a skill, report using this format:

Skill Upgrade Report: [skill-name]

Summary

• Type: Minor Update / Major Upgrade / Restructure
• Date: YYYY-MM-DD

Changes Made

Before vs After

Validation

• quick_validate.py passed
• Structure verified
• User reviewed