specleap-framework 2.2.0 → 2.3.0

package/.commands/compliance.md

@@ -9,7 +9,7 @@
 ## Qué dimensiones se auditan
 
 1. **Version** — El `package.json.version` coincide con el último tag de git.
-2. **Skills** — El número de carpetas en `~/.skills/` coincide con los counters declarados en `CLAUDE.md`, `README.md` y `.quality/baselines/baseline.json`.
+2. **Skills** — El número de carpetas en `~/.claude/skills/` (o `~/.skills/` si es instalación legacy) coincide con los counters declarados en `CLAUDE.md`, `README.md` y `.quality/baselines/baseline.json`.
 3. **i18n** — Todas las claves de `.specleap/i18n/es.json` existen en `.specleap/i18n/en.json` y viceversa.
 4. **Hooks** — `.claude/hooks/spec-guard.sh` existe, tiene shebang, es ejecutable y está referenciado en `.claude/settings.json.template`.
 5. **Baseline** — `.quality/baselines/baseline.json.repo_snapshot` no difiere >20% de los counters reales del repo.

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-05-23
+
+### Changed (BREAKING)
+
+- **Lista de Agent Skills reducida de 34 a 20**, curada para el stack real de SpecLeap (Laravel + React + TypeScript + PostgreSQL + shadcn). Cada skill viene de un repo público mantenido por su autor, sin invenciones. Detalle:
+  - **Eliminados** (14 skills que no encajan con el público objetivo): `python-pro`, `flutter-expert`, `react-native-expert`, `algorithmic-art`, `canvas-design`, `pdf`, `skill-creator`, `terraform-engineer`, `monitoring-expert`, `cloud-architect`, `devops-engineer`, `architecture-designer`, `agent-browser`, `playwright-expert`, `test-master`, `debugging-wizard`, `code-documenter`, `vercel-composition-patterns`.
+  - **Añadidos** (4 skills nuevos que estaban prometidos pero nunca se instalaban): `supabase-postgres-best-practices` (supabase/agent-skills), `vercel-react-best-practices` (vercel-labs/agent-skills, antes path obsoleto), `shadcn` (shadcn-ui/ui), `extract-design-system` (arvindrk/extract-design-system).
+  - **Mantenidos** (16 skills): `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `test-driven-development`, `laravel-specialist`, `api-designer`, `database-optimizer`, `react-expert`, `typescript-pro`, `frontend-design`, `web-design-guidelines`, `security-reviewer`, `gdpr-dsgvo-expert`, `code-reviewer`, `brainstorming`.
+- **Validado end-to-end**: `bash scripts/install-skills.sh` ejecutado contra sandbox limpio descarga los 20 skills sin fallos.
+
+### Fixed
+
+- **CLAUDE.md ya no contiene skills "fantasma"**. Antes documentaba 16 skills que NO existían en ningún repo público (`backend-api-security`, `tailwind-design-system`, `shadcn-ui`, `responsive-design`, `code-review-excellence`, `api-design-principles`, `error-handling-patterns`, `postgresql-table-design`, `sast-configuration`, `stride-analysis-patterns`, `security-requirement-extraction`, `frontend-mobile-security`, `vercel-react-best-practices` con nombre incorrecto, `laravel-standards`, `react-standards`, `frontend-standards`). Esto causaba que el modelo "alucinara" nombres de skills cuando el contexto las invocaba. Ahora CLAUDE.md menciona SÓLO los 20 realmente instalados.
+- **Path de `gdpr-dsgvo-expert` corregido** en `install-skills.sh`. El path real en `alirezarezvani/claude-skills` es `ra-qm-team/skills/gdpr-dsgvo-expert`, no `ra-qm-team/gdpr-dsgvo-expert`. Sin este fix, el skill no se instalaba.
+
+### Documentation
+
+- `CLAUDE.md`, `README.md`, `SETUP.md`, `scripts/README.md` reescritos para reflejar los 20 skills curados con sus categorías reales (Core/Quality 5, Backend 4, Frontend 4, Diseño 3, Seguridad 2, Process 2).
+- LP (`specleap.com`) actualizada: hero "20 Agent Skills curados", desglose por 6 categorías con los nombres exactos de skills reales, sin TIER 1/TIER 2 (innecesario al curar la lista). Tanto ES como EN.
+
+## [2.2.1] - 2026-05-22
+
+### Fixed
+
+- **Bug crítico: los Agent Skills no se cargaban en Claude Code.** `scripts/install-skills.sh` instalaba en `$HOME/.skills/`, que es un path obsoleto que Claude Code dejó de monitorizar. El path canónico que auto-descubre Claude Code es `$HOME/.claude/skills/`. Resultado del bug: todos los usuarios de SpecLeap (incluido Styng) tenían los 34 Agent Skills instalados pero **invisibles** para el runtime — ninguno se activaba por contexto. Detectado tras consultar la doc oficial de Claude Code: solo lee skills de `~/.claude/skills/` (user-level) y `.claude/skills/` (project-level).
+  - **Fix**: `scripts/install-skills.sh` ahora instala en `$HOME/.claude/skills/`. Si detecta una instalación legacy en `$HOME/.skills/` (de versiones ≤ 2.2.0), crea un symlink desde el path canónico apuntando al legacy. Así los usuarios existentes no tienen que mover archivos ni reinstalar — solo ejecutar `bash scripts/install-skills.sh` una vez para que el symlink se cree.
+  - **Migración manual** (alternativa al symlink automático): `ln -s ~/.skills ~/.claude/skills`.
+  - **Verificación**: tras el fix, decirle "Hola" a Claude Code dentro del proyecto y pedir algo que dispare un skill conocido (ej: "qué debo verificar antes de cerrar un ticket") debe activar `verification-before-completion`.
+
+### Changed
+
+- **`CLAUDE.md`, `README.md`, `SETUP.md`, `scripts/README.md`, `.commands/compliance.md`** actualizados para reflejar el path canónico `~/.claude/skills/` y documentar la compatibilidad con instalaciones legacy.
+
 ## [2.2.0] - 2026-05-02
 
 ### Changed

package/CLAUDE.md

@@ -172,7 +172,17 @@ Read and follow these standards for ALL code:
 
 ## Agent Skills (Progressive Disclosure)
 
-If **20 Agent Skills TIER 1** are installed (`~/.skills/`), they activate automatically:
+SpecLeap installs **20 curated Agent Skills** in `~/.claude/skills/` (the canonical path Claude Code auto-discovers). They activate automatically when the conversation context matches each skill's `description` frontmatter.
+
+**Source repos:**
+- `obra/superpowers` — quality/process skills
+- `jeffallan/claude-skills` — stack specialists
+- `anthropics/skills` — design
+- `vercel-labs/agent-skills` — React/Next/web
+- `shadcn-ui/ui` — shadcn components
+- `supabase/agent-skills` — PostgreSQL
+- `arvindrk/extract-design-system` — design-system extraction
+- `alirezarezvani/claude-skills` — GDPR
 
 ### Activation Triggers
 
@@ -182,83 +192,69 @@ Skills load knowledge **only when needed** based on context:
 User: "Crear endpoint POST /api/products con validación"
 
 Auto-activates:
-  ✓ api-design-principles
-  ✓ backend-api-security
-  ✓ laravel-specialist
   ✓ verification-before-completion
-  ✓ postgresql-table-design
+  ✓ laravel-specialist
+  ✓ api-designer
+  ✓ database-optimizer
+  ✓ security-reviewer
 ```
 
 ### Critical Skills
 
 #### verification-before-completion ⭐ **MANDATORY**
 
