What Are Skills?

Skills are reusable sets of instructions that teach AI coding agents how to perform specific tasks. Think of them as specialized playbooks: each skill is a document that your agent reads before carrying out a particular workflow. When you invoke a skill, the agent loads its instructions into context and follows them step by step.

This pattern works across agent platforms — Claude Code calls them Skills, Cursor and Windsurf use Rules, GitHub Copilot has Custom Instructions, OpenAI's Codex uses task templates, and Google's Gemini CLI uses GEMINI.md files. The underlying concept is the same: structured documents that shape how your agent behaves.

The Mental Model

If your AI coding agent is a capable assistant, skills are the playbooks you hand it. Without skills, the agent relies entirely on its general training. With skills, you can encode your team's conventions, preferred patterns, and domain-specific knowledge into precise, repeatable instructions.

A skill is not code that executes. It is a prompt document that shapes the agent's behavior. The distinction matters: skills influencehow the agent thinks and acts, but the agent is still the one doing the thinking and acting.

How Skills Are Invoked

The invocation mechanism varies by platform, but the concept is consistent — you trigger a named set of instructions:

• Claude Code — Skills become slash commands. Create commit-msg/SKILL.md and invoke it with /commit-msg.
• Cursor — Rules are loaded from .cursor/rules/ and applied automatically or by reference.
• Windsurf — Rules live in .windsurf/rules/ and are triggered by context or explicitly.
• GitHub Copilot — Custom instructions are defined in .github/copilot-instructions.md or via VS Code settings.
• OpenAI Codex — Uses an agents.md file and task-level instructions to guide agent behavior.
• Gemini CLI — Uses GEMINI.md files for project-level instructions, similar to CLAUDE.md.

Throughout this curriculum, we use Claude Code's SKILL.md format as the primary teaching example because it has the richest feature set (tool permissions, dynamic context, subagents). The patterns you learn translate directly to other platforms.

A Minimal Skill

Here is the simplest possible skill. It uses YAML frontmatter for metadata and Markdown for instructions — a pattern shared across platforms:

---
description: Generate a concise commit message for staged changes
---

Look at the currently staged git changes (use `git diff --cached`).

Write a conventional commit message that:
- Starts with a type prefix (feat, fix, docs, refactor, test, chore)
- Has a concise subject line under 72 characters
- Optionally includes a body for complex changes

Do NOT commit the changes — only output the message.

That is it. The YAML frontmatter between the --- fences provides metadata (here, just a description). The Markdown body below is the instruction set your agent will follow.

The Skill Lifecycle

When you invoke a skill, most agent platforms follow these steps:

1. Discovery — The agent scans known skill locations and builds a registry of available skills. Typically only the metadata (description) is loaded at this stage, keeping memory usage low.
2. Selection — When you trigger a skill (via slash command, rule match, or explicit reference), the full content is loaded into context.
3. Execution — The agent follows the instructions in the skill body. It may use tools (shell commands, file editing, web search) depending on what the instructions say and what permissions are configured.
4. Completion — The agent finishes the task and returns output to you, just like any other interaction.

This progressive-disclosure model is important: metadata is cheap to keep in context, while full instructions are only loaded when needed.

When to Use Skills

Skills shine in several scenarios:

• Repeated workflows — Generating commit messages, creating components, writing tests, deploying services.
• Team conventions — Encoding code style preferences, PR templates, review checklists.
• Complex multi-step tasks — Database migrations, refactoring patterns, release workflows.
• Onboarding — New team members get instant access to institutional knowledge through project-level skills.

Skills vs. Global Configuration

Every platform has a distinction between always-on configuration and on-demand skills:

• Always-on config is loaded into every interaction. In Claude Code this is CLAUDE.md; in Cursor it's the root .cursorrules file; in Copilot it's the instructions file. Use this for universal rules ("always use TypeScript strict mode").
• Skills are loaded on demand. They provide focused instructions for specific tasks and are only brought into context when invoked. Use these for task-specific playbooks ("here is how we create a new API endpoint").

What's Next

Now that you have the mental model, the next lesson dives into the anatomy of a skill file — the frontmatter fields, the Markdown body, and how agents read them.