Skills for Domain-Specific Knowledge

One thing that bothers me sometimes with coding agents is that they don’t know about iOS 26, or they “forget” about my custom Tailwind palette. And those are because of two different problems:

• First, cutoff dates: the models are trained up until one date, and if whatever you’re working on was released after, well, you’re out of luck.
• Second, project-specific knowledge: they haven’t read the Tailwind CSS files that define that palette.

They could try to figure it out by looking at the code, but that would mean going through your files, searching and reading a lot of files to find how the palette is used.¹

We could solve this with AGENTS.md. But as we’ve seen before, this would cost tokens and degrade the focus of the agent. Furthermore, not everything applies to every task. iOS 26 and its updates don’t matter when I’m working on a backend API. Knowing about the Tailwind palette doesn’t matter when I’m working on database migrations. What we need is context that loads only when it’s relevant to the task at hand.

Introducing Skills

Thankfully, there’s a solution called Skills. They recently became an open standard. They were first created by the Anthropic team for Claude, and now they’ve been adopted by most of the coding tools.²

In a few words, what they are: a directory that contains a SKILL.md file and maybe some other optional directories for scripts, reference, and assets. The SKILL.md is pretty simple. It has a frontmatter with the name of the skill and a short description of when the skill needs to be loaded. Then in the body you have the actual instructions about whatever the skill does. Those instructions can reference documentation or scripts that are shipped with the skill.

Once you have configured skills for your agent, the skill names and their descriptions are included in the system prompt, usually alongside your AGENTS.md file. Then, whenever the agent has to do a task that is relevant to a skill, it will load the full content. If the skill has scripts, it will use them. If the skill has documentation, it will read the relevant parts.

In my case, I have an iOS 26 skill that lists out the updates introduced by the new version. It explains what Liquid Glass is. It covers the UX updates, like tab bars that minimize on scroll. And it adds references to the official documentation from Apple.

Example: iOS 26 Skill

As mentioned before, the problem is that the model knows about iOS 17 and 18, the latest versions when it was trained, but not about iOS 26 that came out after. iOS 26 introduced a bunch of new features and UX changes: Liquid Glass, tab bar minimization, navigation subtitles, glass effects. It also brought improvements to Swift 6.2.

Here’s what I have in the frontmatter:

name: ios-26
description: >-
  iOS 26 / iPadOS 26 development with Xcode 26 and Swift 6.2.
  Use when building iOS apps targeting iOS 26. Covers Liquid Glass design system,
  SwiftUI APIs, navigation patterns, tab bars, search, and Swift 6.2 language features.

A simple name and an accurate description for the agent to figure out when to use it.

And here’s what the content looks like:

# iOS 26 Development

iOS 26 was released September 2025. Apple unified all platform version
numbers to "26" (iOS, iPadOS, macOS, watchOS, tvOS, visionOS) for the
2025-2026 release cycle. Future versions: iOS 27, iOS 28, etc.

## Liquid Glass Design System

Liquid Glass is a translucent material that reflects and refracts
surroundings. Core principle: **content first**. Standard SwiftUI
components automatically adopt Liquid Glass materials.

...

The content covers what changed. It goes into details, has examples, and links to Apple’s documentation.

I could vendor the documentation into a references directory. But to future-proof this skill, I chose to link instead. Since my agents can fetch content online, this works fine.

See the difference: without the skill vs with the skill.

Example: Tailwind v4 + Project Design

Another example: Tailwind v4 and project-specific design.

Sometimes agents forget about the newest version of Tailwind, even though it’s within their training cutoff. They might have been trained with more content from v3. So the skill starts by explaining the v4 changes: parentheses for CSS vars, renamed utilities. It also documents the custom color palette and links to the CSS file where it’s defined. And it lists the custom utility classes.

Here’s the frontmatter:

name: frontend-design
description: >-
  Tailwind CSS v4 syntax and project design system.
  Use when writing frontend styles.
  Covers v4 syntax changes, custom color palette, and utility classes.

And here’s part of the content:

# Frontend Design

This project uses Tailwind CSS v4 with a custom color palette.

## Tailwind v4 Syntax

### CSS Variables

Use parentheses, not square brackets:

<!-- WRONG: v3 syntax -->
<div class="bg-[--background]"></div>

<!-- CORRECT: v4 syntax -->
<div class="bg-(--background)"></div>

## Color Palette

Defined in `src/styles/global.css`.

### Semantic Colors

Use these instead of raw values:

| Class            | Light          | Dark           |
|------------------|----------------|----------------|
| `bg-background`  | Volcanic Pearl | Zinc 900       |
| `text-foreground`| Zinc 900       | Volcanic Pearl |

...

The skill doesn’t vendor the palette and utilities. Those files are used in the project, so the skill links to them instead. The skill explains conventions and how to work with the palette. The project files are the source of truth. If you vendored them, they could get out of sync, and the agent would make mistakes based on stale information.

Unlike the iOS 26 skill, which works for any iOS 26 project, this one is project-specific. It’s not something you’d want available to all your agents system-wide. It lives inside the project repo. Depending on your tool, this goes in different locations. For Claude:

.claude/skills/
└── frontend-design/
    └── SKILL.md

When to Use Skills vs AGENTS.md

When do you decide to use a skill versus putting something in AGENTS.md? Here’s the rule of thumb: if it only matters for certain tasks, it should be a skill. If it’s something that’s true most of the time, it should be in AGENTS.md.

What Comes Next

Now you know about skills and how to make your agent aware of specific domain knowledge. But how do you make sure it actually applies what you say? In the previous post, we talked about removing style guidelines from AGENTS.md. And skills don’t cover all those guidelines either: they just make the agent more up to date with whatever tools it’s using.

So how do we make sure the agent stays on track? This is where infrastructure comes in. You set up linting, testing, and short feedback loops. That’s what we’ll cover next.