Developing Custom Agent Plugins

Developing Custom Agent Plugins

Antigravity Awesome Skills provides a robust collection of agentic SKILL.md playbooks and supporting code designed to enhance the capabilities of various AI coding assistants. For developers looking to extend their AI agents, building custom plugins allows direct integration with these skills, transforming abstract instructions into executable actions within the agent's environment.

This section guides you through the concepts and practical steps for developing plugins that leverage Antigravity Awesome Skills.

What are Antigravity Agent Plugins?

An Antigravity agent plugin acts as a bridge, enabling your AI agent to understand, execute, and respond to the structured instructions defined in SKILL.md files. Instead of manually copying and pasting prompt snippets, a plugin allows an AI agent to programmatically discover, interpret, and invoke these skills, often through function calls or specialized commands.

Key benefits of developing plugins:

• Extend Agent Capabilities: Grant your AI agent access to a vast, curated library of programming, debugging, and operational skills.
• Automate Complex Tasks: Chain multiple skills or integrate them into workflows for sophisticated automation.
• Ensure Consistent Execution: Standardize how your agent performs recurring tasks by enforcing the logic defined in SKILL.md and its associated scripts.
• Maintain Up-to-Date Skills: Programmatically sync with the latest skills from the Antigravity repository, ensuring your agent always uses the most current best practices.

Understanding Antigravity Skills (SKILL.md)

At its core, each Antigravity skill is a SKILL.md file – a Markdown document containing structured operating instructions. These instructions guide an AI agent through a specific task, often detailing inputs, steps, and expected outputs.

Many skills are complemented by executable helper scripts, configuration files, or templates that provide the concrete tooling for the agent to use. For example, a skill focused on API validation might reference a Python script (api_validator.py) to perform static analysis of an OpenAPI specification.

Plugin Responsibilities

A well-designed plugin typically handles the following responsibilities:

1. Skill Discovery and Loading:

   • Identifying where Antigravity skills are located (e.g., cloned repository, installed npm package).
   • Parsing SKILL.md files and any associated metadata (YAML frontmatter, specific Markdown headings) to understand the skill's purpose, parameters, and executable components.

2. Skill Interpretation:

   • Translating the natural language instructions within SKILL.md into actionable logic for the agent. This might involve extracting specific commands, file paths, or API endpoints.

3. Tool Integration and Execution:

   • Invoking the underlying helper scripts or applications that define the skill's functionality. This often involves executing command-line scripts (.py, .sh, etc.) via subprocess or similar mechanisms, or setting up and interacting with local API servers (as seen with FastAPI-based skills).

