AI skill reference for SwiftLint — configuration, rules, custom rules, hooks, and violation fixing. Prevents hallucinated rule names, wrong config syntax, glob vs regex confusion, and other common LLM mistakes.
This skill is slightly opinionated — it favors the SPM plugin (SwiftLintPlugins) over Homebrew installation, --fix over the deprecated autocorrect subcommand, and baseline-driven adoption over disabling rules in legacy codebases. These opinions align with SwiftLint 0.55+ best practices, but older setups may use different conventions.
SwiftLint is the most widely-used Swift linter, but AI models consistently get its configuration wrong. They invent rule names that don't exist (force_optional, unnecessary_cast), confuse glob patterns with regex in config files, suggest the removed autocorrect subcommand, and combine mutually exclusive config keys (only_rules + opt_in_rules).
These aren't subtle issues — they produce configs that SwiftLint rejects outright or that silently lint the wrong files.
| Topic | What AI says (wrong) | What's actually correct |
|---|---|---|
| Rule names | Invents force_optional, avoid_force_unwrap |
Must validate — it's force_unwrapping (see rule catalog) |
| Auto-fix | swiftlint autocorrect |
swiftlint --fix (autocorrect subcommand removed) |
| Custom rule paths | Uses glob patterns (Sources/**/*.swift) |
Custom rules use regex ("Sources/.+\\.swift") |
| Rule selection | Combines only_rules + opt_in_rules |
Mutually exclusive — SwiftLint errors |
| Analyzer rules | Puts in opt_in_rules |
Separate analyzer_rules: key + swiftlint analyze command |
| File paths | swiftlint lint --path file.swift |
Positional arg: swiftlint lint file.swift (no --path flag) |
| Nested configs | Assumes always active | Disabled entirely when --config is passed on CLI |
| SPM plugin URL | Uses main SwiftLint repo | Use SimplyDanny/SwiftLintPlugins (avoids build overhead) |
mkdir -p ~/.claude/skills/swiftlint
cp SKILL.md ~/.claude/skills/swiftlint/
cp -r references ~/.claude/skills/swiftlint/The skill activates automatically when your conversation involves SwiftLint configuration, rules, violations, or linting commands.
mkdir -p ~/.agents/skills/swiftlint
cp SKILL.md ~/.agents/skills/swiftlint/
cp -r references ~/.agents/skills/swiftlint/The files are plain markdown — feed them as context to any AI coding assistant. Each reference file is self-contained:
- Configuration, CLI, custom rules, baselines:
references/configuration.md - Complete rule catalog with status:
references/rules.md - Claude Code hooks, git pre-commit, Xcode build phase, CI:
references/hooks.md
SKILL.md # Router + critical LLM mistakes + inline disable syntax + rule lookup
references/
├── configuration.md # Installation, CLI, config file, path patterns, custom rules, nesting, baselines, per-rule config
├── rules.md # Full rule catalog: Idiomatic, Lint, Metrics, Performance, Style (D/O/A status)
└── hooks.md # Claude Code afterEdit hook, git pre-commit, Xcode build phase, CI (GitHub Actions, Fastlane)
- realm/SwiftLint — official repository & documentation
- SwiftLint Rule Directory — complete rule reference with examples
- SimplyDanny/SwiftLintPlugins — recommended SPM plugin package
- SwiftLint source code — verified CLI flags, config parsing, regex behavior, and nesting rules
Found an inaccuracy, a missing rule, or have experience configuring SwiftLint in large-scale projects? PRs welcome. Please include the source (SwiftLint docs, source code reference, or your own production experience) for any additions.