What Are Agent Skills? The Open SKILL.md Standard Explained

Agent Skills are folders in a repository — each containing a SKILL.md file with YAML frontmatter (name, description) plus detailed instructions and examples — that an AI coding agent loads on demand when a task matches. They turn one-off prompts into reusable, portable capabilities that the same repository can offer to GitHub Copilot, Codex-style tools, and Claude alike.

Introduction

Most teams that adopt AI coding assistants hit the same wall. The assistant is helpful, but it forgets your conventions the moment a new chat starts. So developers paste the same context over and over: “remember, we use kebab-case slugs,” “our blog posts need an answer block,” “run the tests this way.”

Agent Skills exist to end that repetition. Instead of living in a developer’s head or a scratchpad, a skill lives in the repository as a small, structured document the agent can discover and load exactly when it is relevant.

This is the first article in a 10-part series on building an agent-ready repository. We start with the foundational question: what actually is an Agent Skill, and why is the format worth standardizing on?

What Is an Agent Skill?

An Agent Skill is a self-contained, task-specific capability defined as a folder with a single SKILL.md file at its root. The file has two parts:

YAML frontmatter — machine-readable metadata, most importantly a name and a description.
A Markdown body — human- and agent-readable instructions, examples, and guidance on when and how to use the skill.

The convention is simple and predictable:

.github/skills/
├── blog-post/
│   └── SKILL.md
├── image-optimization/
│   └── SKILL.md
└── xeo-optimization/
    └── SKILL.md

The folder name is the skill’s identity. The SKILL.md inside carries the rules. That is the whole standard — deliberately minimal so that any agent can parse it.

The Anatomy of a SKILL.md File

A well-formed skill reads like documentation written for a capable but context-free colleague. Here is the minimum viable shape:

---
name: blog-post
description: Skill for creating blog posts in Astro content collections
---

# Blog Post Skill

## When to Use

- Writing new blog articles
- Publishing technical tutorials

## Trigger Phrases

- "write a blog post"
- "draft a tutorial"

## Before/After Example

Before (weak, no metadata):

...

After (complete frontmatter + strong opener):

...

The name gives the skill a stable handle. The description is the single most important line in the file, because it is what an agent reads to decide whether the skill is relevant to the task in front of it. Everything below the frontmatter is the actual procedure: steps, templates, validation rules, and examples.

Why Not Just Use a Big Prompt?

You could stuff every convention into one giant system prompt. Teams try this, and it fails for predictable reasons:

It does not scale. A single prompt covering blog posts, image optimization, and testing becomes unreadable and contradicts itself.
It wastes context. The agent carries rules about image formats while writing a database migration, crowding out the details that actually matter.
It is not discoverable. Nobody knows which rule fired or why.

Skills solve this by being modular and loaded on demand. The agent pulls in the blog-post skill when — and only when — the task is about writing a post. The rest of the time, that context stays out of the way.

Skills vs. Instructions vs. Agents

Agent Skills are one of three complementary building blocks, and confusing them is the most common setup mistake:

Building block	Answers the question	Lives in
Custom instructions	What are our project-wide rules?	`.github/instructions/` or `copilot-instructions.md`
Agents (personas)	Who is doing the work, and what are their boundaries?	`.github/agents/`
Skills	How do I perform this specific task, step by step?	`.github/skills/<name>/SKILL.md`

Instructions are always-on guardrails. Personas define a role. Skills are the procedural know-how loaded when relevant. Keep procedure out of personas and instructions, and keep broad standards out of skills — a separation we return to throughout this series.

Why the Open Format Matters

The real payoff of the SKILL.md convention is portability. Because the format is just a folder, a metadata block, and Markdown, it is not tied to one vendor. A skill written for GitHub Copilot is readable by Codex-style tools and by Claude, because none of them need a proprietary schema to understand “here is a named capability with a description and instructions.”

That means your investment in writing good skills is durable. Switch tools, add a second agent, or hand the repository to an external team, and the skills travel with the code. This is exactly the kind of built-in maintenance layer we described in External Developer Standards for Agentic Software Development in 2026 — the repository teaches every future contributor, human or AI, how to work inside it.

Key Takeaways

An Agent Skill is a folder plus a SKILL.md file with name/description frontmatter and a Markdown body of instructions and examples.
Skills are loaded on demand, keeping the agent’s context focused and your conventions consistent.
Skills, custom instructions, and agent personas are distinct — procedure belongs in skills.
The open format is portable across Copilot, Codex, and Claude, so the work you invest is not locked to one tool.

Frequently Asked Questions

What is an Agent Skill?

An Agent Skill is a reusable capability for AI coding agents, stored as a folder containing a SKILL.md file. The file has YAML frontmatter with a name and description, followed by Markdown instructions and examples that tell the agent how and when to perform a specific task.

Where do Agent Skills live in a repository?

By convention they live in .github/skills/<skill-name>/SKILL.md, with one folder per skill. The folder name is the skill’s identity, and the SKILL.md file inside holds its metadata and instructions.

How is a skill different from a custom instruction?

Custom instructions are always-on, project-wide rules such as coding standards. A skill is task-specific procedural knowledge that is loaded only when a relevant task appears. Instructions set the guardrails; skills carry the step-by-step how-to.

Do Agent Skills work with tools other than GitHub Copilot?

Yes. Because the format is an open convention — a folder, a metadata block, and Markdown — the same skill can be read by Codex-style tools and Claude-style agents, not just Copilot. That portability is a core reason to adopt the standard.

Conclusion

Agent Skills turn scattered, repeated prompts into a durable, discoverable capability layer that lives with your code. The format is intentionally small, which is precisely why it works across tools and survives handoffs.

In the next article we go one level up and lay out the full .github/ directory — where skills, agents, and instructions sit, and how they fit together.

Want a repository that ships with this maintenance layer built in? Explore the ByblosAI platform, see how our 22 AI agents redefine delivery standards, or contact us to talk through your setup.