Greetings, traveler!

AI coding agents are no longer just autocomplete with a chat box. Tools like Codex and Claude Code can read a repository, edit files, run commands, inspect failures, and continue working across multiple steps.

That sounds useful until the agent starts making the same wrong assumption for the fifth time.

In an iOS project, those assumptions are rarely small. The agent may choose the wrong architecture layer, create a new networking client instead of using the existing one, ignore Swift concurrency rules, skip snapshot tests, or generate SwiftUI code that does not match the design system.

This is where agent instructions come in. They give the agent a project map before it starts touching files. Not the whole map. Just the parts that usually matter: how to build the app, where modules live, what patterns are allowed, what patterns are banned, and which checks must pass before a change is considered done.

There are several ways to provide this context. The names differ by tool, but the idea is similar:

AGENTS.md gives coding agents repository-level instructions.

CLAUDE.md gives Claude Code persistent project context and rules.

AI agent skills package reusable workflows into small, loadable units.

They overlap a little, but they are not the same thing.

What is AGENTS.md

AGENTS.md is a markdown file for coding agents. Think of it as a README written for an AI agent instead of a human contributor.

A normal README usually explains what the project is, how to run it, and why it exists. AGENTS.md can be more direct and more operational. It can tell the agent which commands to run, which folders to inspect first, which style rules matter, and which mistakes are expensive in this repository.

For example, an iOS project might include:

# AGENTS.md

## project overview

This is a modular iOS app written in Swift and SwiftUI.

Use existing modules before creating new ones:
- AppCore for shared domain models
- Networking for API clients
- DesignSystem for UI components
- Feature modules for screens and business logic

## build and test

Before finishing a code change, run:

```sh
xcodebuild test \
  -scheme LivsyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16'

For SwiftFormat:

swiftformat .

Architecture rules

• Do not put networking code inside SwiftUI views.
• Do not create global singletons for new features.
• Prefer async/await for new asynchronous code.
• Keep UIKit wrappers isolated in the UIAdapters module.
• Do not introduce Combine in new code unless the surrounding module already uses it.

SwiftUI rules

• Keep view state local when possible.
• Avoid AnyView unless type erasure is genuinely needed.
• Use stable identifiers in ForEach and List.
• Do not perform heavy work inside body.

Codex reads AGENTS.md before doing work. It can load global guidance from the Codex home directory and project guidance from the repository. It also supports nested instruction files, so a rule placed closer to the current working directory can override broader guidance.

That matters in large iOS apps. The root AGENTS.md can define general rules, while a feature directory can add local instructions:

AGENTS.md
Features/
  Payments/
    AGENTS.md
  Profile/
    AGENTS.md

The Payments file can say that payment flows must keep audit logging intact. The Profile file can describe a different testing strategy. The agent does not need every detail for every task. It needs the right detail at the right level.

What is CLAUDE.md

CLAUDE.md is Claude Code’s project instruction file. It works as persistent context that Claude reads at the start of a session.

The content usually looks similar to AGENTS.md: architecture notes, commands, conventions, testing rules, and common traps. The main difference is ecosystem behavior. CLAUDE.md is Claude Code specific, while AGENTS.md is intended as a broader convention for coding agents.

A useful CLAUDE.md for an iOS project might look like this:

# CLAUDE.md

## project context

This app uses Swift 6, SwiftUI, async/await, and a modular architecture.

Main layers:
- UI: SwiftUI views and view models
- Domain: use cases and entities
- Data: repositories, API clients, persistence
- DesignSystem: shared UI components and tokens

## rules

- Do not add dependencies without asking.
- Prefer existing DesignSystem components over custom controls.
- Keep feature logic out of SwiftUI views.
- Do not use Task.detached for ordinary background work.
- Use MainActor only when UI state is involved.

## commands

Run unit tests:

```sh
xcodebuild test \
  -scheme LivsyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16'

Run formatting:

swiftformat .

Common mistakes

• Some generated API models are overwritten by codegen. Do not edit them manually.
• Snapshot tests are stored next to the feature module.
• The app has several old Combine modules. Do not migrate them unless the task asks for it.

Claude Code also has auto memory. CLAUDE.md is written by the developer or the team. Auto memory is written by Claude based on corrections and patterns it learns during work. Claude treats these as context, not as hard enforcement. If a rule must always run, a hook or CI check is a better fit. That distinction is important. A markdown instruction can say “run tests before finishing.” A CI job can prove whether tests passed.

