SkillDeck: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Code Style: Comments Required

The author has extensive Java/Golang/Python experience but is new to Swift and macOS app development. All generated code must include detailed comments in English explaining:

• Swift-specific syntax and language features (e.g., @Observable, actor, some View, property wrappers)
• SwiftUI concepts and view lifecycle (e.g., .task, .environment(), NavigationSplitView)
• macOS/Apple platform APIs (e.g., NSWorkspace, DispatchSource, FileManager)
• Why a particular Swift pattern is used when it differs from the Java/Go/Python equivalent

Build & Run Commands

swift build                  # Development build
swift build -c release       # Optimized release build
swift run SkillDeck          # Build and launch the app
open Package.swift           # Open in Xcode (Cmd+R to run)
swift test                   # Run all tests
swift test --filter SkillMDParserTests                    # Run one test class
swift test --filter SkillMDParserTests/testParseStandardSkillMD  # Run one test method
swift package clean          # Clean build artifacts

First build downloads dependencies (Yams, swift-markdown, swift-collections).

Architecture

MVVM with @Observable (macOS 14+). The filesystem is the database — skills are directories containing SKILL.md files.

Views → ViewModels (@Observable) → SkillManager (@Observable) → Services (actor)

SkillManager (Services/SkillManager.swift) is the central orchestrator — injected into the view tree via .environment(). It coordinates all sub-services and exposes the public API that ViewModels call.

Services use Swift actor for thread-safe file system access:

• SkillScanner — scans ~/.agents/skills/ and per-agent directories, deduplicates via symlink resolution
• LockFileManager — reads/writes ~/.agents/.skill-lock.json with atomic writes and caching
• AgentDetector — detects installed agents by checking CLI binaries (which) and config directories
• SymlinkManager — static methods for creating/removing symlinks between canonical and agent directories
• FileSystemWatcher — DispatchSource/FSEvents monitoring with 0.5s debounce, publishes via Combine
• GitService — executes git CLI operations (clone, pull, fetch) for GitHub-based skill installs
• UpdateChecker — compares local vs remote commit hashes to detect skill updates
• SkillRegistryService — fetches skills from skills.sh registry API
• ClawHubService — fetches skills from ClawHub catalog for OpenClaw
• TranslationService — inline Chinese translation of skill docs (macOS 26+ Translation framework)
• KeychainService — stores/retrieves proxy credentials from macOS Keychain
• NetworkSessionProvider — provides URLSession instances with proxy configuration applied