agentsclimarketplace
Sign in

Swift source organization workflow

Skill gaelic-ghost/socket/plugins/swift-lang/skills/swift-source-organization-workflow

Organize Swift source trees and files by concern, feature, and layer; split oversized files, extract extension files, normalize MARK sections, file headers, and TODO/FIXME ledgers with stricter split defaults. Use after formatting baseline is clear.From its SKILL.md

Install
npx -y skills add gaelic-ghost/socket --skill swift-source-organization-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.4 KB, 644 tokens by cl100k_base, as published. Nobody here has run it

Swift Source Organization Workflow

Purpose

Keep Swift source trees small, navigable, and organized around real responsibility boundaries.

Use swift-format-style-workflow before structural edits and again afterward. Hand off to apple-dev-skills when file moves require Xcode target membership, project-file mutation, previews, schemes, or build/run validation.

Workflow

  1. Establish or confirm the formatting baseline.
  2. Resolve repo shape:
    • Swift package
    • Xcode app project
    • mixed package plus app
    • server-side Swift service
  3. Inventory source shape:
    • large files
    • mixed concerns
    • broad extensions
    • unclear access-control boundaries
    • nested types that block reuse
    • long TODO/FIXME comments
    • redundant or missing // MARK: sections
  4. Split by concern:
    • strongly consider splitting around 250 to 300 lines when two or more concerns are present
    • treat 500 to 600 lines as a hard split signal unless the file is generated or has a documented exception
    • prefer complete passes over tiny partial splits when adjacent files are part of the same concern cleanup
  5. Choose the split shape:
    • TypeName+Models.swift
    • TypeName+Validation.swift
    • TypeName+Pipeline.swift
    • TypeName+Formatting.swift
    • feature directories for independent user-facing or domain areas
    • layer directories when a package has clear API, domain, persistence, transport, or UI boundaries
  6. Preserve behavior:
    • keep access control intentional
    • keep generated files untouched
    • update package manifests or Xcode project membership through the owning workflow
    • run formatting after moves

MARK Guidance

  • Add // MARK: - <Heading> only when it improves navigation.
  • Name the responsibility boundary, not the declaration kind.
  • Avoid filler headings in short files.
  • Avoid comments that repeat obvious method or type names.

File Header And Ledger Guidance

  • Preserve existing license banners.
  • Use file headers only when the repository already requires them or the task explicitly includes header normalization.
  • Keep file-header purpose and concern text plain, specific, and non-generic.
  • Move long TODO and FIXME prose into ledgers when the repo uses ledger files; keep source comments short and traceable.

Output Shape

Return:

  1. Organization state: repo shape and largest concern problems.
  2. Split plan: files to split, target names, and reason for each split.
  3. Moves: directories or manifests that need updates.
  4. Handoffs: Apple Dev, Server-Side Swift, or package validation needs.
  5. Validation: formatting, build, test, or project-integrity checks.

Guardrails

  • Do not split files purely by line count when the file is coherent and generated files are excluded.
  • Do not invent abstraction layers just to make files shorter.
  • Do not move files across Xcode-managed boundaries without project-membership follow-through.
  • Do not leave duplicate helpers behind after extraction.
  • Do not use // MARK: as decoration.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 326,736. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.