In September I wrote about the agent skills Apple included in Xcode 27. I’ve used them every day since, and I also spent a full session reviewing what else exists in the ecosystem: community repositories, skills from other vendors, MCP servers. I read each one, reviewed its scripts, and kept a small set.
This three-part series comes out of that work:
- Part 0 (this one): what agent skills are and why they matter.
- Part 1 (tomorrow): the essential set, what I have installed globally and why.
- Part 2 (the day after): specialized skills, what to install depending on the kind of app.
If you already use skills daily, you can jump straight to part 1. If the term sounds familiar but you’ve never installed one, start here.
The problem they solve
A language model learns what exists up to its training cutoff. Apple’s SDK changes every June. You feel that gap all the time: the agent suggests ObservableObject when your project already uses @Observable, writes XCTest tests after you moved to Swift Testing, or doesn’t know that in iOS 27 @State became a macro, which is why compile errors suddenly show up where there were none before.
Until recently there were two ways to correct that:
- Explain it in every conversation. It works, but you repeat yourself over and over.
- Write it down in a rules file (
CLAUDE.md, Cursor rules, or the equivalent). That works better, but the file is loaded in full in every session, whether you need it or not. Put everything you know about SwiftUI, Swift Testing, concurrency, and StoreKit in there and you end up paying thousands of context tokens to fix a typo.
An agent skill is the third option: packaged knowledge the agent only loads when it needs it.
What a skill actually is
A skill is a folder. At minimum it contains a SKILL.md file. This is the real opening of one of Apple’s skills:
---
name: modernize-tests
description: "Modernize test suites to use modern Swift Testing features or migrate from XCTest."
---
# Modernize Tests
Test modernization refers to two potential actions: migrating from XCTest
to Swift Testing, and updating existing Swift Testing tests to use
recommended patterns.
...It has two parts:
- The header (frontmatter): a name and a one- or two-line description.
- The body: the full instructions, with examples, edge cases, and what not to do. It can run to hundreds of lines.
Optionally, the folder includes extra reference files or scripts the agent can run. For example, Apple’s skill for auditing an Xcode project’s security settings ships with a script that filters the build settings output.
How the agent uses it without burning context
This is the idea that makes the whole thing work:
- When a session starts, the agent reads only the descriptions of every installed skill. Each one costs roughly 40 to 230 tokens.
- When you ask for something, the agent compares your request with those descriptions.
- If one matches, it loads that skill’s full body and follows its instructions.
In my setup I have nine global skills, and together their fixed cost is about 670 tokens per session. In exchange, when I migrate a test or fix a data race, the agent works from instructions hundreds of lines long that I would otherwise have had to explain myself.
Some skills spell out exactly when they should kick in. Apple’s device-interaction skill, which verifies the app in the simulator, opens like this:
TRIGGER when: user asks to verify/test/check if the app works on device,
after implementing a UI-affecting feature that needs device verification...
DO NOT TRIGGER when: user asks about unit tests only, build-only requests
without device testing...That precision is the difference between a useful skill and one that fires when it shouldn’t.
Skills versus rules
Both live side by side, and it helps to know what goes where:
Rules file (CLAUDE.md and similar) | Agent skill | |
|---|---|---|
| When it loads | Always, in full | The description always; the body only when relevant |
| What it’s for | Conventions of your project: branches, structure, what not to touch | Knowledge about a topic: SwiftUI, Swift Testing, StoreKit |
| Who writes it | You | You, the community, or the vendor |
| Where it lives | In the repo | Global (all your sessions) or inside one project |
My rule of thumb: if something is true only in this project, it goes in the rules file. If it’s true in any project that uses that technology, it’s material for a skill.
Where they work today
The format started in Claude Code, which looks for skills in two places:
~/.claude/skills/: global skills, available in all your sessions.<your-repo>/.claude/skills/: project skills, which only cost context while you work in that repo.
Because the format is just a folder of Markdown, other agents picked it up. As I covered in the September post, Codex and Cursor read skills from ~/.agents/skills/, and Xcode 27 exports its own to whatever folder you choose. This series is written from my workflow, which is Claude Code, but what I say about which skills are worth it applies just as well if you use another agent that supports them.
Why it matters that Apple publishes its own
Until this year, skills for Apple development came from the community. There’s excellent work there, and I cover several in part 1. But with Xcode 27 something different happened: Apple published ten official skills, written by the team that designs the APIs. You export them like this:
xcrun agent skills export ~/path/of/your/choiceThat changes three things:
The source. When a community skill tells you how to structure data flow in SwiftUI, it’s the informed opinion of someone experienced. When Apple’s skill says it, it’s how Apple expects you to use its framework. The idea is for the agent to lean on that source instead of what it remembers from training.
The speed. Apple’s skills ship with each Xcode release. swiftui-whats-new-27 exists because iOS 27 brought changes no model could have known about in advance. Instead of waiting for the model to be retrained, the knowledge arrives with the tool.
The legitimacy. Apple adopting the format tells the rest of the ecosystem that agent skills are now a normal part of the workflow.
What a skill doesn’t do
To set expectations:
- It doesn’t give the agent new capabilities. It gives it context. A StoreKit skill doesn’t let the agent buy anything; it makes it write better StoreKit code.
- It doesn’t replace documentation. It complements it. To understand an API in depth, Apple’s documentation is still the reference.
- It doesn’t guarantee correct code. It cuts down on “that’s not how it’s done anymore” mistakes, but the code still gets reviewed and tested like always.
- Installing everything isn’t free. Every global skill adds its description to all your sessions, and two skills covering the same topic compete with each other. More skills doesn’t mean better results.
Before installing any skill
A skill can include scripts the agent runs on your machine. That’s why I treat every third-party skill the way I’d treat a new dependency:
- I read the full
SKILL.mdand any scripts it ships with. - I copy only the skill’s folder, not the whole repository or its bundled plugins.
- I pin the version (the commit I reviewed) and note where it came from.
Apple’s skills come inside Xcode, so the risk is different, but the “install only what I use” rule still applies. Of the ten, I have three installed globally, I install four more per project when I need them, and I don’t use the remaining three because they don’t fit what I build.
Which ones they are, why those, and how to install them is exactly what part 1 covers.