Ha IOS Code Style
Developmentha-ios-code-styleHa IOS Code Style is an Agent Skill for development published in the home-assistant/iOS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Swift code style, linting, logging, assets, and idioms for Home Assistant iOS. Use when writing or formatting Swift, running SwiftFormat/SwiftLint, referencing SF Symbols or Material Design icons, logging, or using the with() helper.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/home-assistant/iOS/blob/HEAD/.agents/skills/ha-ios-code-style/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ha-ios-code-style, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Code Style, Linting, Logging & Assets
Automated Linting
# Check for lint issues (does not modify files)
bundle exec fastlane lint
# Auto-fix lint issues (run before committing!)
bundle exec fastlane autocorrect
Always run bundle exec fastlane autocorrect after making changes and before committing.
Linters Used
| Tool | Config File | Purpose |
|---|---|---|
| SwiftFormat | .swiftformat | Code formatting (120 char max, before-first wrapping) |
| SwiftLint | .swiftlint.yml | Code quality rules |
| Rubocop | .rubocop.yml | Ruby/Fastlane code |
| YamlLint | .yamllint.yml | YAML files |
Key SwiftFormat Rules
- Max line width: 120 characters
- Wrap arguments/parameters/collections:
before-first selfkeyword: only in initializers (--self init-only)- Guard else: same line
- Headers: stripped (no file header comments)
Key SwiftLint Rules
- No
force_castorforce_try - Keep cyclomatic complexity low
- No assigning to
Current.*outside tests - Use
SFSafeSymbolsfor SF Symbol references:
// ❌ Wrong
Image(systemName: "house")
// ✅ Correct
Image(systemSymbol: .house)
Logging
Use Current.Log (XCGLogger) — never print or NSLog:
Current.Log.info("Connected to \(server.info.name)")
Current.Log.error("Failed: \(error.localizedDescription)")
Current.Log.verbose("Debug detail")
with() Helper
with(_:update:) in Sources/Shared/Common/With.swift is used for fluent inline initialization:
public lazy var webhooks = with(WebhookManager()) {
$0.register(responseHandler: ..., for: .updateSensors)
}
Assets
- SF Symbols via
SFSafeSymbolslibrary (Image(systemSymbol: .house)), never the string-based API - HA domain/entity icons via the
MaterialDesignIconsenum (auto-generated from JSON); names carry anIconsuffix (e.g..lightbulbIcon), andDomain.icon(deviceClass:state:)provides domain-appropriate icons - Asset catalogs in
Sources/Shared/Assets/SharedAssets.xcassets