Skills are the unlock that separates beginners from power users. Instead of re-explaining how you want things done every single time, you save instructions once — and your AI agent automatically uses them when relevant.

This guide will take you from zero to your first working Skill in under 15 minutes.

What Are Skills?

Think of Skills as saved methodology for your AI coding agent.

When you work with an AI agent (in Antigravity, Cursor, or Claude Code), you often find yourself repeating the same instructions:

  • "Always use TypeScript"
  • "Follow this error handling pattern"
  • "Structure my n8n workflows like this"

Skills let you package these instructions once. The agent reads them automatically when the task matches.

The key insight: Skills tell your agent how to do things. MCP tells your agent what tools it can use. Together, they create powerful, context-aware agents.

Skills vs MCP: The Brain and Hands

Skills = The Brain (Methodology)

Skills teach your agent how to approach tasks. They contain instructions, examples, and best practices.

MCP = The Hands (Tools)

MCP (Model Context Protocol) provides the tools — connections to databases, APIs, services.

Example: An MCP server connects your agent to your database. A Skill teaches your agent your data model and query patterns.

You need both for a truly powerful agent.

The Universal Skill Format

Skills follow an open standard that works across all major AI IDEs:

The same SKILL.md file works everywhere. Write once, use anywhere.

Folder Structure Explained

Every Skill lives in its own dedicated folder. Here's the anatomy:

my-skill/
├── SKILL.md              # Required: Main instructions file
├── scripts/              # Optional: Executable scripts
│   └── helper.py
├── templates/            # Optional: Template files
│   └── component.tsx
├── examples/             # Optional: Input/output examples
│   └── example-1.md
└── references/           # Optional: Additional docs
    └── api-reference.md

Why This Structure Matters

  • SKILL.md is the only required file — it's what the agent reads first
  • scripts/ contain code the agent can execute (never enters context window = saves tokens)
  • templates/ provide boilerplate the agent can copy and modify
  • examples/ show the agent what good output looks like
  • references/ hold detailed docs loaded only when needed

The SKILL.md File Format

Every Skill starts with a SKILL.md file. Here's the structure:

---
name: my-skill-name
description: When to use this skill (the "trigger phrase")
---

# Skill Name

## Instructions
Step-by-step guidance for the agent.

## Examples
Input/output pairs to guide behavior.

Breaking It Down

YAML Frontmatter (Required)

  • name: A short identifier (lowercase, hyphens allowed)
  • description: Tells the agent when to activate this Skill. This is the "trigger phrase."

Markdown Body

  • ## Instructions: The actual methodology — what you want the agent to do
  • ## Examples: Show, don't just tell. Input/output pairs are powerful.

How Token Efficiency Works (Progressive Disclosure)

This is why Skills are so powerful:

At Startup: Only the Skill name and description are loaded (~50 tokens)

When Triggered: Full SKILL.md content loads (~500-2000 tokens)

As Needed: Additional resources (scripts, references) load on demand

Compare this to putting everything in your main prompt — you'd burn thousands of tokens on every single request.

Rule of thumb: If instructions apply to less than 20% of conversations, make it a Skill instead of putting it in your main config file.

Your First Skill: Git Commit Formatter

Let's build a simple but useful Skill that formats your git commits consistently.

Step 1: Create the Folder

For Antigravity:

mkdir -p ~/.gemini/antigravity/skills/git-commits

For Claude Code:

mkdir -p ~/.claude/skills/git-commits

For Cursor:

mkdir -p .cursor/skills/git-commits

Step 2: Create SKILL.md

Create a file called SKILL.md in your new folder:

---
name: git-commits
description: Format git commit messages. Triggers on "commit", "git commit", or "write a commit message".
---

# Git Commit Formatter

## Instructions

When writing commit messages, follow this format:

1. **Type prefix**: feat, fix, docs, style, refactor, test, chore
2. **Scope** (optional): Component or area affected in parentheses
3. **Subject**: Imperative mood, lowercase, no period
4. **Body** (optional): Explain what and why, not how

## Format

<type>(<scope>): <subject>

<body>


## Examples

**Input:** "I fixed the login bug where users couldn't reset passwords"

**Output:**

fix(auth): resolve password reset flow for existing users

Users were unable to complete password reset due to expired token

validation. Updated token expiry check to handle edge cases.


**Input:** "Added dark mode"

**Output:**

feat(ui): add dark mode theme support

Step 3: Test It

Open your IDE, start a conversation, and say:

"Write a commit message for: I updated the API to return better error messages"

Your agent should now use your Skill automatically and return something like:

feat(api): improve error message responses

Updated API error handling to return more descriptive messages
for debugging and better user feedback.

The 5 Levels of Skills

As you get more advanced, you can build more sophisticated Skills:

Start at Level 1. Move up as your needs grow.

Connecting Skills to MCP

Skills become even more powerful when combined with MCP servers.

Example Setup:

  1. MCP Server: Connects your agent to n8n (your automation tool)
  2. Skill: Teaches your agent your preferred workflow patterns, node selection, and error handling

When you say "build me a workflow that sends Slack notifications," the agent:

  • Uses the MCP connection to talk to n8n
  • Uses the Skill to know how you like workflows structured

How to Reference MCP in Your Skill

---
name: n8n-workflows
description: Build n8n workflows. Triggers on "workflow", "automation", or "n8n".
---

# n8n Workflow Builder

## Instructions

When building n8n workflows:

1. Always start with a trigger node (Webhook, Schedule, or Manual)
2. Use the n8n MCP connection to create and test nodes
3. Add error handling with a dedicated error branch
4. Log important steps to help with debugging

## My Preferred Patterns

- Use Set nodes to clean data between API calls
- Always add a final "Success" response node
- Name nodes descriptively: "Fetch User Data" not "HTTP Request 1"

Quick Reference: Setup Checklist