CLAUDE.md

Read AGENTS.md for the shared repository rules before making changes. This file is the Claude Code entry point and carries the same skill inventory.

Repository Overview

This is a reusable skills collection for coding agents, focused on Swift and iOS development. It contains curated skills that provide specialized expertise across different iOS/Swift domains. Each skill is a self-contained directory with structured documentation and examples or reference material.

Repository Structure

The repository follows a consistent pattern:

skills/<skill-name>/
├── SKILL.md               # Skill definition with frontmatter and instructions
├── README.md              # User-facing documentation
├── agents/
│   └── openai.yaml        # Optional OpenAI host UI metadata
├── examples/              # Practical code and prompts (when appropriate)
│   ├── prompts.md         # Positive and negative activation fixtures
│   └── *.swift            # Working code examples
├── docs/                  # Optional packaged documentation
└── references/            # Optional deep-dive guides

Available Skills

1. swiftui-programming-skill - SwiftUI declarative UI development, SF Symbols, state management
2. swift-modern-architecture-skill - Swift 6 architecture, SwiftData persistence, Observation framework, modern concurrency
3. ios-accessibility-skill - VoiceOver, Dynamic Type, HIG compliance
4. swift-performance-optimization-skill - Performance profiling, Instruments usage, memory efficiency
5. cross-platform-app-development-skill - Multi-platform app strategies
6. swift-unit-testing-skill - Swift Testing, XCTest, TDD, and test doubles
7. ios-animation-graphics-skill - SwiftUI Canvas, Lottie animations
8. memory-leak-diagnosis-skill - ARC, retain cycles, Instruments Leaks tool
9. swift-SpeechAnalyzer-Framework-Expert - SpeechAnalyzer and SpeechTranscriber for on-device transcription on iOS 26+ and macOS 26+
10. swift-concurrency-migration - Swift 6 concurrency migration and compiler-diagnostic workflows
11. swiftdata-core-data-migrations - Safe SwiftData and Core Data schema/store migrations
12. app-intents-widgets - App Intents, App Shortcuts, WidgetKit, and system surfaces
13. iphone-duo-design - Adaptive iPhone Duo design, state continuity, scenes, camera, and readiness verification

Working with Skills

Skill File Structure

Each SKILL.md follows this frontmatter format:

---
name: <Skill Name>
description: <What the skill does, when to use it, and when not to use it>
---

New skills use a lowercase kebab-case name matching their directory. Preserve the published name value of an existing skill unless a compatibility plan accompanies the change. Hosts use description for implicit activation, so front-load useful trigger terms and include exclusions.

Creating New Skills

When adding a new skill, follow these requirements:

1. Frontmatter: Include only name and a scope-rich description
2. Best Practices Section: Focused, domain-specific best practices
3. Guidelines Section: Additional domain-specific guidelines with bullet points
4. Supporting Material: Add practical examples in examples/, or use docs/ and references/ when the skill is primarily a reference package
5. Code Standards: Code examples must:
   • Follow Swift naming conventions (camelCase, PascalCase for types)
   • Include proper imports
   • Be runnable/compilable where applicable
   • Include explanatory comments where helpful
   • Use modern Swift features (async/await when appropriate)
6. Host Metadata: Add agents/openai.yaml with a concise display name, short description, and a default prompt that names $<skill-name>
7. Progressive Disclosure: Keep SKILL.md under 500 lines and link directly to focused examples or references

New skill directories should use lowercase kebab-case. Existing published directories should not be renamed without a compatibility and migration plan.

Code Quality Standards

All Swift code examples should adhere to:

• Apple's Swift API Design Guidelines
• SwiftUI best practices for declarative UI code
• Modern concurrency patterns (async/await, actors) when applicable
• Memory safety patterns (weak/unowned references, avoiding retain cycles)
• Accessibility-first design (proper labels, hints, Dynamic Type support)
• Type safety and clear error handling
• Explicit platform baselines when APIs require particular Swift, Xcode, iOS, macOS, watchOS, or tvOS versions

Testing Examples

When skills include testing patterns:

• Prefer Swift Testing for new unit and integration tests when the target/toolchain supports it
• Retain XCTest for UI automation, performance tests, Objective-C tests, and legacy suites
• Follow Arrange-Act-Assert structure
• Include both sync and async test examples
• Show proper mocking/dependency injection patterns
• Demonstrate performance testing when relevant

Contributing

Reference CONTRIBUTING.md for contribution guidelines, which include:

• Fork and pull request workflow
• Code must follow Apple's Swift and iOS guidelines
• Update SKILL.md and README.md with changes
• Test all code examples for correctness
• For new skills, include complete directory structure

Development Notes

Validation, not an app build

This repository contains documentation and example code snippets, not a runnable app. There is no shared Package.swift or Xcode project; repository scripts validate structure and type-check standalone examples against their declared SDK targets.

Documentation-Focused

The primary artifacts are .md files with embedded Swift code blocks. Code examples are illustrative and designed to be copied into real projects.

Version Management

The plugin manifests carry the collection's semantic version. Individual portable skill frontmatter intentionally contains only name and description.

Repository Synchronization

When adding, removing, or renaming a skill, update the inventories or structural guidance in AGENTS.md, CLAUDE.md, CODEX.md, and README.md. Update plugin metadata when the change affects the plugin description or release version.

Host independence

Keep core skill procedures usable through ordinary file reads and shell tools. Put host-specific installation and invocation details in the compatibility guide. Use the installer for copy or symlink setup; never merge skill trees into existing unrelated directories.