Claude Skills

What Is This?

Overview

Joannis/claude Skills is a specialized guidance tool designed to assist developers working with Swift on the server side. It combines development best practices with an integrated linting approach, helping teams write cleaner, more maintainable Swift code for backend applications. The tool draws from established patterns in the Swift server ecosystem, particularly around frameworks like Vapor and SwiftNIO.

The linting component enforces consistent code style and flags common mistakes before they reach production. Rather than acting as a simple style checker, it understands the specific patterns and pitfalls that arise in server-side Swift development, such as improper async handling, blocking calls on event loops, and misuse of concurrency primitives.

By combining guidance with automated checks, the tool bridges the gap between documentation and enforcement. Developers receive actionable feedback tied directly to the code they are writing, reducing the time spent reviewing style guides manually.

Who Should Use This

• Backend developers building APIs or microservices with Swift
• Teams migrating from other server languages to Swift
• Developers working with Vapor, Hummingbird, or SwiftNIO directly
• Technical leads establishing code standards for Swift server projects
• Open-source contributors working on Swift server packages
• Developers learning server-side Swift who need guardrails and guidance

Why Use It?

Problems It Solves

• Inconsistent code style across team members working on the same Swift server codebase
• Blocking calls accidentally placed on event loops, causing performance degradation
• Improper error handling patterns that lead to silent failures in production
• Difficulty onboarding new developers unfamiliar with server-side Swift conventions
• Time lost during code review on style and pattern issues that tooling could catch automatically

Core Highlights

• Tailored linting rules specific to server-side Swift, not just general Swift style
• Guidance on async/await and structured concurrency patterns
• Detection of common Vapor and SwiftNIO anti-patterns
• Integration with existing Swift Package Manager workflows
• Clear, actionable error messages with suggested fixes
• Support for custom rule configuration to match team preferences
• Covers both style enforcement and architectural best practices

How to Use It?

Basic Usage

To integrate the linting tool into a Swift server project, add it as a dependency in your Package.swift file and run it against your source directory.

// Package.swift
dependencies: [
    .package(url: "https://github.com/Joannis/claude-skills", from: "1.0.0")
]

Run the linter from the command line:

swift run claude-skills lint Sources/

The output will list violations with file paths, line numbers, and descriptions of the issue along with recommended corrections.

Specific Scenarios

Scenario 1: Catching blocking calls on event loops

When a developer accidentally uses a synchronous file read inside a route handler, the tool flags it:

// Flagged: blocking call on event loop
let data = try Data(contentsOf: fileURL)

The linter suggests replacing this with the appropriate async file I/O method available through the framework.

Scenario 2: Enforcing structured concurrency

The tool detects unstructured task creation that could lead to task leaks:

// Flagged: prefer structured concurrency
Task {
    await performWork()
}

It recommends using task groups or async let bindings where the lifecycle is properly managed.

Real-World Examples

A team building a REST API with Vapor uses the linter in their CI pipeline to block pull requests that introduce event loop violations. A solo developer learning SwiftNIO uses the guidance output to understand why certain patterns are discouraged before adopting bad habits.

When to Use It?

Use Cases

• Setting up a new Swift server project with consistent standards from day one
• Onboarding junior developers to server-side Swift conventions
• Conducting automated code quality checks in CI/CD pipelines
• Refactoring legacy Swift server code to modern concurrency patterns
• Reviewing open-source Swift server contributions before merging
• Preparing a codebase for production deployment
• Teaching server-side Swift in educational or workshop settings

Important Notes

Requirements

• Swift 5.7 or later is required for full concurrency rule support
• Swift Package Manager must be used as the build system
• Xcode 14 or a compatible Swift toolchain must be installed

Usage Recommendations

Do:

• Run the linter on every pull request through CI
• Review the explanation for each rule before disabling it
• Keep the tool updated to receive new rules as Swift server patterns evolve

Do not:

• Disable rules without documenting the reason in your configuration file
• Ignore warnings in development builds, as they often indicate real issues
• Use the tool as a replacement for code review, only as a complement