@moon791017/neo-skills 1.0.1

package/skills/python/reference/coding-style.md

@@ -0,0 +1,92 @@
+# Modern Python Style Guide: Evolution & Conventions
+
+This guide integrates syntax evolutions from Python 3.10 to 3.14 with PEP 8 naming conventions, aimed at providing a consistent, modern, and high-quality development standard.
+
+---
+
+## Part 1: Modern Syntax & Type Evolution (3.10 - 3.14)
+
+### 1. Union Type Operator (3.10+)
+Use `|` instead of `typing.Union` and `Optional`.
+*   **✅ Recommended:** `def process(data: int | str | None):`
+*   **❌ Avoid:** `def process(data: Union[int, str, None]):`
+
+### 2. Structural Pattern Matching (3.10+)
+Use `match/case` for clear data deconstruction.
+*   **✅ Recommended:**
+    ```python
+    match response:
+        case {"status": 200, "data": content}:
+            return content
+        case _:
+            raise ValueError("Unknown response")
+    ```
+
+### 3. Self Type Annotation (3.11+)
+Use `typing.Self` when a class method returns an instance of itself.
+*   **✅ Recommended:** `def clone(self) -> Self: return self`
+
+### 4. Exception Groups and Propagation (3.11+)
+Use `except*` to handle `ExceptionGroup` thrown in concurrent tasks.
+*   **✅ Recommended:**
+    ```python
+    try:
+        await asyncio.gather(t1, t2)
+    except* ValueError:
+        log.error("Handling value errors")
+    ```
+
+### 5. Simplified Generics Syntax (3.12+)
+Use `[T]` directly after the function or class name.
+*   **✅ Recommended:** `def get_first[T](items: list[T]) -> T:`
+*   **❌ Avoid:** `T = TypeVar('T'); def get_first(items: List[T]) -> T:`
+
+### 6. f-string Restrictions Lifted (3.12+)
+Allows quote reuse and internal expression comments.
+*   **✅ Recommended:** `f"Name: {user["name"]}"`
+
+### 7. Deprecation Markers and Generic Defaults (3.13+)
+Use the `@deprecated` decorator and `Box[T = int]`.
+
+### 8. 3.14 Preview Features
+*   **Unparenthesized Exception Catching:** `except ValueError, TypeError:`
+*   **Deferred Annotation Evaluation:** `def set_next(self, node: Node):` (no string quotes required for Node)
+
+---
+
+## Part 2: Naming Conventions (PEP 8)
+
+### 1. Modules and Packages
+*   **Convention:** All lowercase, separated by underscores.
+*   **Example:** `data_processor.py`, `auth_utils/`
+
+### 2. Variables, Objects, and Parameters
+*   **Convention:** **snake_case**.
+*   **Conflict Handling:** If a name conflicts with a keyword, append a trailing underscore, e.g., `id_`, `class_`.
+*   **Example:** `user_count = 5`, `def fetch(id_: int):`
+
+### 3. Functions and Methods
+*   **Convention:** **snake_case**.
+*   **Internal Use:** Single leading underscore `_internal_method()`.
+*   **Name Mangling:** Double leading underscores `__private_attr` (to avoid collision in subclasses).
+
+### 4. Classes and Exceptions
+*   **Convention:** **PascalCase**.
+*   **Example:** `class UserProfile:`, `class DatabaseError(Exception):`
+
+### 5. Constants
+*   **Convention:** **SCREAMING_SNAKE_CASE**.
+*   **Example:** `MAX_RETRIES = 3`, `API_URL = "https://..."`
+
+---
+
+## Part 3: Resource Management & Security
+
+### 1. Context Managers
+Always use the `with` statement to ensure resource release.
+*   **✅ Recommended:** `with open("file.txt") as f:`
+*   **❌ Avoid:** `f = open(...); f.close()`
+
+### 2. Security (3.11+)
+Use `LiteralString` to prevent SQL/Shell injection.
+*   **✅ Recommended:** `def query(sql: LiteralString):`

package/skills/python/reference/patterns.md

