Agent Skills — Open Standard for AI Agent Capabilities

Agent Skills are a lightweight, open format for giving AI agents specialized knowledge and repeatable workflows. Originally developed by Anthropic and adopted across the ecosystem — Claude Code, Gemini CLI, Antigravity CLI, OpenCode, Cursor, GitHub Copilot, and many more.

What Are Agent Skills?

A skill is a folder containing a SKILL.md file with metadata and instructions telling an agent how to perform a specific task. Skills can bundle scripts, reference materials, templates, and other resources:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Why Skills?

Agents are increasingly capable but often lack the context they need for reliable real-world work. Skills solve this by packaging procedural knowledge into portable, version-controlled folders:

• Domain expertise — Capture specialized knowledge (legal review, data analysis, presentation formatting) as reusable instructions
• Repeatable workflows — Turn multi-step tasks into consistent, auditable procedures
• Cross-product reuse — Build a skill once, use it across any skills-compatible agent

Progressive Disclosure

Progressive disclosure allows agents to handle large numbers of capabilities efficiently:

Agents load skills progressively, pulling in more detail only as a task calls for it:

An agent with 20 installed skills doesn't pay the token cost of 20 full instruction sets upfront — only the ones actually used in a given conversation.

The SKILL.md Format

---
name: my-skill-name
description: |
  A short description that tells agents when this skill is relevant.
  Be specific about what the skill does, what it's for, and when to use it.
---

# Clear instructions for the agent

Write the skill instructions in plain language. Include specific steps,
conventions, and examples. The agent will follow these instructions
when the skill is activated.

## Resources

- Reference files are in the `references/` directory
- Templates are in the `assets/` directory
- Scripts are in the `scripts/` directory

Frontmatter Fields

Best Practices

• Be specific in the description — This is what agents use to decide if the skill is relevant. Include keywords, use cases, and boundaries
• Keep instructions focused — One skill = one capability. Don't bundle unrelated tasks
• Include examples — Show the agent what good output looks like
• Version your skills — Use git for change tracking and collaboration
• Test with multiple agents — Skills are cross-platform; verify they work across your toolchain

Supported Agents

Creating a Skill

Step 1: Create the skill folder

mkdir -p my-skill/{scripts,references,assets}

Step 2: Write SKILL.md

---
name: python-docstring-review
description: |
  Reviews Python docstrings for completeness and consistency.
  Checks for: parameter documentation, return value description,
  raised exceptions, and type annotations.
  Use after writing new functions or when reviewing PRs.
---

# Python Docstring Review Checklist

When asked to review docstrings, check each function for:

1. **Summary line** — Does the first line describe what the function does?
2. **Parameters** — Are all params documented with types?
3. **Returns** — Is the return value described?
4. **Raises** — Are exceptions documented?
5. **Types** — Are type hints consistent with the docstring?

## Numpy style (preferred)

```python
def process_data(input: list[int]) -> dict[str, float]:
    """Process input data and return summary statistics.

    Parameters
    ----------
    input : list[int]
        List of integer values to process.

    Returns
    -------
    dict[str, float]
        Summary statistics including mean, median, and std.
    """

Google style (acceptable)

def process_data(input: list[int]) -> dict[str, float]:
    """Process input data and return summary statistics.

    Args:
        input: List of integer values to process.

    Returns:
        dict containing mean, median, and std.
    """

### Step 3: Test with your agent

```bash
# In Antigravity CLI
> Write a Python function and verify its docstring

The agent auto-discovers skills in .agents/ at startup — no manual activation needed.

Using Skills in Antigravity CLI

Antigravity CLI (and Gemini CLI) auto-load skills from the project's .agents/ directory at startup. List available skills:

> /skills

See the Antigravity CLI Configuration for skill storage paths and plugin installation.

Using Skills in Claude Code

Claude Code loads skills from ~/.claude/skills/ or .claude/skills/ at project root. List available skills:

> /skills

Skills are community-contributed. See the Claude Code docs for installation.

Implementation Blueprint for Agent Developers

Discovery Scopes & Override Precedence

Skills are scanned from multiple scopes at session startup:

Shadowing rule: Project-level skills override user-level skills of the same name. Within the same scope, first-found wins (be consistent). Log a warning when a collision occurs.

Activation Patterns

Two approaches for delivering skill content to the model:

File-read activation — The model reads SKILL.md via its standard file-read tool using the path from the catalog. Simplest approach, requires no special infrastructure.

Dedicated tool activation — Register an activate_skill(name) tool that returns the skill content. Advantages: control over what content is returned (strip frontmatter or keep it), structured wrapping with identifying tags, permission enforcement, and activation tracking. Constrain the name parameter to valid skill names to prevent hallucinated skills.

Context Pruning Protection

Active skill instructions must be exempt from context compaction. If your agent truncates or summarizes older messages when the context window fills up, flag skill tool outputs as protected. Losing skill instructions mid-conversation silently degrades the agent's performance without any visible error.

Approaches: use structured tags to identify skill content during compaction, or mark tool outputs as protected in the pruning algorithm.

Trust Considerations

Project-level skills come from the repository being worked on, which may be untrusted (e.g., a freshly cloned open-source project). Gate project-level skill loading on a trust check — only load them if the user has marked the project folder as trusted. This prevents untrusted repositories from silently injecting instructions into the agent's context.

Related

• Agent Skills Official Site — Specification, quickstart, and client showcase
• Implementation Guide: Adding Skills Support to Your Agent — Full lifecycle guide for tool developers
• Antigravity CLI Configuration — Skills paths and plugin setup
• Agent Memory Architectures — How memory relates to skill execution
• SkillOpt: Training Agent Skill Documents — Optimizing skill documents for agent performance