What are AI agent skills? Build your first skill in minutes

The instructions below the YAML

Everything you write below the YAML front matter is only loaded into context when the skill is actually called. This is where you define how the agent should respond, what style to use, and any examples you want it to follow.

For example:

When the user says "good morning", respond with:
- A greeting that starts with "Hi Debbie"
- A question asking if they have done any sport today
- A short, funny joke about sports

Example interaction:
User: good morning
Assistant: Hi Debbie, have you done any sport today? Here's a funny joke about sports...

This section is your playground: you can make responses personal, add constraints, or show examples that the agent can imitate.

Where skills live in your project

Skills are stored inside a skills folder in your project, usually under a configuration directory. Common locations include:

• .github/skills/
• .agents/skills/
• .claude/skills/ or similar, depending on the tool

Each skill gets its own folder, and inside that folder you place the skill.md file:

.github/
  skills/
    good morning/
      SKILL.md

Note: the file is typically named SKILL.md in all caps, depending on the convention of the agent platform you’re using. The platform looks for that exact file name to detect and load the skill.

Skills are usually project-level, not global. That means they only apply inside the repository or workspace where you define them, which is great for keeping behaviors tailored to each project.

Optional extras: scripts, references, assets, and tests

While skill.md is all you need, you can extend a skill with extra folders to make it much more powerful.

Scripts

A scripts folder can contain code that runs outside the model’s context window. For example, scripts can:

• Scan your project files
• Check or update a README
• Gather data the agent can then use

This is useful because it keeps the context small while still letting the agent interact with your codebase or environment.

References

A references folder holds domain knowledge the agent can pull in only when needed. This might include:

• Best practices documents
• Style guides and tone guidelines
• Architecture or process docs

The agent reads these files on demand, so you can give it rich background information without constantly filling the context window.

Assets

An assets folder is for output templates or reusable files, such as:

• README templates
• Badge definitions in JSON
• Diagrams or visual references

These are especially handy when you’re building more advanced skills like documentation generators or project setup assistants. If that kind of automation interests you, you’ll probably also like building more complex agent workflows, similar to the ones described in this guide on creating an AI marketing audit team with Claude Code.

Tests

Some setups also support a tests or similar folder where you can define prompt-based tests with assertions. These act like unit tests for your skill, helping you confirm that:

• The skill is being called correctly
• The responses follow your rules
• Changes don’t break existing behavior

All of these extras are optional, but they become very valuable as your skills grow more complex.

How context works with skills

One of the most important concepts when working with AI agents is the context window—the limited amount of text the model can “see” at once. Skills are designed to use that space efficiently:

• The YAML front matter (name + description) is always loaded into context when you’re in the project.
• The instructions below are only loaded when the agent decides to call that skill.

This means you should:

• Keep descriptions short but explicit about when to use the skill.
• Put detailed behavior, examples, and domain rules in the body below the YAML.

That balance lets the agent discover and trigger the right skill without wasting context on details it doesn’t always need.

Step-by-step: build a simple “good morning” skill

Let’s walk through creating a basic skill that responds to “good morning” with a friendly, personalized message.

1. Create the folders

In your project (for example, in VS Code), create the following structure:

.github/
  skills/
    good morning/
      SKILL.md

The important parts are:

• A skills folder inside something like .github or your agent’s config directory.
• A folder for the skill itself, here called good morning.
• A file named SKILL.md inside that folder.

2. Add the YAML front matter

Open SKILL.md and add:

---
name: good morning
description: When the user says "good morning", respond with a cheerful, personalized greeting.
---

Make sure the name matches the folder name. Keep the description short, but clear enough that the agent knows when to use this skill.

3. Define the behavior

Below the YAML, write the instructions for how the agent should respond. For example:

When the user says "good morning":
- Greet them starting with "Hi <their name>" (use Debbie in this example)
- Ask if they have done any sport today
- Include a short, funny joke about sports

Example:
User: good morning
Assistant: Hi Debbie, have you done any sport today? Here's a funny joke about sports: Why did the soccer player bring string to the game? Because he wanted to tie the score.

You can customize this however you like—change the name, add more questions, adjust the tone, or include more examples.

4. Test the skill with your agent

Once the file is saved, open your AI agent (for example, Copilot, Claude Code, or another tool that supports skills) inside that project and simply type:

good morning

The agent should:

• Notice that there’s a skill related to “good morning”
• Read the SKILL.md file
• Respond following the instructions you wrote (personal greeting, sports question, and a joke)

Because skills are just files in your repo, you can often use the same skill across different tools that support project-based skills. That makes them a great building block if you’re also exploring more advanced AI-powered apps, like the ones described in this no-code AI resume app tutorial.

Scaling up: from toy skills to powerful workflows

The “good morning” skill is intentionally simple, but the same pattern scales to much more powerful use cases:

• Documentation generators that read your code and update READMEs
• Code review helpers that enforce your team’s best practices
• Project setup assistants that create files, diagrams, and templates

By combining SKILL.md with scripts, references, assets, and tests, you can turn a basic AI agent into a highly customized assistant that understands your domain and workflows.

Try it yourself

The fastest way to understand skills is to build one. Create a good morning skill in your own project, swap in your name, and add something personal to the response. Once you see the agent calling your custom behavior, you’ll start to see how far you can push this pattern.

From there, you can explore public skill directories like skills.sh, copy existing skill templates, or use generators that scaffold the folder structure for you. With just a markdown file and a few clear instructions, you can start shaping how your AI agent thinks and works—one skill at a time.