@@ -0,0 +1,112 @@
+# Modern Python Patterns (3.10 - 3.14)
+
+This document lists recommended patterns and best practices for development in Python versions 3.10 through the latest 3.14.
+
+## 1. Structural Pattern Matching (3.10+)
+Use `match` statements to handle complex branching logic, data deconstruction, and Guard conditions.
+
+### Recommended
+```python
+def handle_event(event: dict):
+    match event:
+        case {"type": "click", "position": (x, y)}:
+            print(f"Click at {x}, {y}")
+        case {"type": "keypress", "key": key} if key.isalnum(): # Supports Guard conditions
+            print(f"Key pressed: {key}")
+        case _:
+            print("Unknown event")
+```
+
+## 2. Union Type Operator (3.10+)
+Use `X | Y` instead of `Union[X, Y]` for more readable type annotations.
+
+### Recommended
+```python
+def process_data(data: int | str | None) -> None:
+    # Supports both type hints and isinstance()
+    if isinstance(data, int | str):
+        print(f"Processing: {data}")
+```
+
+## 3. Exception Handling and Concurrent Tasks (3.11+)
+Use Exception Groups and `asyncio.TaskGroup` to manage concurrency.
+
+### Recommended
+```python
+import asyncio
+
+async def main():
+    # New code should prefer TaskGroup over asyncio.gather()
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(fetch_data())
+        tg.create_task(process_data())
+
+try:
+    await main()
+except* ValueError as eg: # Use except* to handle Exception Groups
+    for e in eg.exceptions:
+        print(f"Caught error: {e}")
+```
+
+## 4. Modern Generics and Type Aliases (3.12+)
+Use the new square bracket syntax for generic declarations and the `type` keyword for type aliases.
+
+### Recommended
+```python
+# Generic function declaration (PEP 695)
+def get_first[T](items: list[T]) -> T:
+    return items[0]
+
+# Generic classes and type aliases
+type Point[T] = tuple[T, T]
+
+class Container[T]:
+    def __init__(self, value: T):
+        self.value = value
+```
+
+## 5. Enhanced f-strings (3.12+)
+Leverage unrestricted f-strings to improve code flexibility.
+
+### Recommended
+```python
+songs = ["Playlist A", "Playlist B"]
+# Supports quote reuse and multiline comments
+message = f"Songs: {
+    ", ".join(songs) # Quotes can be reused internally
+} total: {len(songs)} # Supports internal comments"
+```
+
+## 6. PEP 758: Unparenthesized Exception Handling (3.14+)
+Parentheses can be omitted when catching multiple exceptions if the exception instance is not accessed.
+
+### Recommended
+```python
+try:
+    resource = fetch()
+except ConnectionError, TimeoutError: # Omit parentheses allowed from 3.14+
+    log_error("Network request failed")
+```
+
+## 7. Deferred Annotation Evaluation (3.14+)
+String quotes are no longer required when a class refers to itself or classes not yet defined.
+
+### Recommended
+```python
+class Node:
+    # 3.14 supports deferred evaluation; Node name can be used directly
+    def set_next(self, node: Node):
+        self.next = node
+```
+
+## 8. Pathlib Native Operations (3.14+)
+Prefer native copy and move methods built into `pathlib`.
+
+### Recommended
+```python
+from pathlib import Path
+
+source = Path("data.json")
+# 3.14+ supports native copy
+source.copy("backup.json")
+```

