CLAUDE.md · diff
git:20251021.d981f19 to git:20260814.a9c26d7
35 added, 24 removed. Audit A to A.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Overview
- This is a **Claude Skills Collection** repository 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.
+ This is a reusable skills collection for Claude Code and Codex, 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:
```
- <skill-name>/
- ├── SKILL.md # Skill definition with frontmatter and instructions
- ├── README.md # User-facing documentation
- ├── examples/
- │ ├── prompts.md # Example prompts and responses
- │ └── *.swift # Working code examples
- └── references/ # Optional deep-dive guides (modern architecture skill)
+ skills/<skill-name>/
+ ├── SKILL.md # Skill definition with frontmatter and instructions
+ ├── README.md # User-facing documentation
+ ├── agents/
+ │ └── openai.yaml # Optional portable 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** - XCTest framework, TDD, mocking patterns
+ 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
## Working with Skills
### Skill File Structure
Each `SKILL.md` follows this frontmatter format:
```yaml
---
name: <Skill Name>
- description: <Brief description>
- version: 1.0
- activation: <When to activate this skill>
+ description: <What the skill does, when to use it, and when not to use it>
---
```
- The activation field describes when the skill should be invoked based on user queries.
+ 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 YAML frontmatter with name, description, version, and activation
- 2. **Best Practices Section**: 6-10 numbered best practices specific to the domain
+ 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. **Examples Section**: 3-5 complete examples with:
- - User Prompt showing typical request
- - Expected Output with working Swift code
- - Following Apple's Swift conventions
- 5. **Code Standards**: All examples must:
+ 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. **Portable 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:
- - Use XCTest framework conventions
+ - 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
- ### No Build System
- This repository contains documentation and example code snippets, not a runnable project. There is no Package.swift, Xcode project, or build system.
+ ### 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
- Skills use semantic versioning in their frontmatter. Update version when making significant changes to skill content or examples.
+ 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.