Best Practices for Writing Skill Documentation and Examples in Antigravity Awesome Skills

The best practices for writing skill documentation include following the official skill template with standardized front-matter, maintaining a clear section hierarchy with actionable steps, and including security notes for any risky operations.

Consistent skill documentation ensures that both human developers and AI assistants can safely invoke capabilities within the sickn33/antigravity-awesome-skills ecosystem. The repository defines strict conventions for structure, metadata, and content that maximize discoverability and minimize execution risks.

Follow the Skill Template Structure

Every new skill must adhere to the Skill Template defined in docs/contributors/skill-template.md. This template standardizes the required front-matter and section ordering.

Required Front-Matter Fields

The YAML front-matter at the top of each SKILL.md file must include:

• name – Lower-case hyphenated string matching the folder name exactly
• description – Concise summary of the skill's purpose
• category – Classification for browsing
• risk – Safety level (e.g., safe, medium, high)
• source – Origin identifier (e.g., community, official)
• date_added – ISO date string
• author – Creator identifier
• tags – Array of relevant keywords
• tools – Compatible AI tools (e.g., claude, cursor)

Mandatory Content Sections

The template requires specific sections to ensure AI systems can parse intent correctly:

• Overview – 2-4 sentences explaining what the skill does and why it exists

• When to Use – Bullet list of concrete invocation scenarios

• How It Works – Step-by-step instructions using ### Step N: subheadings

• Examples – At least two realistic code snippets with language-specific fences (e.g., ```javascript)

• Best Practices – ✅ Do this / ❌ Don't this checklist format for quick scanning

• Security & Safety – Pre-conditions for shell/network actions with optional <!-- security-allowlist: … --> comments

• Common Pitfalls – Typical problems and solutions

• Related Skills – Cross-references using @skill-name syntax

Understand the Skill Anatomy

The docs/contributors/skill-anatomy.md file defines the physical layout and validation rules for skill packages.

Folder Structure Convention

Each skill lives under skills/<skill-name>/. While only SKILL.md is mandatory, optional directories must follow strict naming conventions:

• examples/ – Usage demonstrations
• scripts/ – Helper executables
• templates/ – Reusable file templates
• references/ – External documentation links

Structural Requirements

Maintain logical heading hierarchy (# Title → ## Overview → ### Step 1) to ensure proper parsing. The anatomy guide emphasizes that front-matter YAML must be valid and that the name field must exactly match the containing folder name.

Write Clear and Actionable Instructions

According to the anatomy guide's Writing Effective Instructions section, documentation must prioritize immediate comprehension:

• Use direct language without hedging (e.g., "Check if the user is authenticated before proceeding")
• Begin instruction sentences with action verbs ("Create the file…", "Run the setup script…")
• Prefer concrete, numbered steps over abstract advice

Implement Security-First Documentation

Any skill executing commands, fetching remote resources, or mutating files requires a Security & Safety Notes section. This section must document:

• Required user confirmations (e.g., "Are you sure you want to delete…?")
• Execution scope limitations (local-only, authorized test environment)
• Optional HTML comments for reviewer visibility: <!-- security-allowlist: approved-domains.json -->

Validate with the Quality Checklist

Before submitting a pull request, verify your skill against the ✅ Quality Checklist specified in docs/contributors/skill-anatomy.md:

1. Front-matter contains valid YAML with all required fields present
2. The name value matches the folder name exactly
3. Sections follow the correct order with proper heading levels
4. Examples are realistic and runnable
5. No typos or inaccurate technical details exist

The repository includes tools/scripts/validate_skills.py, which automates these checks in CI, validating front-matter schema, required sections, and security annotations.

Practical Examples

Minimal "Hello World" Skill

---
name: hello-world
description: "Outputs a friendly greeting"
risk: safe
source: community
date_added: "2024-10-01"
author: "alice"
tags: ["greeting"]
tools: [claude]
---

# Hello World

## Overview

Prints a short greeting to the console. Useful for testing or as a starter template.

## When to Use This Skill

- When you need a quick sanity-check that the skill runner works.
- As a baseline for creating more complex skills.

## How It Works

### Step 1: Print the greeting

Run the following command:

```bash
echo "Hello, world!"

Examples

Example 1: Direct console output

# Run the skill

antigravity run hello-world

# Expected output:

# Hello, world!

Best Practices

• ✅ Keep the skill pure-text; no external calls.
• ❌ Avoid hard-coding environment-specific paths.

Security & Safety Notes

No risky actions – this skill is safe.

Related Skills

• @farewell – prints a goodbye message.

### Skill with Helper Script

```markdown
---
name: fetch-json
description: "Downloads JSON from a URL and pretty-prints it"
risk: safe
source: community
date_added: "2024-10-02"
author: "bob"
tags: ["http", "json"]
tools: [cursor]
---

# Fetch JSON

## Overview

Downloads a JSON payload from a provided endpoint and formats it with `jq`. Demonstrates how to include helper scripts.

## When to Use This Skill

- When you need to inspect API responses quickly.
- As a building block for data-processing pipelines.

## How It Works

### Step 1: Run the helper script

```bash
bash scripts/fetch.sh "https://api.example.com/data"

Step 2: Pretty-print the result

The script pipes the response to jq '.'.

Examples

Example 1: Fetch a public API

# scripts/fetch.sh

#!/usr/bin/env bash
set -euo pipefail
curl -s "$1" | jq '.'

Running the skill:

antigravity run fetch-json

Best Practices

• ✅ Validate that the URL is provided.
• ✅ Use set -euo pipefail in Bash scripts.
• ❌ Do not hard-code secrets in the script.

Security & Safety Notes

• The skill only performs a GET request to the user-provided URL.
• Add a confirmation step if the URL points to an internal network.

Related Skills

• @post-data – sends JSON via POST.

## Summary

Writing effective skill documentation and examples requires strict adherence to established conventions:

- **Start with the template** in `docs/contributors/skill-template.md` to ensure all required front-matter and sections are present
- **Match folder names** exactly with the `name` field in front-matter
- **Include at least two examples** with language-specific code fences for clarity
- **Document security implications** explicitly for any network or filesystem operations
- **Run the validation script** `tools/scripts/validate_skills.py` before submitting changes
- **Reference existing skills** like `skills/brainstorming/SKILL.md` as models for different complexity levels

## Frequently Asked Questions

### What front-matter fields are required for every skill?

Every `SKILL.md` file must include `name`, `description`, `category`, `risk`, `source`, `date_added`, `author`, `tags`, and `tools`. The `name` field must use lower-case hyphenated formatting and exactly match the containing folder name. Invalid or missing YAML front-matter will cause the CI validation script to reject the submission.

### How should I structure the Examples section?

Provide at least two realistic code snippets that demonstrate actual usage scenarios. Use language-specific fenced code blocks (e.g., ` ```python ` or ` ```bash `) rather than generic code blocks. Each example should include comments explaining expected output or behavior, and cover both basic usage and edge cases where applicable.

### What security annotations are required for risky skills?

Any skill performing shell execution, network requests, or file mutations must include a **Security & Safety Notes** section describing required confirmations, execution scope (such as `local-only`), and any user approvals needed. For automated allow-listing, include an HTML comment like `<!-- security-allowlist: domain-pattern -->` visible to reviewers but hidden from rendered output.

### Where can I find the validation script for skill documentation?

The repository provides [`tools/scripts/validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py), which checks front-matter schema compliance, required section presence, heading hierarchy, and security annotations. This script runs in CI on all pull requests, but you can execute it locally to verify your skill documentation before submission.

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