SwiftUI Agent Skills 가이드

하나만 선택한다면: Apple이 작성한 지침과 더 적은 API 환각이 중요할 때는 ameyalambat128/swiftui-skills를, 광범위한 iOS 엔지니어링 지원과 정확한 프레임워크 라우팅이 필요할 때는 dpearson2699/swift-ios-skills를 선택하세요. 가장 강력한 조합: 첫 번째를 사실 기준 레이어로 사용하고 두 번째에서는 프로젝트에 필요한 전문 Skill 5~10개만 설치하세요.

AI가 생성한 SwiftUI에서 가장 흔한 문제는 잘못된 문법이 아니라 겉으로만 올바르게 보이는 코드입니다. 상태 소유권이 불분명하거나, 오래된 탐색 패턴을 쓰거나, 동시성 경계가 모호하거나, 존재하지 않는 API를 사용하기도 합니다. Agent Skills는 범용 모델을 명시적인 Apple 플랫폼 엔지니어링 제약을 따르는 협업자로 바꿔 줍니다.

Agent Skill이란 정확히 무엇인가요?

Skill은 일반적으로 SKILL.md 파일이 들어 있는 디렉터리입니다. Codex, Claude Code, Cursor 같은 코딩 에이전트에 기능을 활성화할 시점, 먼저 읽을 참고 자료, 따라야 할 규칙과 결과 형식을 알려줍니다. Xcode 확장 프로그램도 Swift package도 아닙니다. AI를 위한 팀 엔지니어링 핸드북과 집중형 지식 모음을 합친 것으로 생각하면 됩니다.

모든 규칙을 하나의 거대한 프롬프트에 담는 대신, Skill은 관련 작업에서만 로드될 수 있습니다. SwiftUI 애니메이션 작업에는 애니메이션 지침이, 상거래 작업에는 StoreKit 구매 및 검증 규칙이, 스크롤 문제를 디버깅할 때는 성능 지침이 로드됩니다. 이렇게 작업에 맞춘 컨텍스트는 보통 더 정확하고 토큰 효율도 높습니다.

한눈에 보는 두 가지 접근 방식

접근 방식 1: Xcode 문서를 AI의 사실 기준으로 만들기

가장 가치 있는 설계 선택은 모든 사실과 API를 로컬 /docs에 근거하도록 하는 명시적인 규칙입니다. 에이전트는 코딩 전에 문서를 선택하고 검토 과정에서 사용한 파일을 인용합니다. 형식이나 API가 없다면 그럴듯한 이름을 만들어 내지 않고 불확실성을 밝혀야 합니다.

추출되는 자료는 SwiftUI 레이아웃에 그치지 않습니다. App Intents, AlarmKit, StoreKit, WebKit, SwiftData 상속, Swift Concurrency, Liquid Glass, visionOS 위젯과 InlineArray, Span 같은 저수준 성능 기능도 포함합니다.

알아두어야 할 제한 사항

• macOS와 Xcode 26 이상이 필요합니다. 문서 디렉터리가 채워지기 전에는 Skill이 SwiftUI 지침을 제공해서는 안 됩니다.
• 진입점의 범위가 넓습니다. 복잡한 프로젝트에서는 여전히 “Apple 문서에 따라 상태 소유권과 탐색을 검토해 줘”처럼 초점을 맞춘 요청이 필요합니다.
• 로컬 Xcode 버전이 참고 자료의 버전을 결정하므로, 서로 다른 사용 가능 여부 결론이 나오지 않도록 팀의 도구 체인을 맞춰야 합니다.

접근 방식 2: 조합할 수 있는 iOS Skill 84개

이 저장소의 강점은 정확한 라우팅입니다. 모든 컨텍스트에 Apple 개발 지식 전체를 넣을 필요가 없습니다. SwiftData, StoreKit 2, App Intents와 WidgetKit을 사용하는 구독 앱이라면 해당 Skill에 SwiftUI 패턴, Swift Concurrency, 테스트와 손쉬운 사용 Skill을 함께 설치할 수 있습니다.

아래는 이 글의 업데이트 시점을 기준으로 한 전체 84개 Skill 목록입니다. 각 그룹을 펼쳐 프로젝트 기술 스택을 지원하는지 확인해 보세요.

선택 방법: 수가 아니라 작업에서 시작하세요

시나리오 A: SwiftUI에 AI를 처음 사용하기

Apple 문서 제약을 적용하려면 먼저 swiftui-skills를 설치하세요. 그런 다음 84개 Skill 모음에서 swiftui-patterns, swiftui-navigation, swift-concurrency, swift-testing과 ios-accessibility를 추가하세요. 이 다섯 개는 새 프로젝트에서 가장 흔한 실패 지점을 다룹니다.

시나리오 B: 기존 제품에 기능 만들기

언젠가 유용할지 모르는 기술이 아니라 현재 기술을 기준으로 선택하세요. 구독에는 storekit을, 시스템 화면에는 app-intents와 widgetkit을, 데이터 중심 앱에는 swiftdata 또는 core-data를, 온디바이스 AI 제품에는 apple-on-device-ai를 추가하세요.

시나리오 C: 코드 검토와 안정성 작업

swiftui-performance, debugging-instruments, metrickit, swift-security, ios-accessibility와 app-store-review를 우선하세요. 이 조합은 코드 생성기보다 출시 전 품질을 지키는 역할에 가깝습니다.

