format-swift-sources

Format Swift Sources

Purpose

Use this skill as the top-level workflow for integrating and maintaining SwiftLint and SwiftFormat in Apple or Swift repositories. The skill keeps the support matrix explicit, teaches the shortest correct path for each surface, and includes a deterministic helper script for turning SwiftFormat for Xcode shared settings into a project-root .swiftformat file when the host app export path is unavailable or inconvenient. For shared Swift repositories, the preferred baseline is a checked-in repo-root .swiftformat plus a Git pre-commit hook that formats staged Swift sources and then reruns SwiftFormat in lint mode before the commit is allowed through. When both tools are in play, treat SwiftFormat as the primary owner of formatting shape and use SwiftLint as a complementary signal layer for clarity, safety, maintenance, and selectively chosen documentation expectations rather than as a second formatter. When the script path is needed, prefer feeding it the real shared plist from the SwiftFormat group container over assuming the defaults-domain export is complete, and treat the generated file as a curated starting point rather than as a guaranteed final repo config. It is also the canonical first pass before and after structure-swift-sources when a request will split, move, or reorganize Swift source files.

When To Use

• Use this skill when the user wants to add or maintain swiftformat, swiftlint, or both in a Swift repository.
• Use this skill when the user wants guidance on how to divide responsibility between SwiftFormat and SwiftLint in the same repository.
• Use this skill when the user wants guidance for one of these integration surfaces:
  • CLI
  • Xcode Run Script Build Phase
  • Xcode source editor extension
  • Swift Package Manager plugin
  • AppleScript or Automator-style local triggers
  • Git pre-commit hook
  • GitHub Actions
• Use this skill when the user wants to promote personal SwiftFormat for Xcode settings into a checked-in .swiftformat file.
• Use this skill when the user wants the recommended shared-repo formatting baseline for a Swift repository.
• Use this skill when the user needs the supported-path caveats for SwiftLint or SwiftFormat, such as plugin config-path limitations, Xcode script sandboxing, or per-project config gaps in the SwiftFormat extension.
• Use this skill first when a later structure-swift-sources pass will split files, move files, or normalize section layout and the repo needs a clean formatting baseline before structural edits begin.
• Recommend bootstrap-xcode-workspace --operation create --component-kind library when the user is creating a brand new Swift package and style tooling is only one part of that scaffold.
• Recommend bootstrap-xcode-workspace when the user is creating a native Apple product and style tooling is only one part of that scaffold.
• Recommend swift-package-build-run-workflow or swift-package-testing-workflow when the task shifts from style-tooling integration to ordinary SwiftPM package execution.
• Recommend swift-package-extension-workflow when the task shifts from formatter-specific setup to general plugin capability, permissions, generated outputs, dual-toolchain behavior, or Xcode handoff policy.
• Recommend xcode-build-run-workflow when the task shifts from style-tooling integration to active Xcode execution, diagnostics, or mutation work in an existing project.
• Recommend xcode-testing-workflow when the task shifts from style-tooling integration to active Xcode test work.
• Recommend structure-swift-sources when the task shifts from formatter or linter setup into file splitting, file moves, declaration grouping, or TODO/FIXME ledger cleanup.
• Recommend author-swift-docc-docs when the task shifts from style-tooling setup into symbol documentation, DocC article work, landing-page structure, topic groups, or DocC-oriented review.
• Recommend bootstrap-xcode-workspace --operation align for product guidance alignment.