What are Agent Skills?

Skills are portable, reusable instructions that extend what AI agents can do. They follow an open specification that works across different agent platforms.

The Core Idea

A skill is a markdown file (SKILL.md) that contains structured instructions for an AI agent. When an agent encounters a task that matches a skill's description, it loads and follows those instructions.

Skills are model-invoked—the agent automatically recognizes when a skill is relevant based on its description and context, then asks permission to use it.

Why Skills?

Portable

Write once, run on any compliant agent—Claude Code, Cursor, Goose, Amp, and more.

Version Controlled

Skills are just files. Check them into git, review changes, and share with your team.

Composable

Skills can reference other skills, building complex capabilities from simple parts.

Auditable

Plain text instructions that humans can read, review, and understand before deployment.

The SKILL.md Format

Every skill is defined in a SKILL.md file with YAML frontmatter for metadata, followed by markdown content with instructions.

Required Fields

nameUnique identifier for the skill (1-64 chars, lowercase, hyphens)

descriptionWhat the skill does—agents use this to match requests (1-1024 chars)

Example SKILL.md

---
name: code-review
description: Reviews code changes for best practices, security issues, and style consistency
license: MIT
---

# Code Review Skill

When reviewing code, analyze for:

## Security
- Check for injection vulnerabilities (SQL, command, XSS)
- Verify input sanitization
- Look for hardcoded secrets

## Best Practices
- Ensure consistent naming conventions
- Verify proper error handling
- Check for adequate test coverage

## Output Format
Provide findings as a numbered list with severity levels.

Skill Directory Structure

Skills can include supporting files alongside the SKILL.md:

my-skill/
├── SKILL.md           # Required: skill definition
├── scripts/           # Optional: executable scripts
│   └── validate.py
├── references/        # Optional: documentation for context
│   └── api-docs.md
└── assets/            # Optional: templates, configs, images
    └── template.json

How Skills Get Loaded

Agent harnesses scan for skills in well-known locations. The exact paths vary by agent, but typically include:

•~/.config/skills/ — Personal skills (user-wide)
•.skills/ — Project skills (repo-specific)
•Enterprise/organization-managed skill directories

Full Specification

The complete Agent Skills specification is maintained as an open standard.

View at agentskills.io

← Back to Learn What is an Agent Harness? →