🧠 DeepSeek Skills

8 skills de ingeniería senior + 4 skills de diseño y creativas para DeepSeek R1

Protocolo de activación selectiva que maximiza el rendimiento del modelo sin saturar su ventana de contexto.

¿Qué es esto?

Un set de 12 skills profundas y detalladas que transforman a DeepSeek R1 en un agente de ingeniería senior con capacidades de diseño UX/UI, copywriting persuasivo y animaciones web. Cada skill es un protocolo estructurado por fases, con checklists, ejemplos reales, y anti-patrones documentados.

El problema: las skills son extensas (~10-32 KB cada una) y el contexto de R1 es limitado.

La solución: un AGENTS.md con un Protocolo de Activación Selectiva (PAS) que le indica al modelo cómo clasificar cada tarea y cargar solo las 2-3 skills relevantes, aprovechando su potencia completa sin desperdiciar tokens.

🆕 Update v2.1: Skills de Copy & Animaciones

El agente ahora escribe copy que vende y anima interfaces como un senior.

Dos nuevas skills se suman al paquete:

| ID | Skill | Qué hace | |---|---|---| | CPY | deepseek-copy 🆕 | Protocolo de copywriting persuasivo y SEO. No describe el producto — lo vende. Cubre análisis de contexto de venta, niveles de consciencia del usuario, headlines que detienen el scroll, features → beneficios, CTAs que convierten, estructura AIDA, SEO de copy (no técnico), meta tags, FAQ estratégicas, tono y voz derivados del usuario, y un checklist final de copy antes de publicar. | | ANM | deepseek-animations 🆕 | Protocolo de animaciones web god-tier. Cubre jerarquía de herramientas (CSS → Motion → GSAP), propiedades GPU-safe obligatorias, timing y easing de calidad, scroll animations con Lenis + GSAP ScrollTrigger, text reveals, spring physics, staggers, clip-path reveals, micro-interacciones magnéticas, page transitions, y un checklist de rendimiento + accesibilidad. |

Estas skills se ofrecen junto con las de diseño durante la instalación interactiva.

🔄 Update v2.0: Nueva estructura + CLI mejorado

Algunas herramientas agentic (como OpenCode) no detectaban las skills porque estaban demasiado anidadas. Simplificamos la estructura de carpetas y actualizamos el CLI para que todo funcione en cualquier motor.

- .agents/.skills/skills/<skill>/SKILL.md   ← 3 niveles, no detectado
+ .agents/skills/<skill>/SKILL.md            ← 2 niveles, compatible

Si ya tenías la v1.x instalada, corré npx deepseek-skills restructure para migrar automáticamente.

Skills de Diseño UX/UI

El agente ahora puede diseñar interfaces al mismo nivel que escribe código.

| ID | Skill | Qué hace | |---|---|---| | CLR | deepseek-color | Razonamiento cromático basado en el contexto del producto. No elige colores porque "se ven bien" — los deriva del sector, audiencia, y emociones que el producto necesita comunicar. Cubre psicología del color, sistemas de color con roles semánticos, integración con Tailwind/shadcn, y validación de contraste WCAG. | | DSN | deepseek-design | Protocolo de diseño UI/UX perfeccionista y mobile-first. Garantiza que cada componente funcione en 375px antes de escalar a desktop. Cubre uso correcto de shadcn/ui, tokens semánticos, responsive obligatorio, accesibilidad, micro-interacciones, estados vacíos, skeletons, y un checklist de calidad final. |

Instalación

npx deepseek-skills

Eso es todo. El CLI interactivo te guía paso a paso:

1. Se copian AGENTS.md y .agents/skills/ a tu proyecto
2. Te pregunta si tu proyecto necesita las skills de diseño, copy y animaciones
3. Si decís que sí, se incluyen las 4 skills opcionales (CLR, DSN, CPY, ANM)
4. Si decís que no, se instalan solo las 8 skills de ingeniería

