How to Create a Custom SKILL.md File with Proper Frontmatter Format

To create a custom SKILL.md file with proper frontmatter format, copy the template from docs/contributors/skill-template.md, populate the required YAML keys (name, description, risk, source, date_added), and write the instructional Markdown content below the closing --- delimiter.

A SKILL.md file is the canonical descriptor for any skill registered in the sickn33/antigravity-awesome-skills repository. The Antigravity platform parses these files to surface metadata, safety classifications, and tool dependencies, making proper frontmatter syntax critical for integration with the automated catalog and CI validation pipeline.

SKILL.md Frontmatter Specification

Every SKILL.md must begin with a YAML frontmatter block enclosed by triple dashes (---). The parser expects five required keys and accepts four optional keys to enrich discoverability.

Required Keys

• name – Machine‑readable identifier used for @skill references throughout the ecosystem. Use lowercase with hyphens (e.g., zoom-automation).

• description – Concise summary under 200 characters explaining the skill's purpose.

• risk – Safety classification (none, safe, unknown, or high) indicating security exposure.

• source – Attribution flag (self for original work, community for third‑party contributions).

• date_added – ISO‑8601 date string (YYYY-MM-DD) marking when the skill entered the repository.

Optional Keys

• author – Human‑readable handle or name of the maintainer.
• category – Logical grouping such as automation, data-processing, or utility.
• tags – Array of free‑form labels (e.g., [codegen, QR]) for search indexing.
• tools – List of underlying tools required for execution (e.g., [claude, gemini]).

Step‑by‑Step Guide to Creating Your SKILL.md

Follow this workflow to generate a valid skill definition that passes the repository's linting gates.

1. Copy the Official Template

The repository provides an authoritative scaffold at docs/contributors/skill-template.md. Duplicate it into your skill directory:

cp docs/contributors/skill-template.md skills/your-skill-name/SKILL.md

2. Configure the Frontmatter

Edit the YAML block between the --- delimiters. Ensure strings containing special characters are quoted:

---
name: qr-generator
description: "Create a QR code image for any given URL"
risk: safe
source: community
date_added: "2026-03-01"
author: alice
category: utility
tags: [qr, image]
tools: [gemini]
---

3. Write the Markdown Body

After the closing ---, compose the documentation using standard Markdown. Include these sections for completeness:

• Overview – High‑level explanation of the skill's functionality.
• When to Use – Bullet list of applicable scenarios.
• How It Works – Step‑by‑step internal workflow.
• Examples – Runnable JSON or code snippets demonstrating invocation.
• Security & Safety Notes – Warnings about token handling, rate limits, or environment constraints.
• Common Pitfalls – Known failure modes and mitigations.

4. Validate Locally

Open the file in a Markdown previewer to confirm the YAML parses without indentation errors before submitting. The Antigravity CI will lint the frontmatter against the schema on pull request submission.

Complete SKILL.md Examples

Minimal Valid Configuration

The following snippet from skills/azure-ai-formrecognizer-java/SKILL.md demonstrates a compact yet compliant frontmatter:

---
name: azure-form-recognizer
description: "Extract text and tables from documents using Azure AI Form Recognizer"
risk: safe
source: community
date_added: "2026-02-15"
author: jdoe
category: data-processing
tags: [azure, ocr, java]
tools: []
---

Production‑Grade Skill Definition

The skills/zoom-automation/SKILL.md file illustrates a comprehensive body structure following the frontmatter:

---
name: zoom-automation
description: "Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP."
risk: unknown
source: community
date_added: "2026-02-27"
---

# Zoom Automation via Rube MCP

Automate Zoom operations including meeting scheduling, webinar management, cloud‑recording retrieval, and participant tracking through Composio’s Zoom toolkit.

## Prerequisites

- Rube MCP must be connected (`RUBE_SEARCH_TOOLS` available).
- Active Zoom connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `zoom`.

## Core Workflow – Create a Meeting

1. `ZOOM_GET_USER` – verify user and license.
2. `ZOOM_CREATE_A_MEETING` – supply `topic`, `start_time`, `duration`, `settings__waiting_room`.
3. `ZOOM_GET_A_MEETING` – fetch the `join_url` and `start_url`.

## Example Invocation

```json
{
  "skill": "@zoom-automation",
  "task": "create_meeting",
  "input": {
    "topic": "Project Kickoff",
    "type": 2,
    "start_time": "2026-04-01T15:00:00",
    "timezone": "America/New_York",
    "duration": 60,
    "settings__waiting_room": true
  }
}

Pitfalls

• start_time must be future‑dated; Zoom stores all times in UTC.
• join_url expires after 90 days; store it securely.
• Rate‑limit: max 100 meeting creations per day per user.

## Summary

- **SKILL.md** files require a YAML frontmatter block with five mandatory keys (`name`, `description`, `risk`, `source`, `date_added`) enclosed by `---` delimiters.
- The template at [`docs/contributors/skill-template.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md) provides the authoritative starting point for new skills.
- Optional keys (`author`, `category`, `tags`, `tools`) enhance searchability and categorization within the Antigravity ecosystem.
- Content below the frontmatter uses standard Markdown to document usage, security notes, and examples.
- The CI pipeline validates frontmatter syntax against the repository schema on every pull request.

## Frequently Asked Questions

### What are the required fields in a SKILL.md frontmatter block?

The five required fields are `name` (machine‑readable identifier), `description` (under 200 characters), `risk` (safety level), `source` (attribution), and `date_added` (ISO‑8601 date). Omitting any of these causes the validation pipeline to reject the file.

### How do I validate my SKILL.md file before submitting?

Preview the file in any Markdown renderer to ensure the YAML frontmatter parses correctly (no indentation before the `---` delimiters). The repository's CI automatically lints the schema upon pull request creation, flagging missing required keys or malformed dates.

### Where should I place my custom SKILL.md file in the repository?

Place the file inside a dedicated folder under `skills/<skill-name>/SKILL.md`, or next to the implementation if the skill is self‑contained. The catalog indexer recursively searches the `skills/` directory for all [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) files to build [`CATALOG.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/CATALOG.md).

### What values are accepted for the `risk` and `source` fields?

The `risk` field accepts `none`, `safe`, `unknown`, or `high`, indicating the safety level of executing the skill. The `source` field accepts `self` (for original authorship) or `community` (for third‑party contributions), which determines attribution badges in the platform UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}