Communitygithub.com

CharbelElBateh/personal-website

Habilidad para escribir Swift moderno de manera correcta — modelado con tipos valor, seguridad de datos en Swift 6, concurrencia accesible (@concurrent, main-actor-por-defecto, actores, grupos de tareas), protocolos y genéricos (some vs any), diseño de APIs, rendimiento y ARC, Swift Testing, macros, y las características modernas del lenguaje que los agentes aún no conocen. Úsala al escribir, revisar o migrar Swift, o al corregir un error de concurrencia, un bloqueo, una condición de carrera, un ciclo de retención o un problema de rendimiento.

¿Qué es personal-website?

Esta habilidad se especializa en guiar a los agentes de IA sobre cómo escribir Swift moderno, siguiendo las mejores prácticas y las características más recientes del lenguaje, hasta Swift 6.4. Su objetivo es enseñar un enfoque de 'divulgación progresiva', comenzando con las soluciones más simples y estáticas, y añadiendo dinamismo (concurrencia, semántica de referencia, existenciales, punteros inseguros) solo cuando sea necesario y justificable. La habilidad cubre áreas críticas como el modelado de datos con tipos valor (structs y enums), el manejo de errores y opcionales, la concurrencia segura y eficiente (con énfasis en el modelo de Swift 6.2 donde `async` no mueve el código fuera del actor actual), tipos Sendable y cómo compartir datos correctamente, y la preferencia por tareas estructuradas. Está diseñada para ser utilizada en plataformas como Claude Code, Cursor o Codex, proporcionando reglas claras y ejemplos prácticos que ayudan a evitar errores comunes, como condiciones de carrera, bloqueos y problemas de rendimiento, haciendo que el código sea más seguro y mantenible.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/write-swift

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Escribir Swift

Respuesta Inicial

Cuando esta habilidad se invoque por primera vez sin una pregunta específica, responde únicamente con:

Estoy listo para ayudarte a escribir Swift moderno, de la forma en que el lenguaje quiere ser escrito.

No proporciones ninguna otra información hasta que el usuario haga una pregunta.

Cómo escribir Swift de la forma en que el lenguaje quiere ser escrito, actualizado hasta Swift 6.4.

Toolchain baseline: Swift 6.3 (versión actual a agosto de 2026). Todo aquí compila en 6.3 a menos que esté marcado con ⚠, lo que indica funcionalidades no lanzadas de Swift 6.4. Las guías de concurrencia asumen el modelo de Swift 6.2 — si el proyecto está en 6.1 o anterior, las reglas de la sección §3 sobre async y @concurrent no aplican.

El hilo conductor: Swift es un lenguaje de divulgación progresiva. Comienza con lo más simple, más estático y monohilo que funcione, y añade dinamismo — concurrencia, semántica de referencia, existenciales, punteros inseguros — solo donde puedas señalar la razón. Cada regla a continuación es una aplicación de esto.

Modela esta jerarquía de valores predeterminados. Baja un nivel solo con una razón que puedas enunciar:

NecesidadUsaBaja solo cuando
Datosstruct / enumnecesitas identidad, compartición o herencia
Abstraccióntipo concretotienes código repetido entre tipos
Polimorfismosome P (genérico)necesitas almacenamiento heterogéneo → any P
Ejecuciónactor principal, síncronola creación de perfiles muestra un bloqueo → async → @concurrent → actor
MemoriaArray, Stringla creación de perfiles muestra el costo → InlineArray, Span
SeguridadAPI seguraInteroperabilidad con C o un hot path medido → Unsafe*

1. Modela datos con tipos valor