| Archivo | Descripción | |---|---| | AGENTS.md | Directiva principal del agente — protocolo de activación selectiva | | .agents/skills/ | Las skills seleccionadas (8 core + 4 diseño/creativas opcionales) |

Opciones

npx deepseek-skills                # Instalar en el directorio actual
npx deepseek-skills --force        # Sobrescribir si ya existen
npx deepseek-skills add            # Añadir skills sin borrar las existentes
npx deepseek-skills restructure    # Migrar de v1.x a v2.x
npx deepseek-skills list           # Listar las skills con tamaños
npx deepseek-skills --help         # Ver ayuda

Alternativa (desde GitHub directo):

npx github:gonzi-stack/deepseek-skills

Skills incluidas

Skills de ingeniería (core)

| ID | Skill | Dominio | Cuándo se activa | |---|---|---|---| | RSN | deepseek-reasoning | Razonamiento | Siempre — obligatoria en toda tarea | | CQL | deepseek-code-quality | Calidad de código | Al escribir o modificar código | | ARC | deepseek-architect | Arquitectura | Creación compleja o refactoring | | CTX | deepseek-context | Contexto de proyecto | Para entender stack y convenciones | | DBG | deepseek-debug | Debugging | Al corregir errores o bugs | | PRF | deepseek-performance | Performance | Al optimizar o investigar lentitud | | REV | deepseek-review | Code review | Al revisar código propio o ajeno | | TST | deepseek-testing | Testing | Al escribir o diseñar tests |

Skills de diseño y creativas (opcionales)

| ID | Skill | Dominio | Cuándo se activa | |---|---|---|---| | CLR | deepseek-color | Razonamiento cromático | Al definir paletas de color para una interfaz o marca | | DSN | deepseek-design | UI/UX perfeccionista | Al crear o modificar componentes visuales, páginas o layouts | | CPY | deepseek-copy 🆕 | Copywriting y SEO | Al escribir cualquier texto visible al usuario: headlines, CTAs, onboarding, pricing | | ANM | deepseek-animations 🆕 | Animaciones web | Al implementar animaciones, transiciones, scroll effects, o micro-interacciones |

Cómo funciona

El problema

DeepSeek R1 tiene un contexto limitado. Cargar las 12 skills (~200 KB total) consume una parte significativa de la ventana disponible, dejando poco espacio para el código del proyecto.

La solución: Activación Selectiva

El AGENTS.md define 10 categorías de tareas. Cada categoría activa solo las skills que necesita:

BUILD   → RSN + CQL + (ARC si es multi-capa)
FIX     → RSN + DBG + (CQL si el fix es significativo)
EVOLVE  → RSN + CQL + ARC
PERF    → RSN + PRF + (DBG si parece un bug)
REVIEW  → RSN + REV
TEST    → RSN + TST + (CQL para validar)
CONTEXT → RSN + CTX
PLAN    → RSN + ARC
DESIGN  → RSN + CQL + DSN + (CLR si hay color) + (ANM si hay animaciones)
COPY    → RSN + CPY + (DSN si es parte de una interfaz)

El modelo clasifica la tarea en thinking mode, declara qué skills activa, las lee completas, y las ejecuta a fondo. Máxima potencia, mínimo desperdicio.

Flujo del agente

Tarea del usuario
       │
       ▼
┌─────────────────┐
│  Clasificar     │  ← ¿BUILD? ¿FIX? ¿DESIGN? ¿COPY? ...
│  la tarea       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Activar skills │  ← Solo 2-3 de las 12
│  necesarias     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Leer skills    │  ← Completas, sin omitir
│  activadas      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Ejecutar       │  ← Siguiendo los protocolos
│  la tarea       │     de cada skill activa
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Verificar      │  ← Checklists de cada skill
│  y reportar     │
└─────────────────┘

Configuración

Paso 1 — Instalar

npx deepseek-skills

Paso 2 — Configurar DeepSeek R1

