Guide

Skills for Beginners

A simple path for understanding how reusable task knowledge becomes an agent Skill.

The problem Skills solve

Agents often know general language and code patterns, but they do not automatically know your team's workflow, domain rules, output format, or preferred validation steps. Skills package that repeatable expertise.

The basic folder

A Skill starts with SKILL.md. That file tells the agent when to use the Skill and what procedure to follow.

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

How activation works

The agent first sees only the Skill name and description. If the user task matches, it loads the full instructions. Extra files are loaded only when the Skill tells the agent to read them.

Catalog shown to the agent:
name: release-notes
description: Draft customer-facing release notes from merged PRs, commits, or changelog entries.

User request:
"Turn these merged PRs into release notes."

Agent action:
Load .agents/skills/release-notes/SKILL.md and follow its workflow.

Practice path

Learn Skills by building one small folder, testing activation, and improving the instructions from real failures.

Build the first Skill

Copy the folder and SKILL.md from Skill Quickstart.

Understand the files

Read Skill Structure so references, scripts, and assets make sense.

Write your own

Use Skill Template as a starting point.

Evaluate it

Run should-trigger and should-not-trigger examples from Evaluate Skills.

Four beginner mistakes

These show up in almost every first attempt at a Skill.

Starting too broad"Help with reports" is not a task. Narrow it to one job you could describe in a single sentence.

Writing the description lastThe description controls activation, so write it first and let it constrain the scope.

Inlining everythingLong references belong in files the Skill reads on demand, not in the main instruction file.

Skipping the failure testIf you never check the cases where the Skill should not activate, it will misfire later.