-**Before creating ANY function, class, or component:**
-1. **SEARCH** existing code for similar functionality
-2. **READ** conventions.md for naming patterns
-3. **VERIFY** utilities/services don't already exist
-4. **ONLY THEN** create if nothing similar exists
-
-**Anti-Pattern (NEVER DO):**
-- ❌ Create `UserHelper` when `UserService` exists
-- ❌ Create `formatPrice()` when `formatCurrency()` exists
-- ❌ Create new HTTP client when axios instance exists
-
-#### code-review-excellence
-
-Before committing, verify:
-- No duplicated code
-- Follows conventions.md
-- Tests coverage >= 90%
-- Security best practices
-
-#### backend-api-security
-
-For all endpoints:
-- Server-side validation
-- Rate limiting
-- CSRF protection
-- SQL injection prevention
-- XSS sanitization
-
-#### frontend-design + web-design-guidelines
-
-For all components:
-- Professional design (Vercel/Linear style)
-- Consistent spacing (4px grid)
-- Responsive mobile-first
-- Micro-interactions
-- Design system coherence
-
-### Skill Categories
-
-**🔒 Security (5):**
-- sast-configuration
-- stride-analysis-patterns
-- security-requirement-extraction
-- backend-api-security
-- frontend-mobile-security
-
-**🔄 Consistency (3):**
+**Before claiming work is complete, fixed, or passing:**
+1. **RUN** the verification commands fresh (tests, lint, type-check, manual curl, etc.).
+2. **CONFIRM** the output is what you expected — paste the evidence.
+3. **ONLY THEN** mark the work as done, commit, or open a PR.
+
+**Iron law:** *"No completion claims without fresh verification evidence."*
+
+#### systematic-debugging
+
+When a bug shows up, follow the loop: reproduce → isolate → form hypothesis → test hypothesis → fix → verify. No guessing, no "this should work".
+
+#### test-driven-development
+
+Write the failing test first, then the minimal code to make it pass, then refactor. Coverage target ≥ 90%.
+
+#### code-reviewer + requesting-code-review + receiving-code-review
+
+The three skills cover the full review cycle: self-review before requesting review, asking for review with focus areas, and reacting to review feedback constructively.
+
+### Skill Catalogue (20)
+
+**🔄 Core / Quality (5):**
 - verification-before-completion ⭐