Agregá el contenido de AGENTS.md como instrucción del sistema o custom instructions de DeepSeek R1. El modelo leerá AGENTS.md al inicio de cada conversación y seguirá el protocolo automáticamente.

Paso 3 — (Opcional) Contexto de proyecto

Para mejores resultados, creá un DEEPSEEK_CONTEXT.md en la raíz de tu proyecto usando la plantilla de la skill CTX. Este archivo le dice al modelo las convenciones específicas de tu proyecto: stack, naming, patrones prohibidos, etc.

Paso 4 — Gitignore

Decidí si querés versionar las skills:

# Opción A: Ignorar (cada dev instala con npx)
.agents/

# Opción B: Versionar (compartir con el equipo)
# No agregar .agents/ al .gitignore

Estructura del AGENTS.md

| Sección | Contenido | |---|---| | §0 | Identidad del agente y directivas base | | §1 | Mapa de las 12 skills (8 core + 4 diseño/creativas) | | §2 | Taxonomía: IDs, dominios, dependencias entre skills | | §3 | Protocolo de Activación Selectiva (PAS) — el core | | §4 | Resumen de las fases de razonamiento obligatorias | | §5 | Reglas globales: mínima intervención, prohibiciones | | §6 | Flujo de trabajo estándar (diagrama) | | §7 | Protocolo multi-tarea | | §8 | Integración con contexto de proyecto | | §9 | Zona de auto-modificación (editable por el modelo bajo orden del usuario) |

Qué cubre cada skill

RSN — Reasoning (obligatoria)

Protocolo de 6 fases que el modelo ejecuta antes de tocar código: intake → mapping → blast radius → plan → execution → verification. Previene el patrón "adivinar → cambiar → rezar".

CQL — Code Quality

Estándares de tipos seguros, funciones bien diseñadas, queries seguras, seguridad, error handling, y componentes UI. Con ejemplos ✅/❌ para cada regla.

ARC — Architect

Dos fases: (A) diseño arquitectónico para creación compleja — límites del sistema, capas, contratos, puntos de falla; (B) evolución segura de código existente — refactoring, optimización, extensión sin romper.

CTX — Context

Plantilla para documentar el proyecto: stack, estructura, convenciones, patrones prohibidos/requeridos, decisiones ya tomadas. Convierte las skills universales en skills específicas para tu proyecto.

DBG — Debug

Protocolo de diagnóstico: leer error completo → clasificar tipo → trazar origen → hipótesis verificable → fix mínimo. Incluye patrones para cada tipo de error (null, tipos, DB, imports, auth).

PRF — Performance

Medir → identificar bottleneck real → optimizar → medir de nuevo. Cubre N+1 queries, optimización de queries, caching, memory leaks, concurrencia, y documentación de optimizaciones.

REV — Review

Revisión por capas: corrección → seguridad → contratos → mantenibilidad → consistencia → performance. Clasificación de observaciones en 4 niveles (bloqueante/importante/sugerencia/nitpick).

TST — Testing

Qué testear y qué no, patrón AAA, casos edge obligatorios, mocking correcto, tests unitarios vs integración, y detección de tests que dan falsa seguridad.

CLR — Color

Razonamiento cromático derivado del contexto del producto. Cubre las 5 preguntas de contexto, psicología del color por sector (EdTech, Salud, Fintech, SaaS, E-commerce, Gaming), construcción de sistemas de color con roles semánticos (brand, neutral, success, warning, error), regla 60-30-10, dark mode correcto, integración con Tailwind y shadcn, y validación de contraste WCAG AA/AAA.

DSN — Design

Protocolo de diseño UI/UX completo con enfoque mobile-first obligatorio. Define jerarquía visual antes de implementar, uso correcto de cada componente de shadcn/ui (con tablas de referencia), patrones de layout responsive (dashboard, grids, stack/row), todos los estados de UX (loading, empty, error, hover, focus, disabled), micro-interacciones con propósito, accesibilidad no opcional (touch targets 44px+, ARIA, focus ring), y un checklist de calidad de 30+ puntos.