설치: 범용 에이전트와 Codex

로컬 Apple 문서 Skill 설치하기

# 직접 설치하고 Xcode에서 문서 추출
curl -fsSL https://swiftui-skills.ameyalambat.com/install | bash

# 또는 skills CLI 사용
npx skills add ameyalambat128/swiftui-skills

원격 스크립트를 셸로 전달하기 전에 저장소의 설치 프로그램을 검토하세요. 설치한 뒤에는 설치된 Skill 디렉터리에서 setup.sh를 실행하고 에이전트 세션을 다시 시작하여 새 Skill을 검색할 수 있게 하세요.

84개 Skill 모음에서 대화식으로 선택하기

# 대화식 선택기를 열고 Skill과 대상 에이전트 선택
npx skills add dpearson2699/swift-ios-skills

# 선택한 기능만 설치
npx skills add dpearson2699/swift-ios-skills \
  --skill swiftui-patterns \
  --skill swift-concurrency \
  --skill swift-testing

# 확인 및 업데이트
npx skills check
npx skills update

Codex에 Skill 하나 설치하기

$skill-installer install \
  https://github.com/dpearson2699/swift-ios-skills/tree/main/skills/swiftui-patterns

마지막 디렉터리를 카탈로그에 있는 Skill 이름으로 바꾸세요. 프로젝트별 규칙은 프로젝트 범위에, 재사용할 수 있는 SwiftUI와 엔지니어링 지침은 개인 공유 범위에 두는 것이 좋습니다.

더 안정적인 통합 워크플로

1. 목표와 배포 대상을 밝히세요. 작업이 기능 개발, 리팩터링 또는 검토인지 에이전트에 알리고, 새 API를 조건 없이 사용하지 않도록 최소 iOS 버전을 지정하세요.
2. 사실 기준 레이어가 문서를 먼저 선택하게 하세요. swiftui-skills에 작업에서 사용한 Apple 문서와 사용 가능 여부 제약을 나열하도록 요청하세요.
3. 작업별 Skill만 로드하세요. 전체 카탈로그를 하나의 작업에 추가하는 대신 탐색에는 swiftui-navigation을, 구매에는 storekit을 사용하세요.
4. 완전한 검증을 요구하세요. 에이전트에 대상을 빌드하고 테스트를 실행하며, UI 변경 사항에서는 Dynamic Type, VoiceOver와 다크 모드를 확인하도록 요청하세요.
5. 결정을 프로젝트 규칙에 기록하세요. 반복되는 아키텍처 결정은 작업마다 다시 협의하지 말고 프로젝트 Skill 또는 AGENTS.md에 두어야 합니다.

재사용 가능한 작업 프롬프트는 다음과 같이 시작할 수 있습니다.

Use local Apple documentation as the API source of truth,
and use swiftui-patterns, swift-concurrency, and swift-testing.
Goal: implement a testable asynchronous loading screen for an iOS 26 app.
List the selected documentation and state ownership first, then modify the code, build, and run tests.
Do not introduce an architecture that the project does not already use.

버전과 라이선스: 마지막으로 확인할 두 가지

Apple 플랫폼 API는 빠르게 변합니다. 이 글은 2026년 7월 6일의 swiftui-skills 커밋과 2026년 7월 4일의 swift-ios-skills 커밋을 기준으로 확인했습니다. 저장소 콘텐츠, 지원 버전과 Skill 수는 달라질 수 있습니다. 베타 프레임워크는 항상 현재 Xcode SDK를 기준으로 확인하세요.

라이선스도 다릅니다. swiftui-skills는 MIT를, swift-ios-skills는 PolyForm Perimeter 1.0.0을 사용합니다. 앱 개발과 비공개 소스 상용 워크플로는 허용하지만, 콘텐츠를 경쟁 제품으로 다시 패키징하는 행위는 제한합니다. 팀 배포, 수정 또는 상용 통합 전에 원본 LICENSE를 읽어 보세요.

자주 묻는 질문

SwiftUI Agent Skills가 공식 Apple 문서를 대체하나요?

아니요. Skill은 에이전트가 적절한 시점에 규칙을 로드하고 적용하도록 돕습니다. 최종 API 사용 가능 여부, 플랫폼 동작과 심사 요건은 현재 Xcode SDK와 공식 Apple 자료를 기준으로 확인해야 합니다.

두 Skill 라이브러리를 모두 설치할 수 있나요?

네. 두 라이브러리는 서로를 보완합니다. 하나는 로컬 Apple 문서를 사실의 기준으로 제공하고, 다른 하나는 프레임워크별 지침과 엔지니어링 워크플로를 제공합니다. 기본적으로 전부 설치하지 말고 프로젝트별로 Skill을 선택하세요.

84개 Skill을 모두 설치하는 편이 더 좋은가요?

꼭 그렇지는 않습니다. 여러 Apple 플랫폼 프로젝트를 관리하는 팀에는 도움이 될 수 있지만, 단일 제품은 자주 사용하는 Skill 5~10개를 사용할 때 대개 더 명확하고 지침의 출처도 쉽게 추적할 수 있습니다.

이 Skill은 Codex 전용인가요?

아니요. 두 저장소 모두 Codex, Claude Code와 Cursor를 비롯한 여러 에이전트를 지원합니다. 설치 경로와 검색 방식은 각 에이전트의 현재 버전에 따라 다릅니다.