what are
agent skills?

What is an Agent Skill?

An Agent Skill is a versionable package of procedural knowledge for one job: reviewing pull requests, preparing presentations, analyzing spreadsheets, publishing releases, or following a team's incident process. The open format makes the workflow inspectable and reusable without retraining a model or pasting the same long prompt into every conversation.

A skill is not a separate AI agent, model, or marketplace listing. It is a folder an existing agent can discover and load. The official Agent Skills overview describes the format as lightweight and open, while the specification defines the required files and metadata.

How do Agent Skills work?

1. Discovery: the client reads each skill's name and description so it can match a task without loading every manual.
2. Activation: when the user invokes a skill or the task matches its description, the agent loads the full SKILL.md.
3. Execution: the agent follows the workflow and reads referenced files or runs permitted scripts only when they are needed.

This progressive disclosure keeps the startup context small while making deeper instructions available on demand. The description therefore acts as routing metadata: it should say both what the skill does and when it should be used.

What is a SKILL.md file?

SKILL.md is the required entry point inside a skill folder. It starts with YAML frontmatter containing at least name and description, followed by Markdown instructions. The name must match the parent folder and use lowercase letters, numbers, and hyphens.

research-brief/
├── SKILL.md
├── references/
│   └── source-policy.md
└── assets/
    └── brief-template.md

---
name: research-brief
description: Researches a focused question and writes a cited brief. Use when the user asks for primary-source research or a decision memo.
---

# Research brief

1. Confirm the question and finish condition.
2. Prefer primary, current sources.
3. Separate sourced facts from inference.
4. Write the brief with links beside each claim.
5. Verify every requested point before finishing.

Optional scripts/, references/, and assets/ folders keep deterministic operations, deep documentation, and reusable templates out of the main instructions until needed. Follow the complete creation guide to turn this minimum into a tested skill.

Which AI tools support Agent Skills?

The open format is supported by a growing group of clients. Current official documentation covers Claude Code, OpenAI Codex, VS Code and GitHub Copilot, and Gemini CLI. Cursor and other compatible clients also discover SKILL.md folders.

Portability does not mean every client behaves identically. Project and personal installation paths, invocation syntax, optional frontmatter, tool permissions, and live reload behavior can differ. Keep the core workflow standard, document tested clients, and verify current product documentation before claiming compatibility.

How are Agent Skills different from prompts, agents, rules, and MCP?

Use a skill for repeatable know-how and MCP for standardized connectivity. A skill can instruct an agent how to use an MCP tool safely. Read the Agent Skills versus MCP guide for architecture and security boundaries, or compare SKILL.md, AGENTS.md, and CLAUDE.md when organizing repository instructions.

What are useful Agent Skill examples?

• Code review: inspect a diff against repository rules and finish with reproducible findings.
• Research: gather primary sources, separate evidence from inference, and write a cited brief.
• Document production: transform source material into a branded report using bundled templates.
• Incident response: collect diagnostics, protect evidence, follow escalation rules, and verify recovery.
• Publishing: validate an artifact, generate release notes, and run a documented deployment checklist.

The best examples solve a narrow recurring job with an observable finish condition. Explore the live Agent Skills rankings or browse the catalog to inspect real manuals and source repositories.

Are Agent Skills safe?

A text-only skill can still influence an agent that reads files, calls tools, executes commands, or accesses credentials. Treat every instruction and referenced resource as part of the security boundary. Verify the source and revision, read the complete folder, inspect scripts and dependencies, minimize permissions, and test on a reversible task before important use.

Directory inclusion, stars, and install counts are discovery signals, not security certification. Use the Agent Skill security checklist before adoption and the safe installation guide for client-specific setup and removal.

Where can you find or create Agent Skills?

Use the Agent Skills directory comparison to choose a discovery source by ranking method, source evidence, and submission path. When no existing workflow fits, create one narrow skill, test positive and negative triggers, publish it from an inspectable repository, and follow the publishing guide to document compatibility and trust signals.

What do beginners ask about Agent Skills?

Which primary sources define Agent Skills?

This guide was checked against the Agent Skills overview and open specification, plus current documentation from Anthropic, OpenAI, Microsoft, and Google. Client behavior changes, so verify paths and optional fields before installation.