Skill Anatomy & Template

Antigravity Awesome Skills are structured agentic playbooks designed to provide AI coding assistants with clear, consistent, and actionable instructions. The core unit of this library is the SKILL.md file, a Markdown document enhanced with structured metadata (front matter) and specific headings to guide AI agents.

This section details the anatomy of a SKILL.md file, explaining its mandatory components, common optional sections, and provides a reusable template for creating new skills.

The Purpose of `SKILL.md`

Each SKILL.md serves as a self-contained instruction set, defining:

What the skill is meant to achieve.
How an agent should approach the task.
What inputs are required.
What outputs are expected.
What constraints must be adhered to.
What tools or assets are available for execution.

This structured approach ensures consistency across different skills, facilitates discovery through search, and enables tighter integration with various AI assistants like Claude Code, Cursor, and Gemini CLI.

Skill File Structure

A SKILL.md file is composed of two primary parts:

Front Matter (Metadata): A YAML block at the very top of the file, providing structured data about the skill. This is crucial for indexing, searching, and programmatic integration.
Content Sections (Markdown): Standard Markdown headings and content that detail the skill's instructions, inputs, outputs, and other operational guidelines.

1. Front Matter (Metadata)

The front matter uses YAML syntax, enclosed between two --- lines. It contains key-value pairs that describe the skill.

Mandatory Metadata Fields:

id: A unique, kebab-cased identifier for the skill (e.g., api-design-principles).
name: A human-readable title for the skill (e.g., API Design Principles).
description: A concise summary of what the skill does. This is used for search results and brief overviews.
category: A broad classification for the skill (e.g., Backend, Frontend, DevOps, Security, Productivity).
tags: A list of keywords that further describe the skill, aiding in discovery (e.g., python, fastapi, rest, api).
tools: A list of AI assistants or platforms this skill is primarily designed for or compatible with (e.g., claude, cursor, gemini-cli, copilot).
version: The version of the skill, following semantic versioning (e.g., 1.0.0).
updated_at: The last modification date of the skill (ISO 8601 format, e.g., 2024-07-29T10:30:00Z).

Example Front Matter:

---
id: rest-api-template
name: Generate REST API Template
description: Generates a production-ready REST API template using FastAPI with best practices for pagination, filtering, and error handling.
category: Backend
tags:
  - python
  - fastapi
  - rest
  - api-design
  - code-generation
tools:
  - claude
  - cursor
  - gemini-cli
version: 1.1.0
updated_at: 2024-07-29T14:15:30Z
---

2. Content Sections (Markdown)

The main body of the SKILL.md is organized using Markdown headings. Each heading defines a specific aspect of the skill, providing a structured prompt for AI agents.

Mandatory Content Sections:

## Skill: This is the core instruction. It should clearly define the task, its objective, and the agent's role.
## Inputs: Specifies all necessary information the agent needs to begin the task. This might include file paths, user requirements, existing code snippets, or configuration details. Use clear descriptions and examples for each input.
## Outputs: Describes the expected deliverables. This includes the format (e.g., code, JSON, Markdown), specific files to be created or modified, and any reporting requirements.
## Examples: Provides one or more concrete use cases demonstrating how the skill should be applied and what the expected interaction/output looks like.

Common Optional Content Sections:

## Constraints: Defines limitations, non-negotiables, security considerations, or performance targets. These are critical for guiding agents to stay within defined boundaries.
## Principles: Outlines the underlying principles or best practices that should be followed during execution (e.g., "Follow SOLID principles," "Prioritize readability").
## Tools: Lists and describes any external tools, libraries, or scripts that the agent can or should utilize. If the skill includes executable assets (like api_validator.py or api_bench.py seen in the codebase), this section can instruct the agent on how to use them.
## Assets: Refers to any supplementary files included with the skill, such as code templates (rest-api-template.py), configuration files, or schemas. The agent should be instructed on how to access and use these.
## Testing: Provides guidelines or explicit steps for testing the output generated by the agent.
## Usage: Offers specific instructions on how a human user might invoke or interact with this skill within their chosen AI assistant.
## See Also: Links to related skills, bundles, or external documentation for further context.

Reusable Skill Template

Use this template as a starting point for creating new SKILL.md files. Remember to fill in all front matter fields and customize the content sections to precisely define your skill.

---
id: your-skill-id-kebab-case # Unique identifier (e.g., refactor-python-code)
name: Your Skill Name # Human-readable title (e.g., Refactor Python Code)
description: A brief, clear description of what this skill achieves. # Max ~1-2 sentences for search/overview.
category: Your Category # E.g., Backend, Frontend, DevOps, Security, AI, Utility
tags:
  - tag1
  - tag2
  - tag3 # Keywords for better discoverability (e.g., python, refactoring, code-quality)