package/skills/python-manager/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: python-manager
+version: "1.1.0"
+category: "Environment"
+description: "智慧偵測與管理 Python 專案的虛擬環境與依賴套件工具（支援 uv, Poetry, venv/pip），包含工具安裝導引。"
+compatibility: "Supports any Python project containing pyproject.toml, requirements.txt, uv.lock, or poetry.lock."
+---
+
+# Python Environment Manager Skill
+
+## Trigger On
+- The user asks "How do I install a package?" or "Which package manager is this project using?".
+- The user requests to add, remove, or update Python dependencies.
+- Need to initialize a virtual environment or execute a Python script but unsure whether to use `uv run`, `poetry run`, or `python`.
+- The project lacks explicit environment configuration and needs recommendations for suitable tools.
+
+## Workflow
+1. **Perceive:**
+   - Scan the project root for characteristic files: `uv.lock`, `poetry.lock`, `pyproject.toml`, `requirements.txt`.
+   - Check the system environment to test if tools are installed: execute `uv --version` or `poetry --version`.
+2. **Reason:**
+   - Determine the tool the project should use based on characteristic files (Priority: `uv` > `Poetry` > `pip`).
+   - **Check tool availability**: If the project is determined to use `uv` but it's not installed, or if the user wants to switch to `uv/Poetry` but the environment is not ready, mark it as "Pending Installation".
+3. **Act:**
+   - **Tool Installation Suggestion**: If the tool is not installed, **must ask the user first**: "Detected that the project uses [Tool Name], but it is not installed in your environment. Would you like me to provide the installation command and assist with the installation?"
+   - **Output Commands**: Provide the correct operation commands for the identified management tool.
+   - **Execute Changes**: If the user agrees to installation or dependency changes, provide CLI commands for user confirmation.
+
+## Tooling Commands Reference
+
+### 1. uv (Recommended: Ultra-fast Tool)
+- **Detection Criteria:** `uv.lock` exists.
+- **Installation (Unix/macOS):** `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- **Installation (Windows):** `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+- **Common Commands:**
+  - `uv add <package>` (Add package)
+  - `uv sync` (Sync environment)
+  - `uv run <script.py>` (Run script)
+
+### 2. Poetry
+- **Detection Criteria:** `poetry.lock` exists or `[tool.poetry]` in `pyproject.toml`.
+- **Installation (Cross-platform):** `curl -sSL https://install.python-poetry.org | python3 -`
+- **Common Commands:**
+  - `poetry add <package>` (Add package)
+  - `poetry install` (Install dependencies)
+  - `poetry run python <script.py>` (Run script)
+
+### 3. venv + pip (Legacy Standard)
+- **Detection Criteria:** Only `requirements.txt` or `.venv` exists.
+- **Common Commands:**
+  - `pip install <package>`
+  - `pip install -r requirements.txt`
+
+## Deliver
+- **Environment Detection Report:** Inform the current environment status (e.g., uv installed, poetry.lock detected).
+- **Installation and Operation Guidance:** If tools are missing, proactively ask for installation consent and provide the correct syntax.
+- **Environment Consistency Check:** Ensure provided commands perfectly match the project's existing lock files.
+
+## Validate
+- Never execute installation commands directly without asking the user.
+- Installation commands must distinguish between operating systems (macOS/Linux vs Windows).

package/skills/start-plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: start-plan
+description: 分析需求與專案現況，並生成詳細的開發執行計畫。
+---
+
+# Development Execution Planning Specification
+
+## Perceive
+1. **Context Gathering**: Systematically map the codebase using search tools (`grep_search`, `glob`) to understand file structures and existing patterns.
+2. **Constraint Check**: Identify coding styles, configuration files (e.g., `package.json`, `gemini-extension.json`), and framework dependencies.
+3. **Mandatory Deep Dive**: Validate all assumptions by reading relevant file contents. Do not skip this step.
+
+## Reason
+1. **Gap Analysis**: Clearly define the delta between the current codebase state and the user's desired state.
+2. **Architectural Fit**: Ensure the proposed solution aligns with the established architecture (e.g., separating logic into `skills/`, using `commands/` for entry points).
+3. **Risk Assessment**: Identify potential breaking changes, ambiguous requirements, or side effects.
+4. **Dependency Chain**: Determine the strictly logical order of operations (e.g., "Create directory before creating file").
+
+## Act
+1. **Structure the Plan**: Present the plan to the user in **Traditional Chinese (Taiwan)** using the following mandatory sections:
+   - **🧐 現況分析 (Context Analysis)**: Relevant files and architectural overview.
+   - **🎯 執行目標 (Objectives)**: Concise summary of the mission.
+   - **🛠️ 詳細執行計畫 (Step-by-Step Plan)**: Concrete steps presented as a **numbered list** (DO NOT use Markdown tables). Each step must include:
+     - **類型**: Action Type
+     - **路徑**: File Path
+     - **說明**: Detailed description
+     - **驗證**: Verification method
+   - **⚠️ 風險與確認事項 (Risks & Questions)**: Side effects or points requiring clarification.
+2. **Constraint**: Do not write code or modify files during the planning phase.

