Data Formats & Schemas

The Antigravity Awesome Skills library leverages a variety of structured data formats and schemas to define, catalog, and interact with agentic skills. Understanding these formats is crucial for developing new skills, integrating with the library, or building tools that consume its outputs.

This section details the primary data structures you will encounter, including the core SKILL.md playbook format, the centralized skills.json catalog, and the API specification formats often generated or consumed by skills.

SKILL.md Playbook Format

The foundational unit of the Antigravity Awesome Skills library is the SKILL.md playbook. These are Markdown files designed to provide clear, structured instructions and context for AI agents. While flexible, they follow a recommended structure to ensure consistency and machine readability.

Purpose: To define an individual agentic skill, its purpose, usage, inputs, outputs, and any associated assets.

Structure: SKILL.md files typically include a YAML frontmatter (for metadata) followed by a series of Markdown headings.

---
name: Skill Name
description: A brief, clear description of what this skill does.
id: unique-skill-id # Optional, but recommended for programmatic identification
tags: [tag1, tag2, productivity, coding]
tools: [Claude Code, Cursor, Gemini CLI]
version: 1.0.0 # Optional versioning for the skill itself
authors: [Your Name]
source: https://github.com/sickn33/antigravity-awesome-skills
---

# Skill Name: A Detailed Title

## Purpose
Explain the primary goal and use case of this skill. What problem does it solve?

## Usage
Provide instructions on how an agent or user should invoke and interact with this skill.
Include any specific commands, prompt structures, or preconditions.

### Inputs
List and describe any required or optional inputs for this skill.
- `input_name_1`: (Type, e.g., `string`, `list<string>`) Description of the input.
- `input_name_2`: (Type, e.g., `boolean`, `integer`) Another input.

### Outputs
Describe the expected output format or outcome of the skill's execution.
- `output_data`: (Type, e.g., `json`, `markdown`) Description of the output.
- `side_effect`: (e.g., `files created`, `API calls made`) Any other effects.

## Examples
Provide one or more concrete examples of using the skill, including input prompts and expected outputs.

```prompt
Example prompt for the skill.

Expected output from the skill.

Assets

Link to any supplementary files, scripts, or templates located in the skill's assets directory.

asset-file.py: A Python script used by this skill.
template.md: A Markdown template.

Constraints

Detail any limitations, safety guidelines, or specific environment requirements for the skill.


**Relevance:** `SKILL.md` files are the primary means of packaging and sharing individual agentic capabilities within the Antigravity ecosystem.

### Skill Catalog (skills.json)

The `skills.json` file serves as a comprehensive, machine-readable index of all available skills within the library. It is used by the web application for browsing and search, and can be consumed by other tools for programmatic access to skill metadata.

**Purpose:** To provide a centralized, structured catalog of all skills, enabling efficient discovery and integration.

**Schema (Simplified):** An array of skill objects.

```json
[
  {
    "id": "unique-skill-id",
    "name": "Skill Name",
    "description": "A concise summary of the skill's function.",
    "path": "path/to/skill/SKILL.md",
    "tags": ["tag1", "tag2"],
    "tools": ["Claude Code", "Cursor"],
    "authors": ["Author Name"],
    "version": "1.0.0",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "star_count": 0,
    "slug": "skill-name"
  },
  {
    // ... another skill object
  }
]

Key Fields:

id (string): A unique identifier for the skill.
name (string): The human-readable name of the skill.
description (string): A brief explanation of what the skill does.
path (string): The relative path to the SKILL.md file within the repository.
tags (array of strings): Keywords or categories associated with the skill.
tools (array of strings): The AI coding assistants or tools this skill is compatible with or designed for.
authors (array of strings): The creators or maintainers of the skill.
version (string, optional): The version of the skill itself.
updated_at (string, optional): ISO 8601 timestamp of the last update.
star_count (integer, optional): Number of stars if it's a popular skill.
slug (string): A URL-friendly identifier for the skill.

