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

> Create a custom SKILL.md file with proper frontmatter format. Copy the template, populate YAML keys, and add your instructional Markdown content below the delimiter.

- Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
- Tags: how-to-guide
- Published: 2026-03-18

---

**To create a custom SKILL.md file with proper frontmatter format, copy the template from [`docs/contributors/skill-template.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md). Duplicate it into your skill directory:

```bash
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:

```yaml
---
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/azure-ai-formrecognizer-java/SKILL.md) demonstrates a compact yet compliant frontmatter:

```yaml
---
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/zoom-automation/SKILL.md) file illustrates a comprehensive body structure following the frontmatter:

```yaml
---
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"
---

```

```markdown

# 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.