CPY — Copy 🆕

Protocolo de copywriting persuasivo y SEO. No describe el producto — lo vende. Cubre análisis de contexto de venta (6 preguntas obligatorias), niveles de consciencia del usuario (1-5), fórmulas de headline probadas, features → beneficios con el método "y eso qué significa x3", CTAs en primera persona, estructura AIDA para landing pages, SEO de copy (headings, meta tags, FAQ estratégicas), tono derivado del usuario, y un checklist de copy+SEO antes de publicar.

ANM — Animations 🆕

Protocolo de animaciones web god-tier. Rendimiento primero: solo animar transform y opacity (GPU compositor thread). Cubre la jerarquía de herramientas (CSS → Motion → GSAP → WebGL), tokens de duración (100ms–600ms), easings custom (cubic-bezier/spring physics), staggers para listas, text reveals, clip-path reveals, scroll-scrub con GSAP ScrollTrigger, setup Lenis + GSAP, horizontal scroll con pin, micro-interacciones magnéticas, page transitions en Next.js, prefers-reduced-motion obligatorio, y un checklist de rendimiento + accesibilidad.

FAQ

¿Funciona con otros modelos además de DeepSeek R1?

Las skills están optimizadas para el modo thinking de DeepSeek R1, pero los principios son universales. Podés adaptar el AGENTS.md para otros modelos con capacidad agentic.

¿Puedo agregar mis propias skills?

Sí. Creá un nuevo SKILL.md en .agents/skills/tu-skill/ y registrala en la tabla de §2 del AGENTS.md. El modelo puede hacerlo por vos si se lo ordenas (§9.3).

¿Las skills son para un stack específico?

No. Son universales. Los ejemplos usan TypeScript pero los principios aplican a cualquier lenguaje y framework. Las skills de diseño y creativas (CLR, DSN, CPY, ANM) incluyen integración con Tailwind CSS, shadcn/ui, Framer Motion y GSAP pero el razonamiento aplica a cualquier stack. Para convenciones específicas de tu stack, usá DEEPSEEK_CONTEXT.md.

¿Puedo modificar las skills?

Son tuyas. Modificalas libremente. Si encontrás mejoras, abrí un PR.

¿Las skills de diseño y creativas son obligatorias?

No. Durante la instalación, el CLI te pregunta si tu proyecto necesita skills de diseño, copy y animaciones. Si tu proyecto es puramente backend o infraestructura, simplemente respondé "No" y se instalan solo las 8 skills de ingeniería.

⚠️ Breaking Change: Reestructuración de directorios (v1.x → v2.x)

Cambio: .agents/.skills/skills/ → .agents/skills/

¿Qué cambió?

La estructura de directorio de las skills pasó de 3 niveles de anidación a 2 niveles:

- .agents/.skills/skills/<skill-name>/SKILL.md
+ .agents/skills/<skill-name>/SKILL.md

¿Por qué?

Motores agentic como OpenCode y otros no resuelven correctamente rutas con más de 2 niveles de profundidad dentro de .agents/. El nivel intermedio .skills/ no aportaba valor semántico y impedía que las skills fueran detectadas automáticamente por estos motores.

Este cambio garantiza compatibilidad con el mayor número de herramientas agentic posible.

¿Qué hacer si ya tenías la versión anterior?

# Opción recomendada: usar el comando de migración
npx deepseek-skills restructure

# Alternativa: reinstalar desde cero
npx deepseek-skills --force

El comando restructure detecta la estructura v1.x, migra las skills automáticamente, y te pregunta si querés actualizar el AGENTS.md a la versión compatible.

Contribuir

1. Forkeá el repo
2. Creá una rama: git checkout -b mi-mejora
3. Hacé tus cambios en las skills o el CLI
4. Abrí un Pull Request

Las skills deben seguir el formato existente: frontmatter → principio fundamental → fases numeradas → checklist final.

Licencia

MIT