4. Agent Interface Mapping:

   • Exposing the skill to the AI agent through its native tool-calling or command-line interface. This involves defining function signatures (for models like Claude Code or OpenAI's function calling) or specific commands (for CLI tools like Gemini CLI or Cursor).
   • Managing input parameters and converting them into arguments for the underlying scripts.

5. Output Parsing and Formatting:

   • Capturing the output from executed scripts.
   • Parsing structured outputs (JSON, CSV, logs) into a format the AI agent can easily consume and act upon.
   • Handling errors and providing meaningful feedback to the agent.

Developing a Custom Plugin: A Conceptual Walkthrough

Let's consider how you might build a plugin to enable your AI agent to use an Antigravity skill like "Validate API Design" (hypothetically leveraging api_validator.py).

1. Choose Your Agent

First, identify the AI coding assistant you are targeting. Each agent has its own way of integrating external tools or plugins. For example:

• Claude Code/OpenAI Function Calling: Define Python functions with @tool decorators.
• Cursor/Codex CLI: Define custom commands or scripts that the IDE/CLI can execute.
• Gemini CLI: Extend its capabilities via custom commands.

2. Access Antigravity Skills

The Antigravity Awesome Skills library can be installed via npm, making its file structure accessible.

npm install antigravity-awesome-skills
# or clone the repository:
# git clone https://github.com/sickn33/antigravity-awesome-skills.git

Your plugin will need to know the path to the installed skills. If installed via npm, skills are typically in node_modules/antigravity-awesome-skills/skills/.

3. Design the Skill Interface for Your Agent

For an "API Validator" skill, your agent might expose a function like validate_api_spec(file_path: str) -> str.

4. Implement Skill Execution Logic

This is where your plugin invokes the actual skill-related scripts. You'll read the SKILL.md to understand how to use api_validator.py. A minimal Python plugin function might look like this:

import subprocess
import json
import os
from pathlib import Path

# Assume antigravity_skills_path points to the root of the installed skills
ANTIGRAVITY_SKILLS_PATH = Path("./node_modules/antigravity-awesome-skills/skills")
# Or if cloned: ANTIGRAVITY_SKILLS_PATH = Path("./antigravity-awesome-skills/skills")

def validate_api_spec(spec_file_path: str) -> str:
    """
    Validates an API specification file using the Antigravity API Validator skill.

    Args:
        spec_file_path: The path to the OpenAPI/Swagger specification file.

    Returns:
        A JSON string detailing validation results (issues, passed checks).
    """
    validator_script = (
        ANTIGRAVITY_SKILLS_PATH / "api-patterns/scripts/api_validator.py"
    )

    if not validator_script.exists():
        return f"Error: API Validator script not found at {validator_script}"

    if not Path(spec_file_path).exists():
        return f"Error: Specification file not found at {spec_file_path}"

    try:
        # Execute the api_validator.py script
        # The script is designed to output JSON when run with --json (implied by content)
        # Note: The provided api_validator.py does not have a --json flag,
        # so this example assumes we'd modify or wrap it to get JSON output,
        # or parse its stdout. For demonstration, we'll parse its direct output.
        result = subprocess.run(
            ["python3", str(validator_script), str(Path(spec_file_path))],
            capture_output=True,
            text=True,
            check=True,
            encoding='utf-8' # Ensure correct encoding for output
        )

        # The api_validator.py script prints results directly.
        # We'd parse this output, potentially looking for "issues" and "passed" markers.
        # For a real plugin, you'd ideally modify api_validator.py to output JSON directly.
        
        # For this example, let's assume a simplified parsing of its stdout
        # In a production plugin, you'd likely enhance api_validator.py itself to return structured data.
        output_lines = result.stdout.strip().split('\n')
        validation_report = {
            "file": spec_file_path,
            "summary": "Validation complete",
            "details": output_lines
        }
        return json.dumps(validation_report, indent=2)

    except subprocess.CalledProcessError as e:
        return f"Error executing API validator: {e.stderr}"
    except Exception as e:
        return f"An unexpected error occurred: {str(e)}"

# Example Usage (in your agent's context):
# agent_tool_call_response = validate_api_spec("/path/to/my_api.openapi.json")
# print(agent_tool_call_response)

5. Handle Outputs and Errors

Ensure your plugin captures and formats the output from the invoked scripts in a way that is consumable by your AI agent. This might involve:

• Structured Data: If the script outputs JSON, directly return the parsed JSON.
• Text Summaries: If the script outputs plain text, you might need to summarize or extract key findings.
• Error Reporting: Clearly indicate failures and provide relevant error messages from the underlying scripts.

Example: Serving a Local API with a Skill

Some Antigravity skills, like the "Instagram Dashboard API" (plugins/antigravity-awesome-skills-claude/skills/instagram/scripts/serve_api.py), involve launching a local API server. A plugin for such a skill would:

1. Receive a request to start the Instagram dashboard.
2. Launch serve_api.py in a background process (e.g., using subprocess.Popen).
3. Provide the agent with the local API endpoint (e.g., http://localhost:8000/).
4. Optionally, offer functions to interact with this local API (e.g., get_instagram_posts()).

Considerations and Best Practices

• Security: Be mindful of running external scripts. Sanitize all inputs from the AI agent before passing them to subprocess calls to prevent command injection vulnerabilities. Ensure the scripts you execute are trusted.
• Environment Management: Ensure the execution environment for your plugin has all necessary dependencies (e.g., Python packages like fastapi, uvicorn, psutil). You might need to manage virtual environments.
• Configuration: Externalize sensitive information (API keys, database paths) and allow the agent or plugin to configure them.
• Error Handling: Implement robust error handling within your plugin to gracefully manage issues like missing scripts, invalid inputs, or script execution failures. Provide clear, concise error messages back to the AI agent.
• Asynchronous Operations: For long-running tasks or API servers, consider using asynchronous programming (asyncio in Python) to avoid blocking your agent.
• Idempotency: Design your plugin functions to be idempotent where possible, meaning calling them multiple times has the same effect as calling them once.
• Testing: Thoroughly test your plugin's integration with both the Antigravity skills and your target AI agent.

By following these guidelines, you can build powerful and reliable plugins that empower your AI agents with the extensive capabilities of Antigravity Awesome Skills.