-- code-review-excellence
 - systematic-debugging
+- requesting-code-review
+- receiving-code-review
+- test-driven-development
 
-**🎨 Design/Frontend (6):**
-- web-design-guidelines
-- frontend-design
-- ui-ux-pro-max
-- tailwind-design-system
-- shadcn-ui
-- responsive-design
-
-**🛠️ Backend/Dev (6):**
+**🛠️ Backend (4) — Laravel + PostgreSQL:**
 - laravel-specialist
+- api-designer
+- database-optimizer
+- supabase-postgres-best-practices
+
+**⚛️ Frontend (4) — React + TypeScript + shadcn:**
+- react-expert
+- typescript-pro
 - vercel-react-best-practices
-- test-driven-development
-- api-design-principles
-- postgresql-table-design
-- error-handling-patterns
+- shadcn
+
+**🎨 Design (3):**
+- frontend-design
+- web-design-guidelines
+- extract-design-system
+
+**🔒 Security (2):**
+- security-reviewer
+- gdpr-dsgvo-expert
+
+**🔁 Process (2):**
+- code-reviewer
+- brainstorming
 
 **See:** [SETUP.md](SETUP.md) for installation details.
 

package/README.md

@@ -11,14 +11,14 @@
   <a href="https://www.npmjs.com/package/specleap-framework"><img src="https://img.shields.io/npm/v/specleap-framework.svg?color=22c55e&label=npm" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/agents-3-6366f1" alt="3 agents" />
   <img src="https://img.shields.io/badge/commands-10-f97316" alt="10 commands" />
-  <img src="https://img.shields.io/badge/skills-34-22c55e" alt="34 Agent Skills" />
+  <img src="https://img.shields.io/badge/skills-20-22c55e" alt="20 Agent Skills" />
   <img src="https://img.shields.io/badge/hooks-1-ec4899" alt="1 hook" />
   <img src="https://img.shields.io/badge/rules-4-eab308" alt="4 rules" />
   <img src="https://img.shields.io/badge/built%20for-Claude%20Code-000000" alt="Built for Claude Code" />
   <a href="https://ko-fi.com/specleap"><img src="https://img.shields.io/badge/Ko--fi-Support%20SpecLeap-FF5E5B?logo=ko-fi&logoColor=white" alt="Ko-fi" /></a>
 </p>
 
-SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 34 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
+SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 20 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
 
 **Versión actual:** 2.1.14 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
@@ -96,7 +96,7 @@ bash setup.sh
 | **Trae los archivos** | npm los descarga | git los clona del repo |
 | **Ideal para** | Empezar rápido, no recordar el flujo de git | Devs que ya manejan git fluidamente |
 
-A partir de aquí ambos flows son idénticos: el `setup.sh` solicita los tokens de GitHub y Asana, instala los 34 Agent Skills en `~/.skills/` y genera la estructura base. Tiempo total: 10 a 15 minutos.
+A partir de aquí ambos flows son idénticos: el `setup.sh` solicita los tokens de GitHub y Asana, instala los 20 Agent Skills en `~/.claude/skills/` y genera la estructura base. Tiempo total: 10 a 15 minutos.
 
 **Requisitos previos:**
 
@@ -139,30 +139,18 @@ El prefijo `/` está reservado por Claude Code para sus propios slash commands (
 
 ## Agent Skills
 
-SpecLeap instala **34 Agent Skills profesionales** en `~/.skills/` durante el setup. Se activan automáticamente cuando el contexto lo requiere.
-
-### TIER 1 — 20 skills base
-
-| Categoría | Skills |
-|-----------|--------|
-| Consistencia | `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `code-reviewer`, `debugging-wizard` |
-| Backend | `laravel-specialist`, `api-designer`, `database-optimizer`, `python-pro`, `react-expert`, `typescript-pro` |
-| Diseño | `frontend-design`, `canvas-design`, `algorithmic-art`, `skill-creator` |
-| DevOps | `devops-engineer`, `cloud-architect`, `architecture-designer` |
-| Testing | `test-driven-development` |
-
-### TIER 2 — 14 skills añadidas en v2.1
+SpecLeap instala **20 Agent Skills curados** en `~/.claude/skills/` (path canónico que Claude Code auto-descubre) durante el setup. Se activan automáticamente cuando el contexto lo requiere. Cada skill viene de un repo público mantenido por su autor original.
 
 | Categoría | Skills |
 |-----------|--------|
-| Frontend web | `web-design-guidelines`, `vercel-composition-patterns`, `agent-browser` |
-| Mobile | `react-native-expert`, `flutter-expert` |
-| Testing avanzado | `playwright-expert`, `test-master` |
+| Core / Quality | `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `test-driven-development` |
+| Backend (Laravel + PostgreSQL) | `laravel-specialist`, `api-designer`, `database-optimizer`, `supabase-postgres-best-practices` |
+| Frontend (React + TS + shadcn) | `react-expert`, `typescript-pro`, `vercel-react-best-practices`, `shadcn` |
+| Diseño | `frontend-design`, `web-design-guidelines`, `extract-design-system` |
 | Seguridad | `security-reviewer`, `gdpr-dsgvo-expert` |
-| Infraestructura | `terraform-engineer`, `monitoring-expert` |
-| Otras | `brainstorming`, `code-documenter`, `pdf` |
+| Process | `code-reviewer`, `brainstorming` |
 
-La skill `verification-before-completion` obliga al asistente a verificar si el código solicitado ya existe antes de crearlo, evitando duplicación de lógica.
+La skill `verification-before-completion` aplica el principio *"sin evidencia fresca no se cierra"*: el asistente debe ejecutar verificaciones reales (tests, lint, curl) y pegar la salida antes de marcar nada como completado.
 
 ---
 

package/SETUP.md

@@ -69,7 +69,7 @@ bash setup.sh
 **Qué hace `setup.sh`:**
 - Selecciona idioma (Español/English)
 - Pide tokens GitHub y Asana
-- Instala los 34 Agent Skills en `~/.skills/`
+- Instala los 20 Agent Skills curados en `~/.claude/skills/` (path canónico que Claude Code auto-descubre)
 - Configura CodeRabbit
 - Crea estructura base + archivos de configuración
 
@@ -143,7 +143,7 @@ Alternativa al workflow conversacional. Para equipos que requieren propuestas fo
 **⚠️ IMPORTANTE:** Estos NO son opcionales. SpecLeap requiere estos componentes para SDD profesional:
 - **Asana** — Gestión de backlog (comando `planificar`)
 - **CodeRabbit** — Code review automático en PRs
-- **Agent Skills** — Best practices automáticas (20 skills TIER 1)
+- **Agent Skills** — Best practices automáticas (20 skills curados)
 - **Git Hooks** — Validación pre-commit local
 - **GitHub** — Control de versiones y colaboración
 
@@ -223,7 +223,7 @@ git push origin main
 
 ---
 
-### 3. Agent Skills (34 profesionales)
+### 3. Agent Skills (20 curados)
 
 Extensiones para Claude/Cursor que aplican best practices automáticamente al contexto de cada tarea.
 
@@ -233,21 +233,19 @@ Instalación:
 bash scripts/install-skills.sh
 ```
 
-Se descargan e instalan 34 skills en `~/.skills/` (20 TIER 1 más 14 TIER 2):
+Se descargan e instalan 20 skills curados en `~/.claude/skills/` (path canónico que Claude Code auto-descubre — desde v2.2.1; instalaciones legacy en `~/.skills/` siguen funcionando vía symlink automático). La lista está enfocada en el stack real de SpecLeap (Laravel + React + TypeScript + PostgreSQL):
 
-- **Consistencia (6):** `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `code-reviewer`, `debugging-wizard`
-- **Backend (6):** `laravel-specialist`, `api-designer`, `database-optimizer`, `python-pro`, `react-expert`, `typescript-pro`
-- **Diseño y frontend (7):** `frontend-design`, `canvas-design`, `algorithmic-art`, `skill-creator`, `web-design-guidelines`, `vercel-composition-patterns`, `agent-browser`
-- **DevOps (5):** `devops-engineer`, `cloud-architect`, `architecture-designer`, `terraform-engineer`, `monitoring-expert`
-- **Mobile (2):** `react-native-expert`, `flutter-expert`
-- **Testing (3):** `test-driven-development`, `playwright-expert`, `test-master`
+- **Core / Quality (5):** `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `test-driven-development`
+- **Backend (4) — Laravel + PostgreSQL:** `laravel-specialist`, `api-designer`, `database-optimizer`, `supabase-postgres-best-practices`
+- **Frontend (4) — React + TS + shadcn:** `react-expert`, `typescript-pro`, `vercel-react-best-practices`, `shadcn`
+- **Diseño (3):** `frontend-design`, `web-design-guidelines`, `extract-design-system`
 - **Seguridad (2):** `security-reviewer`, `gdpr-dsgvo-expert`
-- **Documentación y otros (3):** `code-documenter`, `brainstorming`, `pdf`
+- **Process (2):** `code-reviewer`, `brainstorming`
 
 Verificar lo instalado:
 
 ```bash
-ls ~/.skills/
+ls ~/.claude/skills/
 ```
 
 ---
@@ -393,7 +391,7 @@ export PATH="$PATH:$(pwd)/openspec/cli"
 
 1. Verifica instalación:
 ```bash
-ls -la ~/.skills/
+ls -la ~/.claude/skills/
 ```
 
 2. Reinicia tu IDE (VSCode/Cursor/JetBrains)
@@ -439,7 +437,7 @@ chmod +x .git/hooks/pre-commit
 - [ ] IDE abierto (VSCode/Cursor) y chat con Claude funcional
 - [ ] Comando `ayuda` ejecutado exitosamente
 - [ ] **Asana configurado en `.env`** (OBLIGATORIO)
-- [ ] **20 Agent Skills instaladas en ~/.skills/** (OBLIGATORIO)
+- [ ] **20 Agent Skills instaladas en ~/.claude/skills/** (OBLIGATORIO)
 - [ ] **Git hooks instalados** (OBLIGATORIO)
 - [ ] **CodeRabbit configurado en GitHub** (OBLIGATORIO)
 - [ ] **Repositorio pusheado a GitHub** (OBLIGATORIO)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",

package/scripts/README.md

@@ -43,24 +43,22 @@ git commit --no-verify -m "mensaje"
 
 ### `install-skills.sh`
 
-**Propósito:** Instalar los 34 Agent Skills del framework en `~/.skills/`.
+**Propósito:** Instalar los 20 Agent Skills curados del framework en `~/.claude/skills/` (path canónico que Claude Code auto-descubre). Si existe `~/.skills/` de instalaciones previas (versiones ≤ 2.2.1), se crea un symlink desde el path canónico para mantener compatibilidad.
 
 **Uso:**
 ```bash
 bash scripts/install-skills.sh
 ```
 
-**Instala:** 34 skills (20 TIER 1 + 14 TIER 2).
+**Instala:** 20 skills curados para el stack de SpecLeap (Laravel + React + TypeScript + PostgreSQL).
 
 **Categorías:**
-- Consistencia: `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `code-reviewer`, `debugging-wizard`
-- Backend: `laravel-specialist`, `api-designer`, `database-optimizer`, `python-pro`, `react-expert`, `typescript-pro`
-- Diseño y frontend: `frontend-design`, `canvas-design`, `algorithmic-art`, `skill-creator`, `web-design-guidelines`, `vercel-composition-patterns`, `agent-browser`
-- DevOps: `devops-engineer`, `cloud-architect`, `architecture-designer`, `terraform-engineer`, `monitoring-expert`
-- Mobile: `react-native-expert`, `flutter-expert`
-- Testing: `test-driven-development`, `playwright-expert`, `test-master`
-- Seguridad: `security-reviewer`, `gdpr-dsgvo-expert`
-- Documentación y otros: `code-documenter`, `brainstorming`, `pdf`
+- Core / Quality (5): `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `test-driven-development`
+- Backend (4) — Laravel + PostgreSQL: `laravel-specialist`, `api-designer`, `database-optimizer`, `supabase-postgres-best-practices`
+- Frontend (4) — React + TS + shadcn: `react-expert`, `typescript-pro`, `vercel-react-best-practices`, `shadcn`
+- Diseño (3): `frontend-design`, `web-design-guidelines`, `extract-design-system`
+- Seguridad (2): `security-reviewer`, `gdpr-dsgvo-expert`
+- Process (2): `code-reviewer`, `brainstorming`
 
 El script detecta las skills ya instaladas y las salta. Puede volver a ejecutarse con seguridad.
 

package/scripts/install-skills.sh

@@ -1,6 +1,13 @@
 #!/bin/bash
-# SpecLeap — Instalador de Agent Skills TIER 1 + TIER 2
-# Versión 2.1.1 — 34 skills profesionales
+# SpecLeap — Instalador de Agent Skills (20 skills curados para el flujo SDD)
+#
+# Path: instala en $HOME/.claude/skills/ (path canónico que Claude Code
+# auto-descubre). Si existe $HOME/.skills/ (path legacy de versiones previas
+# de SpecLeap), se crea un symlink desde el path canónico para mantener
+# compatibilidad sin mover archivos.
+#
+# La lista está curada para el stack de SpecLeap (Laravel + React + TypeScript
+# + PostgreSQL) y el flujo CONTRATO → tickets → implementar → verify.
 
 set -e
 
@@ -10,74 +17,44 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m'
 
-echo -e "${BLUE}━━━ Installing Agent Skills (34 total) ━━━${NC}"
+echo -e "${BLUE}━━━ Installing 20 curated Agent Skills ━━━${NC}"
 echo ""
 
 # Lista de skills (repo:path:name)
+# El "name" debe coincidir con el frontmatter `name` del SKILL.md del repo,
+# porque ese es el identificador que Claude Code usa para activar la skill.
 SKILLS=(
-    # Consistencia (3) - obra/superpowers
+    # Core / Quality (5)
     "obra/superpowers:skills/verification-before-completion:verification-before-completion"
     "obra/superpowers:skills/systematic-debugging:systematic-debugging"
     "obra/superpowers:skills/requesting-code-review:requesting-code-review"
-    
-    # Backend (7) - jeffallan/claude-skills
+    "obra/superpowers:skills/receiving-code-review:receiving-code-review"
+    "obra/superpowers:skills/test-driven-development:test-driven-development"
+
+    # Backend Stack (4) — Laravel + PostgreSQL
     "jeffallan/claude-skills:skills/laravel-specialist:laravel-specialist"
     "jeffallan/claude-skills:skills/api-designer:api-designer"
     "jeffallan/claude-skills:skills/database-optimizer:database-optimizer"
-    "jeffallan/claude-skills:skills/code-reviewer:code-reviewer"
-    "jeffallan/claude-skills:skills/debugging-wizard:debugging-wizard"
-    "jeffallan/claude-skills:skills/python-pro:python-pro"
+    "supabase/agent-skills:skills/supabase-postgres-best-practices:supabase-postgres-best-practices"
+
+    # Frontend Stack (4) — React + TypeScript + Tailwind/shadcn
     "jeffallan/claude-skills:skills/react-expert:react-expert"
-    
-    # Diseño (4) - anthropics/skills
-    "anthropics/skills:skills/frontend-design:frontend-design"
-    "anthropics/skills:skills/skill-creator:skill-creator"
-    "anthropics/skills:skills/canvas-design:canvas-design"
-    "anthropics/skills:skills/algorithmic-art:algorithmic-art"
-    
-    # DevOps (3) - jeffallan/claude-skills
-    "jeffallan/claude-skills:skills/devops-engineer:devops-engineer"
-    "jeffallan/claude-skills:skills/cloud-architect:cloud-architect"
-    "jeffallan/claude-skills:skills/architecture-designer:architecture-designer"
-    
-    # Testing (2) - obra/superpowers
-    "obra/superpowers:skills/test-driven-development:test-driven-development"
-    "obra/superpowers:skills/receiving-code-review:receiving-code-review"
-    
-    # Frontend (1) - jeffallan/claude-skills
     "jeffallan/claude-skills:skills/typescript-pro:typescript-pro"
-    
-    # ━━━ TIER 2 Skills (14 nuevas) ━━━
-    
-    # Design/Frontend (3) - vercel-labs
+    "vercel-labs/agent-skills:skills/react-best-practices:vercel-react-best-practices"
+    "shadcn-ui/ui:skills/shadcn:shadcn"
+
+    # Design (3)
+    "anthropics/skills:skills/frontend-design:frontend-design"
     "vercel-labs/agent-skills:skills/web-design-guidelines:web-design-guidelines"
-    "vercel-labs/agent-skills:skills/composition-patterns:vercel-composition-patterns"
-    "vercel-labs/agent-browser:skills/agent-browser:agent-browser"
-    
-    # Brainstorming (1) - obra/superpowers
-    "obra/superpowers:skills/brainstorming:brainstorming"
-    
-    # PDF (1) - anthropics/skills
-    "anthropics/skills:skills/pdf:pdf"
-    
-    # DevOps/Infrastructure (2) - jeffallan/claude-skills
-    "jeffallan/claude-skills:skills/terraform-engineer:terraform-engineer"
-    "jeffallan/claude-skills:skills/monitoring-expert:monitoring-expert"
-    
-    # Mobile (2) - jeffallan/claude-skills
-    "jeffallan/claude-skills:skills/react-native-expert:react-native-expert"
-    "jeffallan/claude-skills:skills/flutter-expert:flutter-expert"
-    
-    # Documentation (1) - jeffallan/claude-skills
-    "jeffallan/claude-skills:skills/code-documenter:code-documenter"
-    
-    # Security (2) - jeffallan/claude-skills + alirezarezvani/claude-skills
+    "arvindrk/extract-design-system:skills/extract-design-system:extract-design-system"
+
+    # Security (2)
     "jeffallan/claude-skills:skills/security-reviewer:security-reviewer"
-    "alirezarezvani/claude-skills:ra-qm-team/gdpr-dsgvo-expert:gdpr-dsgvo-expert"
-    
-    # Testing Advanced (2) - jeffallan/claude-skills
-    "jeffallan/claude-skills:skills/playwright-expert:playwright-expert"
-    "jeffallan/claude-skills:skills/test-master:test-master"
+    "alirezarezvani/claude-skills:ra-qm-team/skills/gdpr-dsgvo-expert:gdpr-dsgvo-expert"
+
+    # Process (2)
+    "jeffallan/claude-skills:skills/code-reviewer:code-reviewer"
+    "obra/superpowers:skills/brainstorming:brainstorming"
 )
 
 TOTAL=${#SKILLS[@]}
@@ -85,9 +62,22 @@ INSTALLED=0
 FAILED=0
 SKIPPED=0
 
-SKILLS_DIR="$HOME/.skills"
+SKILLS_DIR="$HOME/.claude/skills"
+LEGACY_SKILLS_DIR="$HOME/.skills"
 TMP_DIR="/tmp/specleap-skills-$$"
 
+# Compatibilidad con instalaciones legacy:
+# Si el path antiguo ($HOME/.skills/) tiene skills y el path canónico
+# no existe todavía, crear symlink. Así Claude Code los ve sin tener
+# que mover archivos ni reinstalar nada.
+if [ -d "$LEGACY_SKILLS_DIR" ] && [ ! -e "$SKILLS_DIR" ]; then
+    mkdir -p "$HOME/.claude"
+    ln -s "$LEGACY_SKILLS_DIR" "$SKILLS_DIR"
+    echo -e "${YELLOW}⚠️  Detected legacy skills path $LEGACY_SKILLS_DIR${NC}"
+    echo -e "${YELLOW}   Created symlink at $SKILLS_DIR for Claude Code auto-discovery.${NC}"
+    echo ""
+fi
+
 mkdir -p "$SKILLS_DIR"
 mkdir -p "$TMP_DIR"
 
@@ -103,9 +93,9 @@ echo ""
 for i in "${!SKILLS[@]}"; do
     IFS=':' read -r repo path name <<< "${SKILLS[$i]}"
     num=$((i + 1))
-    
+
     printf "  [%2d/%2d] %-40s " "$num" "$TOTAL" "$name"
-    
+
     # Skip si ya existe
     if [ -d "$SKILLS_DIR/$name" ]; then
         echo -e "${YELLOW}SKIP${NC} (already installed)"
@@ -125,7 +115,7 @@ for i in "${!SKILLS[@]}"; do
 
     # Verificar SKILL.md
     if [ ! -f "$repo_dir/$path/SKILL.md" ]; then
-        echo -e "${RED}FAIL${NC} (SKILL.md not found)"
+        echo -e "${RED}FAIL${NC} (SKILL.md not found at $path)"
         FAILED=$((FAILED + 1))
         continue
     fi
@@ -149,7 +139,7 @@ fi
 echo ""
 
 if [ $INSTALLED -eq 0 ] && [ $SKIPPED -eq $TOTAL ]; then
-    echo -e "${GREEN}All skills already installed!${NC}"
+    echo -e "${GREEN}All 20 skills already installed!${NC}"
     exit 0
 fi
 
@@ -159,4 +149,4 @@ if [ $FAILED -gt 0 ]; then
     exit 1
 fi
 
-echo -e "${GREEN}Agent Skills installation complete!${NC}"
+echo -e "${GREEN}Agent Skills installation complete (20 skills)!${NC}"