What are AI agent skills

An AI agent skill is a reusable workflow packaged as a small directory. The required file is usually SKILL.md. Supporting files can include scripts, examples, templates, references, or assets.

Skills are useful when an instruction has grown too large or too procedural for AGENTS.md or CLAUDE.md.

For example, this does not belong in the root instruction file:

“To review SwiftUI performance, inspect body invalidation, identity stability, state ownership, list reuse, image decoding, layout feedback, animation scope, and async lifecycle work. Then produce findings grouped by severity with exact file references and suggested fixes.”

That is a workflow. It has steps. It may need examples. It may need references. It may evolve over time.

A skill is a better home for it:

.agents/
  skills/
    swiftui-performance/
      SKILL.md
      references/
        state-invalidation.md
        lists-and-scrolling.md
        layout-drawing-animation.md

Or in Claude Code:

.claude/
  skills/
    swiftui-performance/
      SKILL.md
      references/
        state-invalidation.md
        lists-and-scrolling.md

A minimal SKILL.md might look like this:

---
name: swiftui-performance
description: Use this skill when reviewing or fixing SwiftUI performance issues, including broad state invalidation, unstable identity, heavy rows, scrolling hitches, layout cost, drawing cost, and async lifecycle work.
---

# SwiftUI performance review

Use this workflow for SwiftUI performance work.

## review order

1. Identify the screen or component under review.
2. Find the state that can invalidate the view.
3. Check whether identity is stable in lists and conditional branches.
4. Look for expensive work inside body, computed properties, and row views.
5. Check image loading, decoding, caching, and resizing.
6. Check layout feedback through GeometryReader and PreferenceKey.
7. Review async work in task, onAppear, refreshable, and view models.

## output

Return:
- suspected issue
- why it matters
- file and symbol
- suggested fix
- test or profiling step

Codex uses progressive loading for skills. It starts with the skill name, description, and file path. It loads the full SKILL.md only when the task matches the skill or the user invokes it directly. Claude Code has a similar idea: skills can be invoked directly, and the body loads when the skill is used.

This is the main reason skills scale better than one huge instruction file. The agent does not need a full SwiftUI performance handbook for a small copy change. But when the task is “review this screen for scrolling hitches,” it should load the detailed workflow.

AGENTS.md vs CLAUDE.md vs skills

These files solve different context problems.

tool	best for	scope	who writes it	when it loads
AGENTS.md	Repository instructions for coding agents	Global, repository, directory	Developer or team	Before the agent starts work
CLAUDE.md	Claude Code project memory and rules	User, project, organization	Developer or team	At the start of a Claude Code session
Skill / SKILL.md	Reusable workflow or domain procedure	User, project, plugin	Developer, team, or skill author	When invoked or selected as relevant
Auto memory	Learned project notes and corrections	Usually local to a repository	Claude	At session start, with limits

A practical rule:

• Use AGENTS.md or CLAUDE.md for rules the agent should know every time.
• Use a skill for a repeatable workflow.
• Use hooks, scripts, and CI for rules that must be enforced.

For example:

“Use SwiftFormat” belongs in AGENTS.md or CLAUDE.md.

“Run SwiftFormat automatically after edits” belongs in a hook.

“Perform a full SwiftUI performance review” belongs in a skill.

“Never commit secrets” belongs in instructions, but also in tooling. The markdown file can remind the agent. The scanner should enforce it.

How to create good agent instructions

Good agent instructions are boring in the best way. They are specific, short, and easy to verify.

Bad instruction:

Follow our architecture and write clean code.

Better instruction:

Do not call API clients from SwiftUI views. Add networking work to a repository in the Data layer, then call it from a use case.

Bad instruction:

Make sure everything is tested.

Better instruction:

For view model changes, add or update tests in the matching FeatureNameTests target. Run the feature test target before finishing.

Bad instruction:

Use the design system.

Better instruction:

Use PrimaryButton, SecondaryButton, AppTextField, and AppListRow from DesignSystem. Do not create local button styles unless the task explicitly asks for a new component.

The best instructions usually come from repeated review comments. If a reviewer has written the same note twice, it probably belongs in AGENTS.md, CLAUDE.md, or a skill.

For iOS teams, useful sections often include:

## build commands

## test commands

## module map

## architecture rules

## Swift concurrency rules

## SwiftUI rules

## generated files

