Guide · Agent skill

How to use the SwiftUI View Refactor agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The swiftui-view-refactor skill gives an AI coding agent a fixed set of conventions for reviewing or refactoring SwiftUI views: consistent member ordering, smaller subviews, built-in state tools instead of view model classes, and correct use of Observation. It is written for iOS and macOS developers who want cleaner SwiftUI code without changing what the app does. After this guide you will know what the skill changes, how to install it, how to ask for it in plain language, and what to check before accepting its edits.

SwiftUI View Refactorsteipete/agent-scripts · MIT Download the skill

Quick start

1Download the ZIP. Download the swiftui-view-refactor ZIP from this page and unzip it. Confirm that SKILL.md is in the folder.
2Place the folder. Copy the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ inside a project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
3Open your SwiftUI project. Start your agent in the project that contains the SwiftUI views you want to review or edit.
4Make a specific request. Name the file or view and the goal, such as reordering members or splitting a long body, and say whether behavior must stay the same.
5Review the changes. Read the diff the agent produces, checking that layout and logic were not altered and that any view model was left as you intended.
6Build and test. Build the project in Xcode or your Swift toolchain and run your tests, since the skill does not do this for you.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions that an AI agent loads when a task matches it. This skill is defined in a SKILL.md file and a supporting reference file, references/mv-patterns.md.

When the skill is active, the agent follows these conventions while reviewing or refactoring SwiftUI code: it orders the parts of a view consistently, splits large view bodies into smaller subviews, favors @State and @Environment over adding view model classes, and checks that @Observable objects are stored correctly. The skill is guidance only. The files contain no scripts and make no network calls.

View ordering: Environment, let properties, @State and other stored properties, computed vars, init, body, view helpers, then helper and async functions.
MV (Model-View) first: views stay lightweight, and models or services own business logic.
Splitting: large bodies become subviews, passing small inputs instead of the whole parent state.
Observation: @Observable reference types are stored as @State in the root view, and optional state is avoided unless required.
Behavior first: the skill says not to change layout or business logic unless you ask.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. You can install the skill for yourself across all projects, or for one project only.

For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Check that the unzipped folder contains SKILL.md. The skill is not active if that file is missing from the folder.

Personal: ~/.claude/skills/swiftui-view-refactor/
Project only: .claude/skills/swiftui-view-refactor/ inside your project
Claude apps: Settings → Capabilities → Skills, then upload

~/.claude/skills/swiftui-view-refactor/

Trigger the skill with natural requests

You do not need a special command. Ask for SwiftUI review or refactoring work in plain language, and mention the file or view. The skill's description covers view refactor and review work involving layout, dependency injection, Observation, and view models, so requests about those topics are the ones it is meant for.

Good requests name the goal and the constraint, for example that behavior must stay the same. Be explicit if you want the agent to leave an existing view model alone.

Refactor ContentView.swift so the body is shorter and split into subviews. Keep behavior the same.
Review this SwiftUI file for Observation misuse, such as unnecessary optional @State.
Reorder the members of ProfileView to match the standard SwiftUI ordering.
Tidy this view, but keep the existing MVVM view model as it is.

Example: what a split looks like

The skill's main pattern is to move sections of a long body into named subviews. In the example below, the body only lists the sections, and each section's details live in its own part of the file or in a separate View type.

Review every change the agent makes. Splitting a view is safe only when the same data and actions reach the same places on screen.

var body: some View {
    VStack(alignment: .leading, spacing: 16) {
        HeaderSection(title: title, isPinned: isPinned)
        DetailsSection(details: details)
        ActionsSection(onSave: onSave, onCancel: onCancel)
    }
}

Know what the skill needs and its safety limits

The skill needs a SwiftUI codebase to review or edit. Xcode or another Swift toolchain is needed to build and test the changes, but the skill itself does not use it. The skill runs no scripts and uses no network.

Because the skill is only text instructions, the main risk is a bad edit, not a hidden action. Build the project and run your tests after the agent finishes.

Requires: a SwiftUI codebase
Runs scripts: no
Uses network: no
Build and test: use Xcode or your Swift toolchain yourself

Tips for good results

Work in a git branch or commit before a refactor, so you can compare and revert the agent's changes. Ask for one view or one file at a time rather than the whole app.

If your project uses MVVM on purpose, say so before you start. The skill tells the agent to avoid introducing view models, which can conflict with an existing architecture.

Commit or branch first so changes are easy to review.
Scope each request to one view or file.
State up front if you rely on view models.
Check the output with a build and your existing tests.

What people use it for

Reordering the members of a long SwiftUI view to the standard top-to-bottom order.
Splitting a large body into named header, filter, results and footer sections.
Reviewing an @Observable store for optional @State that is not needed.
Replacing an optional view model with a non-optional @State view model created in init, in a codebase that already uses one.
Converting repeated computed view code into a small standalone View type when it is reused.

Frequently asked questions

How do I install the swiftui-view-refactor skill?

Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does this skill require anything to run?

It needs a SwiftUI codebase to work on. Xcode or another Swift toolchain is useful for building and testing the changes, but the skill itself does not need them. It runs no scripts and makes no network calls.

Is the swiftui-view-refactor skill free?

The skill is released under the MIT licence, as listed on this page. Check the licence file in the repository for the full terms.

Will this skill change how my app behaves?

The skill instructs the agent to keep behavior intact and not to change layout or business logic unless you ask. You should still build and test the result, because any edit can introduce a bug.

Can I use this skill if my project uses MVVM?

Only with care. The skill tells the agent not to introduce view models and to prefer MV patterns, which may conflict with an MVVM architecture. If you have view models, state that in your request so the agent keeps them, or choose a different tool.

What is the difference between this and general SwiftUI advice?

This skill is a fixed set of rules: member ordering, MV-first structure, subview splitting and Observation checks. A general assistant may suggest any structure, while this skill steers the agent toward one consistent style. It does not cover UIKit, AppKit or web code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are an iOS or macOS developer, or a team, that wants SwiftUI views tidied into a consistent MV-style structure and checked for Observation misuse, with behavior left unchanged. Pick something else if your project relies on MVVM view models you want to keep, or if your code is UIKit, AppKit or web.

Download the skill