Los tipos valor son la opción predeterminada en Swift, no un caso especial.

  • Por defecto, usa struct y enum. Usa class solo para identidad, estado mutable compartido, herencia o ciclo de vida de recursos. Una ventana, una conexión a base de datos, una entidad almacenada en un motor de renderizado — esos tienen identidad. Un Punto, una Bebida, un Material no.
  • let por defecto; var solo cuando mutas. Esta es la misma disciplina que some antes que any y valor antes que referencia: comienza estrecho, amplía con causa.
  • Un struct con una propiedad de tipo referencia mutable no es ni un valor ni una referencia. Las copias comparten el objeto; las mutaciones se filtran entre copias. O mantén el tipo referenciado inmutable, expón solo propiedades computadas que lo reenvíen, o conviértelo en una propiedad private almacenada detrás de copy-on-write.
  • Copy-on-write es cómo obtienes almacenamiento fuera de línea y semántica de valor. Envuelve una clase final en un struct y verifica isKnownUniquelyReferenced(&storage) antes de mutar; copia primero si no lo es. Así es exactamente como funcionan Array, String y Dictionary.
  • Los enums son la herramienta para "un conjunto fijo de cosas" y para estado mutuamente excluyente. Reemplazar un montón de propiedades almacenadas opcionales (isSharing, selectedRows, shareTarget) con un enum State hace que las combinaciones inválidas sean irrepresentables y que el cambio de estado sea atómico en lugar de una secuencia de escrituras de propiedades que puedes olvidar completar.
  • Componer valores produce un valor. Un struct cuyas propiedades almacenadas son todas tipos valor tiene semántica de valor gratis — lo que hace que deshacer, diffing y restauración de estado sean una única ruta de código en lugar de una por propiedad.
struct Material {                       // semántica de valor preservada
  var roughness: Double
  private var _texture: Texture         // una clase

  var color: Color {
    get { _texture.color }
    set {
      if !isKnownUniquelyReferenced(&_texture) { _texture = Texture(copying: _texture) }
      _texture.color = newValue
    }
  }
}

Tipos no copiables (~Copyable) expresan propiedad única: un descriptor de archivo, una transferencia bancaria, un recurso abierto. Suprimir la copia convierte "no debes ejecutar esto dos veces" de una aserción en un error de compilación, y hace que deinit en un struct sea significativo. Marca el método final como consuming para que el compilador demuestre que es el último uso. La propiedad de los parámetros se vuelve explícita: borrowing (solo lectura, el predeterminado), consuming (lo toma), inout/mutating (acceso de escritura temporal).


2. Errores y opcionales — haz visibles las rutas de fallo

El manejo de errores de Swift se basa en tres puntos: las fuentes de error están marcadas para que no puedan sorprenderte; los errores llevan suficiente contexto para actuar; y los errores recuperables son diferentes de los errores de programador.

  • Recuperable → throw. Error de programador → precondition/fatalError. Una llamada de red fallida mantiene el programa en ejecución. Un índice fuera de límites significa que el código está mal y debe detenerse antes de que el error se convierta en un problema de seguridad.
  • Los enums con valores asociados son los mejores tipos de error. case duplicateFriend(String) supera a case duplicateFriend — el contexto es la clave.
  • guard para condiciones de error, porque fuerza la ruta de salida. if let para el desempaquetado normal.
  • throws(TipoError) es para funciones internas, código genérico que reenvía errores y entornos restringidos donde empaquetar any Error es demasiado costoso. Para API pública, throws sin tipo preserva tu libertad de cambiar el tipo de error más adelante. Nota la unificación: throws es throws(any Error), y no lanzar es throws(Never) — que es lo que permite a map abstraer sobre ambos.
  • Forzar desempaquetado solo donde puedas enunciar el invariante, y prefiere un #require/precondition fallido con un mensaje sobre un ! desnudo.

3. Concurrencia: mantente en un solo hilo hasta que la creación de perfiles diga lo contrario

Esta es la sección que los agentes suelen entender mal con más frecuencia, porque el modelo cambió en Swift 6.2.

Comienza cada aplicación completamente en el hilo principal. El código de un solo hilo llega muy lejos, y la mayoría de las aplicaciones nunca necesitan salir de él.

La progresión, en orden. No te saltes pasos.

  1. Un solo hilo en el actor principal. Sin concurrencia alguna. Adecuado para la mayoría de las aplicaciones.
  2. async/await para ocultar latencia (red, disco). Aún sin concurrencia propia — APIs del SDK como URLSession.data(from:) descargan en tu nombre.
  3. @concurrent para mover tu trabajo pesado fuera del hilo principal — solo después de que Instruments muestre un bloqueo.
  4. actor para mover el estado fuera del actor principal — solo cuando demasiado estado del actor principal está forzando a las tareas a saltar constantemente de vuelta.

