Agent Skills

Intent

Agent Skills is an open standard for extending AI agent capabilities with specialized knowledge and workflows.

Problem

Imagine your AGENTS.md file is overloaded with instructions for working on your project. There, you documented how to work with networking, what design pattern to use, how to compile your project, how to test, deploy, and so on. As a result, the context window is loaded with thousands of unnecessary tokens at the beginning of each session.

Solution

Agent Skills allow you to organize capabilities and knowledge that are loaded progressively as the task requires them.

• Do you need to deploy to production? Don't overload the context with instructions; create a Skill for that.
• Do you need instructions on how your architecture works? Create a Skill for it.
• Do you have a code template for specific patterns? A Skill could store them.

Real World Analogy

Imagine you hire an inexperienced construction worker who claims to be a fast learner and is open to any task, and you need him to lay the bricks in the bathroom. Would you ask him to read books about architecture, interior design, and the blueprints for the whole house? Of course not. Instead, you'd just instruct the new hire on how to lay the bricks in that specific spot. That's what an Agent Skill is: focused instructions.

Anatomy of an Agent Skill

You can save the Agent Skills at user level —available for all your sessions— or at your project level —available for everyone using the same project.

User level Skills

Project level Skills

Directory Structure

<skill-name>/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md Structure

---
name: skill-name
description: A description of what this skill does and when to use it.
---

# Title

Instructions

Use the directory name; dash-case is recommended.

Tips

• ✓Although the Skill is loaded only when needed, the metadata is always loaded at the beginning of every session, which is why short descriptions are recommended
• ✓Coding agents often create a script when performing a task; if the script can be reused, it is worth saving it in the proper Skill directory.

Example

In this example, we will see how to implement a Skill that follows the MVVM design pattern.

Directory

.agents/
└── skills/
    └── mvvm-pattern/
        ├── SKILL.md
        └── references/
            └── example.md

SKILL.md

---
name: mvvm-pattern
description: Implements features following the MVVM architecture pattern used in this project. Use when creating a new screen, adding a view model, or refactoring a view that mixes UI and business logic.
---

# MVVM Pattern

This project uses MVVM to keep views free of business logic. Follow these conventions when building or modifying a screen.

## Layers

- **Model**: Plain data types and domain logic. No UIKit/SwiftUI imports.
- **ViewModel**: Owns state and exposes it to the view. Handles formatting, validation, and calls to services. No view references.
- **View**: Renders state and forwards user intent to the ViewModel. No business logic.

## Rules

1. A ViewModel never imports `UIKit` or `SwiftUI`.
2. Expose state through `@Observable`.
3. Inject dependencies (services, repositories) through the initializer, never instantiate them inside the ViewModel.
4. Views observe the ViewModel; they do not own or mutate model state directly.
5. Side effects (network, persistence) live in services the ViewModel calls, not in the View.

## Steps to add a new screen

1. Create the folder `Features/<FeatureName>/`.
2. Add `<FeatureName>Model.swift`, `<FeatureName>ViewModel.swift`, and `<FeatureName>View.swift`.
3. Use the template in `assets/ViewModel.template.swift` as a starting point.
4. Register dependencies in the initializer.

See `references/example.md` for a complete worked example.

Pros and Cons

Relation with Other Context Providers

• Agents' docs follow a classical documentation structure that humans use, while Skills use a structure optimized for sharing the same skills between multiple AI tools.