Relevance: This file is essential for building user interfaces, search functionalities, and automated tooling around the skill library. The prerender-routes.js script, for example, uses skills.json to generate static pages for the web application.

OpenAPI/Swagger Specifications

Many agentic skills within the Antigravity library are designed to interact with, design, or validate APIs. For these skills, OpenAPI (formerly Swagger) specifications are a crucial data format. Skills can generate these specifications to define a new API or consume them to understand and interact with existing ones.

Purpose: To provide a standard, language-agnostic interface description for RESTful APIs, detailing endpoints, operations, parameters, and data models.

Structure: OpenAPI specifications are typically written in YAML or JSON, adhering to the OpenAPI Specification (OAS) standard (e.g., OpenAPI 3.0 or 3.1). Key sections include:

openapi / swagger: Specifies the version of the OpenAPI standard.
info: General API metadata (title, version, description).
paths: Defines the individual API endpoints and their HTTP methods (GET, POST, PUT, DELETE, PATCH). Each operation includes parameters, request bodies, and responses.
components (OpenAPI 3.x) / definitions (Swagger 2.0): Defines reusable data schemas (e.g., User object, Error object).

Example (Snippet):

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
paths:
  /api/users:
    get:
      summary: List users with pagination and filtering.
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A paginated list of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUsers'
    post:
      summary: Create a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "123"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        status:
          type: string
          enum: ["active", "inactive", "suspended"]
          default: "active"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UserCreate:
      type: object
      required:
        - email
        - name
        - password
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        password:
          type: string
          minLength: 8
    PaginatedUsers:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
        pages:
          type: integer

Relevance: Skills like api-design-principles and api-patterns often leverage OpenAPI for scaffolding, validation, and documentation of API endpoints. It ensures that APIs built or analyzed by agents adhere to clear, discoverable contracts.

FastAPI Pydantic Models (as JSON Schemas)

Several skills in the library involve creating or interacting with Python web services, particularly using FastAPI. FastAPI leverages Pydantic models to define data structures for request bodies, query parameters, and—most importantly for data formats—response schemas. These Pydantic models automatically generate JSON Schema definitions, making the API responses self-documenting and type-safe.

Purpose: To explicitly define the structure and validation rules for JSON data sent to and received from API endpoints, ensuring data integrity and predictable interactions.

Structure (Resulting JSON): While defined in Python as pydantic.BaseModel classes, the critical aspect for users is the resulting JSON structure that conforms to these definitions.

Example (JSON output for a User):

{
  "id": "abc-123",
  "email": "jane.doe@example.com",
  "name": "Jane Doe",
  "status": "active",
  "created_at": "2023-10-27T10:30:00.123456",
  "updated_at": "2023-10-27T10:30:00.123456"
}

Example (JSON output for PaginatedResponse):

{
  "items": [
    {
      "id": "abc-123",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "status": "active",
      "created_at": "2023-10-27T10:30:00.123456",
      "updated_at": "2023-10-27T10:30:00.123456"
    },
    {
      "id": "def-456",
      "email": "john.smith@example.com",
      "name": "John Smith",
      "status": "inactive",
      "created_at": "2023-10-26T09:00:00.000000",
      "updated_at": "2023-10-26T09:00:00.000000"
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "pages": 5
}

Key Characteristics:

Field Names and Types: Directly mapped from the Pydantic model's attributes.
Validation: Constraints defined in Pydantic (e.g., min_length, EmailStr, ge, le) are enforced.
Optionality: Fields marked as Optional in Python correspond to optional keys in the JSON.
Enums: Python Enum types are serialized as string values in JSON.

Relevance: When a skill generates a REST API (e.g., instagram or junta-leiloeiros), the data returned by these APIs will strictly adhere to the JSON schemas derived from their Pydantic models. This provides a robust and predictable contract for any client consuming these services.