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

| File           | Action   | Description            |
| -------------- | -------- | ---------------------- |
| SKILL.md       | Modified | Added X, Y, Z sections |
| scripts/new.py | Added    | Script for ...         |

### Before vs After

| Metric   | Before | After | Change |
| -------- | ------ | ----- | ------ |
| Tokens   | X      | Y     | +Z%    |
| Sections | X      | Y     | +Z     |

### Validation

- [ ] `quick_validate.py` passed
- [ ] Structure verified
- [ ] User reviewed

skill-creator