tools:
  - tool1
  - tool2 # AI assistants this skill is optimized for (e.g., claude, cursor, gemini-cli)
version: 1.0.0 # Semantic versioning
updated_at: YYYY-MM-DDTHH:MM:SSZ # Last update date (ISO 8601 format)
---

## Skill

[MANDATORY] Clearly and concisely state the primary objective of this skill. What task should the AI agent perform? What is the desired outcome?

*Example:* Refactor the provided Python code snippet to improve readability, adherence to PEP 8, and modularity, without altering its core functionality. The refactored code should be easily testable.

## Inputs

[MANDATORY] Detail all information the AI agent will receive or needs to access to execute this skill. Use clear formatting (e.g., bullet points, code blocks) for each input.

*   **`[Input Parameter 1 Name]`**: A description of the input, its format, and what it represents.
    *Example:* **`python_code`**: The Python code snippet to be refactored, provided as a multiline string or file content.
*   **`[Input Parameter 2 Name]`**: ...
    *Example:* **`context_file_path` (Optional)**: The path to a file containing additional context, such as a `requirements.txt` or `.env` file, if external dependencies or environment variables are relevant.

## Outputs

[MANDATORY] Specify the exact format and content expected as the final output. What files should be created/modified? What should the output structure be?

*   **Refactored Code**: The complete, refactored Python code, presented in a Markdown code block.
*   **Summary of Changes**: A brief explanation of the key refactorings applied and their benefits.
*   **Potential Improvements (Optional)**: A list of further improvements that could be made but were not part of this specific refactoring task.

## Constraints

[OPTIONAL, but highly recommended for agentic tasks] Define any limitations, guardrails, or non-negotiable requirements for the task.

*   **No Functional Changes**: The refactoring must not introduce any bugs or change the observable behavior of the code.
*   **PEP 8 Compliance**: All generated code must strictly adhere to PEP 8 style guidelines.
*   **Efficiency**: Maintain or improve the original code's time and space complexity.
*   **Security**: Do not introduce any security vulnerabilities.

## Principles

[OPTIONAL] Outline the guiding principles or design philosophies the agent should follow.

*   **Readability**: Prioritize code that is easy for humans to read and understand.
*   **Modularity**: Break down complex logic into smaller, reusable functions or classes.
*   **Idempotence**: Operations should be repeatable without causing unintended side effects (if applicable).

## Tools

[OPTIONAL] List any external tools or scripts the agent should consider using. If the skill includes executable scripts, instruct the agent on how to use them.

*   **`pylint`**: For static code analysis and adherence to style guides.
*   **`black`**: For automatic code formatting according to PEP 8.
*   **`plugins/antigravity-awesome-skills-claude/skills/code-analyzer/scripts/analyzer.py`**: Use this script to get an initial analysis of the provided Python code's complexity and potential issues before refactoring.
    *   *Usage Example*: `python scripts/analyzer.py --file <path_to_code>`

## Assets

[OPTIONAL] Reference any supporting files or templates bundled with this skill.

*   **`plugins/antigravity-awesome-skills-claude/skills/rest-api-template/assets/rest-api-template.py`**: A FastAPI template file that can be used as a reference for common API patterns.

## Examples

[MANDATORY] Provide concrete examples of how this skill would be used, including input and expected output.

### Example 1: Basic Function Refactoring

**User Input/Context:**

```python
# Original code (input.py)
def calculate_total_price(item_price, quantity, discount_percentage):
    discount_amount = (item_price * quantity) * (discount_percentage / 100)
    final_price = (item_price * quantity) - discount_amount
    return final_price

price = 100
qty = 5
disc = 10
total = calculate_total_price(price, qty, disc)
print(f"Total price: {total}")

Agent Expected Output:

# Refactored Code
def calculate_final_price(item_price: float, quantity: int, discount_percentage: float) -> float:
    """
    Calculates the final price of items after applying a discount.

    Args:
        item_price: The price of a single item.
        quantity: The number of items.
        discount_percentage: The discount percentage to apply (0-100).

    Returns:
        The final price after discount.
    """
    base_price = item_price * quantity
    discount_factor = discount_percentage / 100
    discount_amount = base_price * discount_factor
    final_price = base_price - discount_amount
    return final_price

if __name__ == "__main__":
    price = 100.0
    qty = 5
    disc = 10.0
    total = calculate_final_price(price, qty, disc)
    print(f"Total price: {total}")

Summary of Changes:

Renamed calculate_total_price to calculate_final_price for clarity.
Added type hints for better code readability and maintainability.
Introduced intermediate variables base_price and discount_factor to improve step-by-step understanding.
Added a comprehensive docstring explaining the function's purpose, arguments, and return value.
Wrapped example usage in an if __name__ == "__main__": block.

undefined

Skill Anatomy & Template