SwiftButler

Analyze, syntax-check, reindent, and distribute Swift source code with the SwiftButler CLI. Use when working with Swift files or packages and you need a comp...

Security Scan

The skill is internally consistent: it wraps a Homebrew-installable CLI (butler) for operating on local Swift source files and asks for no credentials or unusual access.

Purpose & Capability

Name/description, required binary (butler), and usage examples all align: the skill exists to run the SwiftButler CLI on Swift source. Requiring the butler binary is proportional to the stated purpose.

Instruction Scope

SKILL.md instructs the agent to install/verifiy the CLI and run commands (analyze, check, reindent, distribute) against local source paths. All referenced files/paths are within the scope of editing or inspecting Swift code; there is no instruction to read unrelated system files or exfiltrate data.

Install Mechanism

Install uses a Homebrew formula from the cocoanetics/tap. Homebrew formulas are common and expected for macOS tooling, but third-party taps can install arbitrary code—reviewing the formula or upstream repo is recommended.

Credentials

No environment variables, credentials, or config paths are requested. This is proportional: the CLI operates on local files and doesn't require external secrets.

Persistence & Privilege

always:false and normal model invocation. The skill does not request permanent presence or modify other skills' configs. It will execute local CLI commands when invoked, which is expected.

Assessment

This skill will run a local CLI (butler) that can modify your Swift source (reindent/distribute). Before installing: 1) verify the Homebrew tap/formula and upstream GitHub repo if you don't trust the tap (brew taps can install arbitrary code); 2) run commands with --dry-run or target a copy of your repo first to avoid unexpected file changes; 3) confirm the installed binary with butler --version and inspect its behavior on a small test directory. If you need higher assurance, review the formula and the tool's source on the linked GitHub page.

Use butler to reduce Swift source into a more manageable working surface.

Setup

Install via Homebrew:

brew install cocoanetics/tap/swiftbutler

Verify:

butler --version

For local development from a checkout:

swift build
.build/debug/butler --version

Core Rules

• Prefer analyze when an agent needs API shape, not full implementation details.
• Prefer --format yaml or --format json when the result will be parsed or reused.
• Prefer check for fast validation loops before swift build.
• Use reindent to normalize indentation in place; choose exactly one of --spaces <n> or --tabs.
• Use distribute before targeted edits when a generated file has become too large or noisy.

Fast Command Map

Analyze Swift APIs

# Default interface-style output
butler analyze Sources/MyModule

# Public API only
butler analyze Sources/MyModule --visibility public

# Recursive YAML output for tooling
butler analyze Sources --recursive --format yaml

# Write structured output to a file
butler analyze Sources --recursive --format yaml --output api.yaml

Supported formats:

• interface
• json
• yaml
• markdown

Syntax-check Swift quickly

butler check Sources --recursive
butler check Sources --recursive --json
butler check Sources --recursive --json --pretty
butler check Sources --recursive --format markdown --show-fixits

Reindent with spaces or tabs

# Default: 3 spaces
butler reindent Sources --recursive

# Explicit spaces
butler reindent Sources --recursive --spaces 2
butler reindent Sources --recursive --spaces 4

# Tabs instead of spaces
butler reindent Sources --recursive --tabs

# Preview without modifying files
butler reindent Sources --recursive --tabs --dry-run

Notes:

• --spaces <n> accepts values from 1 to 16.
• --tabs and --spaces <n> are mutually exclusive.
• Without --tabs, the default is --spaces 3.

Distribute large files into smaller ones

# Split one large generated file
butler distribute Generated.swift

# Preview recursive distribution
butler distribute Sources/Generated --recursive --dry-run

# Write distributed files to a separate directory
butler distribute Sources/Generated --recursive --output SplitSources

When to Use Which Command

• Use analyze to hand an LLM a compact view of types, functions, properties, and docs.
• Use check inside generation or repair loops for immediate syntax feedback.
• Use reindent after generated or patched code has inconsistent indentation.
• Use distribute when one large Swift file should become declaration-sized files that are easier to inspect and edit.