Agent Skills

Agent Skills Standard

You are an expert in the Agent Skills open standard, the portable format for extending AI agents with specialized capabilities.

What Is a Skill?

A skill is a directory containing a SKILL.md file plus optional supporting files. Skills package domain-specific knowledge and workflows that agents can use to perform tasks. Skills are portable across any agent that supports the standard.

Directory Structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
├── assets/           # Optional: templates, images, data files
└── ...               # Any additional files

SKILL.md Format

The file must contain YAML frontmatter followed by Markdown content:

---
name: skill-name
description: What this skill does and when to use it.
---

# Skill Name

Detailed instructions for the agent.

## When to Use
- Specific triggers and use cases

## Instructions
- Step-by-step guidance

Frontmatter Fields

| Field | Required | Constraints | |-------|----------|-------------| | name | Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. Must match parent directory name. | | description | Yes | Max 1024 chars. Describes what the skill does AND when to use it. | | license | No | License name or reference to bundled license file. | | compatibility | No | Max 500 chars. Environment requirements. | | metadata | No | Arbitrary key-value mapping. |

Name Field Rules

• 1-64 characters
• Only lowercase alphanumeric and hyphens
• No leading, trailing, or consecutive hyphens
• Must match the parent directory name

Description Best Practices

• Describe both WHAT the skill does and WHEN to use it
• Include specific keywords that help agents identify relevant tasks

Progressive Disclosure

Skills are loaded in stages for context efficiency:

1. Metadata (~100 tokens): name and description loaded at startup
2. Instructions (< 5000 tokens recommended): Full SKILL.md body loaded when activated
3. Resources (as needed): Supporting files loaded only when required

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

Optional Directories

scripts/

Executable code agents can run. Should be self-contained with helpful error messages.

references/

Additional documentation loaded on demand. Keep files focused and small.

assets/

Static resources: templates, images, schemas, data files.

Skill Discovery Locations

Agents scan these directories:

| Location | Scope | Agents | |----------|-------|--------| | .agents/skills/ | Project-level | Primary standard path (all agents) | | .claude/skills/ | Project-level | Claude Code | | .cursor/skills/ | Project-level | Cursor | | .codex/skills/ | Project-level | Codex | | .windsurf/skills/ | Project-level | Windsurf | | .gemini/skills/ | Project-level | Gemini | | .opencode/skills/ | Project-level | OpenCode | | .agent/skills/ | Project-level | Antigravity | | ~/.agents/skills/ | User-level | All agents |

Invocation

• Implicit: Agent automatically activates when task matches the description
• Explicit: User types @skill-name, $skill-name, or selects from skill picker

Reference

Full specification: https://agentskills.io/specification Documentation index: https://agentskills.io/llms.txt

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yiftahb
• Source: yiftahb/agsync
• License: MIT

Install and usage instructions live in the source repository linked above.