Activa primero la configuración de compilación correcta. Habilita Concurrencia Accesible en cada proyecto. Para módulos de aplicación y módulos orientados a la interfaz de usuario, también establece Aislamiento de Actor Predeterminado a MainActor — es el valor predeterminado para nuevos proyectos de aplicación en Xcode 26, y elimina la mayoría de tus anotaciones @MainActor. En un paquete: swiftSettings: [.defaultIsolation(MainActor.self)]. No establezcas main-actor-por-defecto para una biblioteca de propósito general — las bibliotecas deben enviar APIs nonisolated y dejar que los clientes decidan dónde se ejecuta el trabajo.

La regla que cambió

En Swift 6.2, marcar una función como async no la mueve fuera del actor actual. Se ejecuta donde fue llamada. Esto es lo que hace que "el código más natural de escribir" esté libre de condiciones de carrera por defecto.

  • @concurrent — siempre cambia al grupo de hilos concurrentes. Úsalo en tu trabajo pesado de CPU.
  • nonisolated — se ejecuta donde sea llamado. Este es el valor predeterminado correcto para APIs de bibliotecas, porque el llamante decide. nonisolated en un tipo hace que todos sus miembros sean nonisolated (Swift 6.1+).
  • Ninguno de los dos — permanece en el actor del llamante.
nonisolated struct PhotoProcessor {          // desacoplado del actor principal
  @concurrent                                // garantizado para ejecutarse en segundo plano
  func process(_ data: Data) async -> ProcessedPhoto {
    async let sticker = extractSticker(data)  // dos trabajos independientes, en paralelo
    async let colors  = extractColors(data)
    return await ProcessedPhoto(sticker: sticker, colors: colors)
  }
}
  • Crea un perfil antes de descargar trabajo. Usa Instruments (Time Profiler, Hangs). Si el código se puede hacer más rápido sin concurrencia, hazlo siempre primero. La concurrencia tiene un costo real: asignación de tareas, planificación y razonamiento.
  • No generes una tarea para trabajo trivial. Una tarea hija para leer un valor de UserDefaults cuesta más de lo que ahorra.
  • Una tarea por operación de principio a fin. El trabajo que debe ocurrir en orden va en una tarea; las operaciones independientes obtienen tareas separadas para que el runtime pueda intercalarlas.
  • await es un punto de suspensión, y rompe la atomicidad. El estado puede cambiar mientras estás suspendido, y puedes reanudarte en un hilo diferente. Vuelve a verificar las suposiciones después de cada await. Nunca mantengas un bloqueo a través de uno. Nunca confíes en el almacenamiento local de hilo a través de uno.

Reentrancia de actores

Los actores garantizan exclusión mutua, no transacciones. Entre dos awaits en el mismo actor, se ejecuta otro trabajo.

  • Muta el estado del actor en métodos síncronos. El código síncrono en un actor se ejecuta hasta completarse sin interrupciones — ese es tu límite de transacción.
  • Mantén los métodos async de los actores delgados, compuestos de operaciones transaccionales síncronas, y deja el actor en un estado consistente en cada await.
  • El error clásico: verificar caché → await descarga → escribir caché. Dos tareas fallan ambas, ambas descargan, la segunda sobrescribe la primera. Vuelve a verificar después del await, o desduplica el trabajo en curso.
  • Los actores no son FIFO. Ejecutan primero el trabajo de mayor prioridad, precisamente para evitar la inversión de prioridad. Si necesitas orden, usa una tarea (que se ejecuta de principio a fin) o un AsyncStream, no un actor.

4. Sendable y compartir datos