## dependencies

## pull request expectations

Keep the file small. A 500-line instruction file looks comprehensive, but agents are still working within a context window. Long files also become stale. A short file with sharp rules beats a giant internal wiki pasted into markdown.

How to use them in daily iOS work

Agent files work best when they are part of normal development, not a side experiment.

Before asking the agent to implement a feature, the repository should already explain the basics:

• Where feature modules live
• How navigation is wired
• Which dependency injection pattern is used
• Which generated files must not be edited
• Which tests should run for the changed area

Then the prompt can stay focused:

Implement empty state support for the Transactions screen.
Follow repository instructions.
Reuse DesignSystem components.
Add view model tests for loading, empty, error, and success states.

For a review task, invoke a skill directly:

Use the swiftui-performance skill to review TransactionListView.
Focus on scrolling hitches and unnecessary invalidation.

For Claude Code:

/swiftui-performance Review TransactionListView for unnecessary body invalidation.

For Codex, the skill can be selected implicitly if its description matches the task, or invoked explicitly depending on the surface.

The workflow becomes much cleaner. AGENTS.md or CLAUDE.md gives the baseline. The skill gives the procedure. The prompt gives the current task.

A useful setup for an iOS repository

A simple setup can look like this:

AGENTS.md
.claude/
  CLAUDE.md
  skills/
    swiftui-performance/
      SKILL.md
    concurrency-review/
      SKILL.md
    feature-implementation/
      SKILL.md
Features/
  Payments/
    AGENTS.md
DesignSystem/
  AGENTS.md

The root AGENTS.md defines shared repository rules. CLAUDE.md gives Claude Code the same core context, possibly with Claude-specific notes. The skills directory stores workflows that should not load on every task.

The DesignSystem AGENTS.md can add local rules:

# DesignSystem/AGENTS.md

- Do not introduce feature-specific names in this module.
- Components must support Dynamic Type.
- New colors must use existing token naming.
- Add a preview for each new public component.

The Payments AGENTS.md can add stricter rules:

# Features/Payments/AGENTS.md

- Do not change payment confirmation behavior without tests.
- Keep analytics events stable unless the task explicitly asks to rename them.
- Use PaymentAuditLogger when confirmation state changes.

This structure lets agents behave differently in different parts of the same codebase without forcing every rule into one huge file.

Common mistakes

The first mistake is writing instructions that sound like advice instead of rules.

“Be careful with concurrency” is weak. “Do not mutate ObservableObject state outside MainActor” is usable.

The second mistake is putting every workflow into AGENTS.md or CLAUDE.md. A root instruction file should not contain a full release checklist, performance guide, localization guide, and debugging handbook. That belongs in skills or normal documentation.

The third mistake is trusting markdown too much. Agents can miss instructions. They can misunderstand them. They can also follow an instruction and still write bad code. Use tests, linters, formatters, hooks, and CI for anything that must be guaranteed.

The fourth mistake is never updating the files. Agent instructions should change after real failures. If the agent edits generated files, add a rule. If it keeps adding local UI components instead of using the design system, add a rule. If it reads the wrong module first, add routing guidance.

Treat the files as part of the codebase.

Where this helps iOS teams most

This setup is especially useful in iOS projects because many rules are local and architectural.

SwiftUI code has performance traps that are hard to catch from syntax alone. Swift concurrency has rules that depend on isolation and ownership. Modular apps have boundaries that are obvious to the team but invisible to a fresh agent session. Generated API models, design tokens, localization files, and project.yml files all need careful handling.

Agent instructions reduce the amount of context that has to be repeated in every prompt.

They also make agent output easier to review. When the repository says “do not put networking in views,” the reviewer can reject a bad change without re-explaining the architecture. When the SwiftUI performance skill defines the review format, every performance review comes back in a shape the team can compare.

That does not make the agent senior. It makes the agent less random.

Final thoughts

AGENTS.md, CLAUDE.md, and skills are small files, but they change the way coding agents enter a project.

AGENTS.md is the shared instruction layer for coding agents.

CLAUDE.md is Claude Code’s persistent project context.

Skills are reusable workflows that load only when the task needs them.

For an iOS team, the best starting point is simple: add build commands, test commands, module boundaries, architecture rules, generated file warnings, and a few SwiftUI or concurrency rules. Then add skills only when a repeated workflow becomes too large for the root file.

The goal is to stop repeating the same corrections in chat and code review.