/format-swift-sources

name: format-swift-sources
description: Guide SwiftLint and SwiftFormat integration across CLI, Xcode build phases, Xcode source-editor workflows, Swift Package plugins, AppleScript, Git hooks, and GitHub Actions, including exporting SwiftFormat for Xcode settings into a checked-in project config file. Use this first when a later source-organization pass needs a clean formatting baseline.

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.

Single-Path Workflow

1. Classify the request by tool selection:

• `swiftformat`
• `swiftlint`
• `both`

2. Classify the request by surface:

• `cli`
• `xcode-build-phase`
• `xcode-source-extension`
• `swiftpm-plugin`
• `applescript`
• `git-pre-commit`
• `github-actions`
• `swiftformat-xcode-config-export`

3. Check the support matrix in `references/integration-matrix.md` before proposing or generating steps. 4. Choose one documented path:

• when the user wants the default baseline for a shared Swift repo, prefer a checked-in root `.swiftformat` and a Git pre-commit hook that formats staged Swift files and then verifies them with `swiftformat --lint`
• for SwiftFormat settings export, prefer the host app export flow in `references/swiftformat-xcode-config-export.md`
• use `scripts/export-swiftformat-xcode-config.fsx` only when a deterministic shared-defaults export is needed
• when `defaults export` from the suite domain is empty, stale, or incomplete, point the script at the real shared plist inside the SwiftFormat group container with `--input-plist`
• after script export, review the generated file before checking it in because extension state may still need light curation
• for all other surfaces, use the tool-specific references instead of inventing a hybrid path

5. Return one supported setup path, one set of caveats, and one follow-up verification step. 6. When the request also includes source-organization work, hand off to `structure-swift-sources` only after this formatting path is