Sendable marca un tipo como seguro para compartir entre dominios de aislamiento. El compilador lo verifica en cada límite de tarea y actor.

  • Los tipos valor son Sendable cuando su almacenamiento lo es — inferido automáticamente para tipos no públicos. Los tipos públicos nunca obtienen capacidad de envío inferida: marcar un tipo público como Sendable es una promesa a tus clientes, por lo que Swift te obliga a escribirlo.
  • Los actores y las clases @MainActor son implícitamente Sendable, porque su estado está aislado.
  • La mayoría de las clases de modelo no deberían ser ni @MainActor ni Sendable. Mantenlas no Sendable a propósito — evita que la mitad del modelo se mute en el hilo principal mientras la otra mitad se muta en segundo plano. Si necesitan salir del actor principal, hazlas nonisolated, no Sendable.
  • Aún puedes enviar un objeto no Sendable entre dominios siempre que el emisor deje de usarlo. Realiza todas tus mutaciones antes de entregarlo; tocarlo después es el error.
  • Los cierres también capturan estado. Marca un tipo de función como @Sendable solo si realmente cruza dominios.
  • @unchecked Sendable es una promesa que el compilador no puede verificar. Resérvalo para tipos con sincronización interna real (un Mutex, un bloqueo). Lo mismo para nonisolated(unsafe) en un global — último recurso, no un silenciador de advertencias.

Cuando encuentres un error de condición de carrera, recorre esta lista:

  1. No lo compartas. Mueve el objeto compartido a un local para que cada trabajo concurrente tenga su propia instancia. (Esta es la solución para la gran mayoría de errores reales.)
  2. Conviértelo en un tipo valor Sendable, de modo que "compartir" sea realmente copiar.
  3. Aísla en un actor — el actor principal, o uno propio.
  4. Solo entonces recurre a Mutex/Atomic del módulo Synchronization (almacénalos en propiedades let), o @unchecked Sendable.

Las variables globales y estáticas son la fuente más común de errores. En orden de preferencia: conviértela en let; ponla en @MainActor; envuélvela en un Mutex; nonisolated(unsafe). Nota: los globales en Swift se inicializan perezosamente y atómicamente — a diferencia de C.

Adaptando APIs de callback antiguas: anota los protocolos delegados con @MainActor si los posees. Si no, marca el método como nonisolated y usa MainActor.assumeIsolated { } — afirma en lugar de saltar, por lo que atrapa ruidosamente en lugar de competir silenciosamente. @preconcurrency en la conformidad es la abreviatura para lo mismo. Usa @preconcurrency import para silenciar temporalmente las advertencias de sendability de un módulo que no ha migrado; las advertencias vuelven — correctamente — una vez que lo hace.


5. Concurrencia estructurada

Prefiere siempre las tareas estructuradas.

Las tareas estructuradas (async let, grupos de tareas) tienen un ámbito como las variables locales: no pueden sobrevivir al bloque, se esperan automáticamente, y heredan cancelación, prioridad y valores locales de tarea a través del árbol de tareas. Las tareas no estructuradas (Task { }, Task.detached) no te dan nada de eso automáticamente.

  • async let para un número fijo, estáticamente conocido, de hijos concurrentes.
  • withTaskGroup cuando el número es dinámico. Los grupos de tareas se ajustan a AsyncSequence — itera los resultados a medida que llegan. Usa withDiscardingTaskGroup cuando los hijos no devuelvan nada: libera los recursos de cada hijo inmediatamente y cancela los hermanos en el primer error.
  • Task { } solo cuando la vida útil del trabajo no encaje en un ámbito — reaccionando a un callback delegado, un toque de botón, la aparición de una vista. Hereda el aislamiento del actor y la prioridad; debes gestionar la cancelación tú mismo.
  • Task.detached casi nunca. No hereda nada — ni aislamiento, ni prioridad, ni locales de tarea. Si necesitas una raíz separada, pon un grupo de tareas dentro de ella en lugar de separar repetidamente.

La cancelación es cooperativa. Cancelar establece una bandera; no detiene nada. Verifica Task.isCancelled o try Task.checkCancellation() antes de comenzar trabajo costoso, y también en ayudantes síncronos. Para el trabajo que está suspendido en lugar de ejecutándose (el next() de un AsyncSequence), usa withTaskCancellationHandler — y recuerda que el manejador se ejecuta inmediatamente y concurrentemente con el cuerpo, por lo que el estado que toca necesita sincronización real (un atómico o un bloqueo, no un actor — no puedes garantizar el orden en un actor).

Limita tu concurrencia. No distribuyas un hijo por elemento sobre una lista sin límites. Inicia N hijos, luego agrega un

…

[truncado para traducción]

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

Skills relacionados