package/skills/swift/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: swift
+version: "1.0.0"
+category: "Language"
+description: "Swift 專家技能 (5.0+)。支援從基礎語法到 Swift 6 的現代開發模式，涵蓋 SwiftUI、Structured Concurrency、記憶體安全以及高效能 App 開發指引。"
+compatibility: "Supports Swift 5.0 through 6.0+. Adaptive to iOS, macOS, and Server-side Swift environments."
+---
+
+# Modern Swift (5.0+) Expert Skill
+
+## Trigger On
+- The user asks to write, debug, refactor, or review Swift code.
+- The project directory contains `*.swift`, `Package.swift`, or `*.xcodeproj`.
+- Development involves iOS (SwiftUI/UIKit), macOS, or Server-side Swift (Vapor).
+- Code modernization is needed (e.g., migrating to Structured Concurrency or Swift 6 language mode).
+
+## Workflow
+1. **Perceive (Version Awareness):**
+   - Identify the Swift version (e.g., check `Package.swift` or build settings).
+   - Determine the platform (SwiftUI vs UIKit, Server vs App).
+   - Assess dependency management (Swift Package Manager, CocoaPods).
+2. **Reason (Planning Phase):**
+   - Evaluate the use of modern syntax (e.g., `async/await`, `Result`, `@propertyWrapper`).
+   - Decide on memory management strategies (ARC, `weak/unowned`).
+   - For UI tasks, prioritize SwiftUI for modern apps or UIKit for legacy support.
+3. **Act (Execution Phase):**
+   - Write swifty, concise code following Apple's API Design Guidelines.
+   - Implement type-safe and protocol-oriented solutions.
+   - Leverage **Structured Concurrency** (`Task`, `async let`) for asynchronous operations.
+4. **Validate (Standard Validation):**
+   - Check for memory leaks (retain cycles) using capture lists.
+   - Verify Swift 6 concurrency safety (data race detection).
+   - Ensure naming conventions follow the standard `lowercamelCase` for members and `PascalCase` for types.
+
+## Feature Roadmap (Swift 5.0 - 6+)
+
+### Swift 5.0 - 5.4 (Foundation)
+- **Result Type**: Standardized error handling.
+- **Property Wrappers**: Encapsulating property logic (e.g., `@Published`).
+- **Opaque Types**: Hiding implementation details (`some View`).
+- **Result Builders**: DSL support for SwiftUI.
+
+### Swift 5.5 - 5.10 (Modern Concurrency)
+- **Async/Await**: Linear asynchronous code.
+- **Actors**: Thread-safe state isolation.
+- **Distributed Actors**: Communicating across processes.
+- **Non-copyable Types**: Explicit control over object ownership.
+
+### Swift 6+ (Safety & Performance)
+- **Full Data Isolation**: Compile-time data race prevention.
+- **Typed Throws**: Explicitly defining error types.
+- **Embedded Swift**: Running Swift on restricted environments.
+
+## Coding Standards
+- **Conciseness**: Use trailing closures and shorthand argument names where appropriate.
+- **Safety**: Prefer `if let` or `guard let` over force unwrapping (`!`).
+- **Purity**: Prefer `struct` (Value Types) over `class` (Reference Types) for data models.
+- **Concurrency**: Avoid `Thread.sleep` or legacy completion handlers; use structured concurrency.
+
+## Deliver
+- **Version-Optimized Code**: Provide code using the best features of the target Swift version.
+- **SwiftUI/UIKit Insights**: Recommend patterns based on the UI framework used.
+- **Concurrency Migration**: Provide strategies for moving to Swift 6 strict concurrency checks.
+
+## Validate
+- Ensure code compiles without warnings in the target Swift version.
+- Validate that closure capture lists correctly handle object lifecycles.
+- Confirm that error handling uses the `do-catch` or `throws` patterns correctly.
+
+## Documentation
+### Official References
+- [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
+- [The Swift Programming Language Guide](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/)
+
+### Internal References
+- [Swift Coding Style and Naming Conventions](reference/coding-style.md)
+- [Swift Anti-Patterns and Best Practices](reference/anti-patterns.md)
+- [Modern Swift Patterns Guide](reference/patterns.md)

package/skills/swift/reference/anti-patterns.md

@@ -0,0 +1,75 @@
+# Swift Anti-Patterns & Best Practices
+
+This document highlights common pitfalls in Swift development and the recommended ways to avoid them.
+
+## 1. Memory Management
+
+### 1.1 Avoid Retain Cycles (Strong Reference Cycles)
+**Problem**: Two objects holding strong references to each other will never be deallocated, causing a memory leak.
+
+- **Bad**:
+  ```swift
+  class Client {
+      var onComplete: (() -> Void)?
+      func start() {
+          onComplete = { self.doSomething() } // Retain cycle
+      }
+  }
+  ```
+- **Good**:
+  ```swift
+  onComplete = { [weak self] in 
+      self?.doSomething() 
+  }
+  ```
+
+### 1.2 Avoid `unowned` for Async Work
+**Problem**: `unowned` assumes the object will always exist. If the object is deallocated before the async work finishes, the app will crash.
+- **Best Practice**: Use `weak` for closures that might outlive their context.
+
+---
+
+## 2. Optionals
+
+### 2.1 Avoid Force Unwrapping (`!`)
+**Problem**: Force unwrapping a `nil` value causes an immediate runtime crash.
+
+- **Bad**: `let url = URL(string: str)!`
+- **Good**: `guard let url = URL(string: str) else { return }`
+
+### 2.2 Avoid Implicitly Unwrapped Optionals
+- **Problem**: Variables like `var name: String!` are dangerous because they hide the possibility of `nil`.
+- **Exception**: IBOutlets in iOS development are a standard exception.
+
+---
+
+## 3. UI Patterns (App Context)
+
+### 3.1 Avoid Massive View Controller
+**Problem**: Putting all networking, business logic, and UI code in a single `UIViewController`.
+- **Best Practice**: Use **MVVM** or **Clean Architecture** to separate concerns.
+
+### 3.2 Avoid Hardcoded Strings
+- **Best Practice**: Use `NSLocalizedString` for text and Enums for identifiers (like Segue IDs or Cell IDs).
+
+---
+
+## 4. Concurrency
+
+### 4.1 Avoid `Thread.sleep` or Busy Waiting
+- **Best Practice**: Use `Task.sleep(nanoseconds:)` in Swift Concurrency or dispatch queues.
+
+### 4.2 Avoid Main Thread Blocking
+- **Problem**: Performing heavy I/O or network requests on `DispatchQueue.main`.
+- **Best Practice**: Use `Task` or `background` queues, then switch back to `main` only for UI updates.
+
+---
+
+## 5. General Design
+
+### 5.1 Avoid Overusing Singletons
+**Problem**: Global state makes unit testing difficult and creates hidden dependencies.
+- **Best Practice**: Use **Dependency Injection** to pass services to objects.
+
+### 5.2 Avoid String-based APIs
+- **Best Practice**: Prefer Type-safe APIs. For example, use `Codable` for JSON instead of manually parsing `[String: Any]`.

package/skills/swift/reference/coding-style.md

@@ -0,0 +1,56 @@
+# Swift Coding Conventions
+
+This guide follows Apple's official [API Design Guidelines](https://swift.org/documentation/api-design-guidelines/) to ensure code is readable, maintainable, and "Swifty."
+
+## 1. Naming Conventions
+
+### 1.1 Capitalization
+- **Types and Protocols**: Use `PascalCase` (e.g., `UserData`, `NetworkManager`).
+- **Variables, Properties, and Methods**: Use `lowercamelCase` (e.g., `userName`, `fetchData()`).
+- **Enums**: Use `lowercamelCase` for cases (e.g., `case success(String)`).
+
+### 1.2 Clarity Over Brevity
+- **Grammatical Usage**: Method names should read like English phrases.
+  - `list.insert(x, at: i)` instead of `list.put(x, i)`.
+- **Protocols**: 
+  - Protocols that describe *what* something is should be nouns (e.g., `Collection`).
+  - Protocols that describe a *capability* should end in `-able` or `-ible` (e.g., `Equatable`, `Codable`).
+
+---
+
+## 2. Code Organization
+
+- **Extensions**: Use `extension` to group protocol conformance or logical chunks of code.
+- **Access Control**: Be explicit with `private`, `fileprivate`, `internal` (default), and `public`. Use `private(set)` for properties that should be read-only from the outside.
+- **File Structure**: Prefer one primary type per file.
+
+---
+
+## 3. Idiomatic Swift
+
+### 3.1 Type Inference
+- Let the compiler infer types when the meaning is obvious.
+  - `let names = [String]()` is preferred over `let names: [String] = []`.
+
+### 3.2 Closures
+- Use **Trailing Closure Syntax** whenever a closure is the last argument.
+  - `UIView.animate(withDuration: 0.3) { ... }`
+
+### 3.3 Structs vs. Classes
+- **Default to Structs**: Use `struct` for data models and state.
+- **Use Classes**: Only when you need identity, inheritance, or `deinit` logic.
+
+---
+
+## 4. Error Handling
+
+- **Guard**: Use `guard` to exit early from functions, reducing indentation.
+- **Optional Binding**: Use `if let` or `guard let` instead of `!` (force unwrap).
+- **Throws**: Use `throws` for recoverable errors and `Result` for asynchronous error passing in legacy Swift (5.5+ prefers `async throws`).
+
+---
+
+## 5. Documentation
+
+- **Triple Slash**: Use `///` for documentation comments. This enables Quick Help in Xcode.
+- **Parameters**: Document parameters and return values using `- Parameters:` and `- Returns:`.

package/skills/swift/reference/patterns.md

@@ -0,0 +1,94 @@
+# Modern Swift Patterns Guide
+
+This document covers recommended architectural and language patterns for Swift 5.0 through 6.0+.
+
+## 1. Structured Concurrency (Swift 5.5+)
+
+### 1.1 Async/Await
+Replace completion handlers with `async` functions for linear, readable code.
+```swift
+func fetchUser() async throws -> User {
+    let data = try await network.request(url)
+    return try JSONDecoder().decode(User.self, from: data)
+}
+```
+
+### 1.2 Task Groups and `async let`
+Run multiple tasks in parallel safely.
+```swift
+async let avatar = downloadImage(id: 1)
+async let profile = fetchProfile(id: 1)
+let result = try await User(profile: profile, image: avatar)
+```
+
+---
+
+## 2. State Management
+
+### 2.1 Property Wrappers
+Encapsulate logic for reuse across properties.
+```swift
+@propertyWrapper
+struct Trimmed {
+    private var value: String = ""
+    var wrappedValue: String {
+        get { value }
+        set { value = value.trimmingCharacters(in: .whitespacesAndNewlines) }
+    }
+}
+```
+
+### 2.2 Observability (Swift 5.9+)
+Using the `@Observable` macro instead of `ObservableObject` for more efficient UI updates in SwiftUI.
+
+---
+
+## 3. Protocol-Oriented Programming (POP)
+
+### 3.1 Protocol Extensions
+Provide default implementations to protocols.
+```swift
+protocol Validatable {
+    var isValid: Bool { get }
+}
+
+extension Validatable {
+    var isValid: Bool { return true } // Default implementation
+}
+```
+
+### 3.2 Opaque Return Types
+Return a type that conforms to a protocol without exposing the concrete type.
+```swift
+func makeView() -> some View { ... }
+```
+
+---
+
+## 4. Swift 6 Concurrency Safety
+
+### 4.1 Actors
+Protect mutable state from data races.
+```swift
+actor Counter {
+    private var value = 0
+    func increment() { value += 1 }
+}
+```
+
+### 4.2 Sendable
+Ensure types can be safely passed between concurrent contexts.
+```swift
+struct Message: Sendable {
+    let text: String
+}
+```
+
+---
+
+## 5. UI Architecture: MVVM
+
+Decouple business logic from View layers (SwiftUI or UIKit).
+- **Model**: Data structures (`struct`).
+- **ViewModel**: Logic handler (`class` with `@Published` or `@Observable`).
+- **View**: UI declaration.

package/skills/swift-ui/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: swift-ui
+version: "1.0.0"
+category: "UI Framework"
+description: "SwiftUI 專家技能 (iOS 16.0+)。支援從宣告式 UI 基礎到 iOS 18+ 的現代開發模式，涵蓋 NavigationStack、Observation 框架、資料流架構及高效能視圖設計。"
+compatibility: "Requires iOS 16.0+, Swift 5.0+. Adaptive to modern iOS, iPadOS, and macOS SwiftUI development."
+---
+
+# Modern SwiftUI (iOS 16+) Expert Skill
+
+## Trigger On
+- The user asks to write, debug, refactor, or review SwiftUI code.
+- The target project version is iOS 16 or higher (utilizing features like `NavigationStack`, `Grid`, etc.).
+- Development involves state management (`@State`, `@Observable`), custom layouts, or animations.
+
+## Workflow
+1. **Perceive (Version and Environment Awareness):**
+   - Confirm if the deployment target is iOS 16+.
+   - Identify the current state management paradigm (traditional `ObservableObject` vs. modern `@Observable`).
+   - Assess the usage of navigation components (check if deprecated `NavigationView` is still in use).
+2. **Reason (Planning Phase):**
+   - Plan the view hierarchy to maximize reusability and minimize redundant `body` computations.
+   - Enforce the use of `NavigationStack` or `NavigationSplitView` for navigation needs.
+   - Select the correct data flow tools based on data lifecycle (`State`, `Binding`, `Environment`).
+3. **Act (Execution Phase):**
+   - Follow SwiftUI core principles to write concise, declarative Swift code.
+   - Use `Grid`, `ViewThatFits`, or custom `Layout` protocols to implement complex layouts.
+   - Leverage modern modifiers (e.g., `.sheet` with `detents`).
+4. **Validate (Standard Validation):**
+   - Check for "God Views" (views with excessive logic or `body` content) and suggest splitting them.
+   - Ensure `@State` and `@Binding` are used correctly to avoid unnecessary view refreshes.
+   - Verify that the UI remains fluid and adheres to Apple's Human Interface Guidelines (HIG).
+
+## Feature Roadmap (SwiftUI Evolution)
+
+### iOS 13.0 - 15.0 (Foundation Era)
+- **Declarative Syntax**: Core `View` protocol and `body` property.
+- **State Management**: `@State`, `@Binding`, `@ObservedObject`, `@EnvironmentObject`.
+- **Basic Containers**: `VStack`, `HStack`, `ZStack`, `List`.
+- **Legacy Navigation**: `NavigationView` and `NavigationLink`.
+
+### iOS 16.0 - 17.0 (Modern Era)
+- **NavigationStack**: Decoupled and data-driven navigation pattern.
+- **Observation Framework**: `@Observable` macro (Swift 5.9+) replacing `ObservableObject`.
+- **Advanced Layouts**: `Grid`, `ViewThatFits`, and `Layout` protocol.
+- **Swift Charts**: Native data visualization framework.
+
+### iOS 18.0+ (Latest Features)
+- **SwiftUI Animations**: New phase-based and keyframe-based animation APIs.
+- **Interaction Enhancements**: Improved Scroll View controls and gesture handling.
+
+## Coding Standards
+- **Declarative Style**: Keep the view tree structure clear and avoid writing complex logic within `body`.
+- **Modularity**: Split subviews into independent `structs` instead of computed properties.
+- **Preview Guidelines**: Use the `#Preview` macro for rapid development, testing across multiple environment settings (Dark Mode, different locales).
+- **Type Safety**: Prefer strongly typed navigation paths and environment keys.
+
+## Deliver
+- **Version-Optimized Code**: Provide code utilizing iOS 16+ features (e.g., `NavigationStack`, `presentationDetents`).
+- **Modular View Components**: Deconstruct large views into single-responsibility, reusable components.
+- **Modern State Management**: Prioritize the `@Observable` pattern for projects supporting Swift 5.9+.
+
+## Validate
+- Ensure code compiles without warnings and uses the best available APIs for the target version.
+- Validate view `body` execution efficiency, ensuring no side effects are included.
+- Confirm that data flow follows the unidirectional flow principle whenever possible.
+
+## Documentation
+### Official References
+- [SwiftUI Documentation](https://developer.apple.com/documentation/swiftui/)
+- [Human Interface Guidelines (Layout)](https://developer.apple.com/design/human-interface-guidelines/layout)
+
+### Internal References
+- [SwiftUI Coding Style and Naming Conventions](reference/coding-style.md)
+- [SwiftUI Anti-Patterns and Best Practices](reference/anti-patterns.md)
+- [Modern SwiftUI Patterns Guide](reference/patterns.md)