# Guía del Equipo de Soporte

## Contenido de Innovación: Modos y Habilidades de Desarrollo de Contenido Educativo

**Versión:** 1.1.1
**Audiencia:** Equipo de Soporte, Administradores de Sistemas, Líderes Técnicos
**Fecha:** 2026-04-24

---

## 1. Introducción

Esta guía proporciona al equipo de soporte instrucciones precisas para instalar, configurar, solucionar problemas y extender los modos y habilidades de Contenido de Innovación para Roo Code.

---

## 2. Prerrequisitos

### 2.1 Requisitos del Sistema

| Componente | Requisito |
|------------|-----------|
| Roo Code | Versión 3.8 o posterior |
| Node.js | Versión 18.x o posterior (para scripts de validación) |
| Git | Versión 2.30 o posterior |
| Sistema Operativo | Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+) |

### 2.2 Permisos Requeridos

- Acceso de lectura/escritura al espacio de trabajo del proyecto
- Capacidad para modificar el archivo de configuración `.roomodes`
- Acceso al directorio `.agents/skills/`
- Acceso al navegador (para modos Content Producer y LX Designer)

---

## 3. Instalación

### 3.1 Clonar Repositorio

```bash
git clone https://archi.pinion.education/PinionEducation/pinion-modes-skills.git innovation-content
cd innovation-content
```

### 3.2 Instalar Modos

**Opción A: Instalación Manual**

Copie cada configuración de modo a su archivo `.roomodes` de Roo Code:

```bash
# En Windows (cmd.exe)
copy innovation-content\modes\curriculum-designer\mode-config.yaml %USERPROFILE%\.roo\modes\
copy innovation-content\modes\instructional-writer\mode-config.yaml %USERPROFILE%\.roo\modes\
copy innovation-content\modes\assessment-dev\mode-config.yaml %USERPROFILE%\.roo\modes\
copy innovation-content\modes\content-producer\mode-config.yaml %USERPROFILE%\.roo\modes\
copy innovation-content\modes\lx-designer\mode-config.yaml %USERPROFILE%\.roo\modes\
copy innovation-content\modes\accessibility-auditor\mode-config.yaml %USERPROFILE%\.roo\modes\
```

```bash
# En macOS/Linux
cp innovation-content/modes/*/mode-config.yaml ~/.roo/modes/
```

**Opción B: Instalación Automatizada**

```bash
# Ejecutar el script de instalación (si está disponible)
./scripts/install-modes.sh
```

### 3.3 Instalar Reglas

Copie los archivos de reglas XML al directorio de reglas apropiado para cada modo:

```bash
# En Windows (cmd.exe)
for %m in (curriculum-designer instructional-writer assessment-dev content-producer lx-designer accessibility-auditor) do (
  xcopy /E /I innovation-content\modes\%m\rules %USERPROFILE%\.roo\rules-%m\
)
```

```bash
# En macOS/Linux
for mode in curriculum-designer instructional-writer assessment-dev content-producer lx-designer accessibility-auditor; do
  mkdir -p ~/.roo/rules-$mode
  cp innovation-content/modes/$mode/rules/*.xml ~/.roo/rules-$mode/
done
```

### 3.4 Instalar Habilidades

Copie todos los directorios de habilidades a su carpeta de habilidades:

```bash
# En Windows (cmd.exe)
xcopy /E /I innovation-content\skills %USERPROFILE%\.agents\skills\
```

```bash
# En macOS/Linux
cp -r innovation-content/skills/* ~/.agents/skills/
```

### 3.5 Verificar Instalación

1. Abra Roo Code
2. Cambie a cada modo y verifique que cargue sin errores:
   - `curriculum-designer`
   - `instructional-writer`
   - `assessment-dev`
   - `content-producer`
   - `lx-designer`
   - `accessibility-auditor`
3. Pruebe la invocación de una habilidad en cada modo

---

## 4. Configuración

### 4.1 Estructura de Configuración de Modos

Cada archivo de configuración de modo (`mode-config.yaml`) sigue esta estructura:

```yaml
name: "Nombre para Mostrar del Modo"
slug: "slug-del-modo"
roleDefinition: "Descripción detallada de lo que hace este modo"
whenToUse: "Guía sobre cuándo activar este modo"
permissions:
  fileRestrictions:
    - "patrones/*.md"
    - "directorio/**/*"
  allowedCommands:
    - "nombre-del-comando"
  browserAccess: true/false
customInstructions: |
  Instrucciones adicionales para el comportamiento del modo
```

### 4.2 Estructura de Configuración de Habilidades

Cada archivo de habilidad (`SKILL.md`) sigue esta estructura:

```yaml
---
name: nombre-habilidad
description: Breve descripción de la habilidad
---

# Nombre de la Habilidad

## Capacidades
- Capacidad 1
- Capacidad 2

## Uso
Cuándo y cómo usar esta habilidad

## Entrada
Formato de entrada esperado

## Salida
Formato de salida esperado

## Limitaciones
Limitaciones conocidas

## Suposiciones
Suposiciones hechas por esta habilidad
```

### 4.3 Personalizar Permisos

Para modificar los permisos de archivo de un modo, edite el archivo `mode-config.yaml`:

```yaml
permissions:
  fileRestrictions:
    - "directorio-personalizado/**/*"
    - "*.extension-personalizada"
```

---

## 5. Solución de Problemas

### 5.1 Problemas Comunes

| Problema | Causa | Resolución |
|----------|-------|------------|
| El modo no aparece en Roo Code | Configuración no copiada | Verifique que el archivo `.roomodes` contiene la entrada del modo |
| Habilidad no encontrada | Habilidad no en directorio correcto | Verifique que `~/.agents/skills/nombre-habilidad/SKILL.md` existe |
| Permiso denegado | Restricción de archivo muy estrecha | Actualice `fileRestrictions` en mode-config.yaml |
| Error de análisis XML | XML mal formado | Valide XML con `xmllint` o validador en línea |
| Error de análisis YAML | Sintaxis YAML inválida | Valide YAML con `yamllint` o validador en línea |

### 5.2 Comandos de Diagnóstico

```bash
# Validar todos los archivos YAML
find . -name "*.yaml" -exec yamllint {} \;

# Validar todos los archivos XML
find . -name "*.xml" -exec xmllint --noout {} \;

# Verificar que existen archivos de habilidades
for skill in $(ls skills/); do
  test -f "skills/$skill/SKILL.md" && echo "$skill: OK" || echo "$skill: FALTA"
done

# Verificar que existen reglas de modos
for mode in $(ls modes/); do
  count=$(ls "modes/$mode/rules/"*.xml 2>/dev/null | wc -l)
  echo "$mode: $count reglas"
done
```

### 5.3 Ubicaciones de Registros

| Tipo de Registro | Ubicación |
|------------------|-----------|
| Registros de Roo Code | `~/.roo/logs/` |
| Registros de activación de modos | Salida de consola al cambiar modos |
| Registros de invocación de habilidades | Salida de consola al usar habilidades |

---

## 6. Extender Modos y Habilidades

### 6.1 Agregar un Nuevo Modo

**Paso 1: Crear Directorio del Modo**

```bash
mkdir -p modes/nuevo-modo/rules
```

**Paso 2: Crear Configuración del Modo**

Cree `modes/nuevo-modo/mode-config.yaml`:

```yaml
name: "Nombre del Nuevo Modo"
slug: "nuevo-modo"
roleDefinition: "Describir lo que hace este modo"
whenToUse: "Describir cuándo usar este modo"
permissions:
  fileRestrictions:
    - "directorio-nuevo-modo/**/*"
  allowedCommands:
    - "comando-relevante"
customInstructions: |
  Instrucciones adicionales
```

**Paso 3: Crear Archivos de Reglas XML**

Cree los 7 archivos de reglas XML requeridos:

```bash
# Use esta secuencia de prompts para generar cada archivo de reglas:
```

**Prompt para 1_workflow.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '1_workflow.xml'.
Define el flujo de trabajo principal con estas etapas:
1. Recibir entrada
2. Procesar entrada
3. Validar salida
4. Entregar resultado

Usa este formato:
<?xml version="1.0" encoding="UTF-8"?>
<rule name="workflow" mode="nuevo-modo">
  <workflow>
    <stage name="Recibir Entrada">...</stage>
    <stage name="Procesar Entrada">...</stage>
    <stage name="Validar Salida">...</stage>
    <stage name="Entregar Resultado">...</stage>
  </workflow>
</rule>
```

**Prompt para 2_best_practices.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '2_best_practices.xml'.
Define 5 mejores prácticas para este modo con descripciones y ejemplos.
```

**Prompt para 3_common_patterns.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '3_common_patterns.xml'.
Define 3-5 patrones de diseño comunes usados en este modo.
```

**Prompt para 4_decision_guidance.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '4_decision_guidance.xml'.
Proporciona árboles de decisión y guía para elecciones comunes en este modo.
```

**Prompt para 5_examples.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '5_examples.xml'.
Proporciona 2-3 ejemplos resueltos mostrando salida correcta de este modo.
```

**Prompt para 6_error_handling.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '6_error_handling.xml'.
Define escenarios de error, métodos de detección y pasos de resolución.
```

**Prompt para 7_communication.xml:**
```
Crea un archivo de reglas XML para el modo 'nuevo-modo' llamado '7_communication.xml'.
Define plantillas de transferencia para pasar trabajo hacia y desde este modo.
```

**Paso 4: Registrar Modo**

Agregue el modo al archivo `.roomodes` o copie `mode-config.yaml` al directorio de modos.

### 6.2 Agregar una Nueva Habilidad

**Paso 1: Crear Directorio de Habilidad**

```bash
mkdir -p skills/nueva-habilidad
```

**Paso 2: Crear SKILL.md**

Cree `skills/nueva-habilidad/SKILL.md`:

```markdown
---
name: nueva-habilidad
description: Breve descripción de lo que hace esta habilidad
---

# Nueva Habilidad

## Capacidades
- Capacidad 1: Descripción
- Capacidad 2: Descripción
- Capacidad 3: Descripción

## Uso
Describir cuándo y cómo usar esta habilidad. Incluir escenarios específicos.

## Entrada
Describir el formato de entrada esperado:
- Tipos de archivo aceptados
- Estructura de datos esperada
- Campos requeridos

## Salida
Describir el formato de salida:
- Tipos de archivo producidos
- Estructura de datos devuelta
- Indicadores de éxito/fallo

## Limitaciones
- Limitación 1
- Limitación 2

## Suposiciones
- Suposición 1
- Suposición 2
```

**Paso 3: Probar Habilidad**

1. Active el modo padre
2. Invoque la habilidad por nombre
3. Verifique que devuelva la salida esperada
4. Pruebe el manejo de errores con entrada inválida

### 6.3 Modificar Modos Existentes

**Para cambiar permisos:**
1. Edite `modes/[modo]/mode-config.yaml`
2. Actualice `fileRestrictions` o `allowedCommands`
3. Pruebe que el modo aún funciona correctamente

**Para cambiar flujo de trabajo:**
1. Edite `modes/[modo]/rules/1_workflow.xml`
2. Asegure que el XML está bien formado
3. Pruebe el flujo de trabajo en Roo Code

**Para agregar mejores prácticas:**
1. Edite `modes/[modo]/rules/2_best_practices.xml`
2. Agregue nuevos elementos `<practice>`
3. Verifique que el modo aplica las nuevas prácticas

### 6.4 Modificar Habilidades Existentes

**Para actualizar una habilidad:**
1. Edite `skills/[habilidad]/SKILL.md`
2. Actualice la sección relevante (Capacidades, Uso, Entrada, Salida, etc.)
3. Pruebe la habilidad en su modo padre

---

## 7. Secuencias de Prompts para Tareas de Soporte

### 7.1 Instalar Todos los Modos y Habilidades

```
Instala los 6 modos y 30 habilidades del proyecto innovation-content.
Copia las configuraciones de modos a .roomodes, reglas XML a .roo/rules-[slug]/,
y habilidades a .agents/skills/. Verifica que cada modo carga correctamente.
```

### 7.2 Validar Instalación

```
Valida la instalación de innovation-content:
1. Verifica que las 6 configuraciones de modo existen y son YAML válido
2. Verifica que los 42 archivos de reglas XML existen y están bien formados
3. Verifica que los 30 archivos SKILL.md existen y tienen frontmatter YAML
4. Prueba cambiar a cada modo
5. Reporta cualquier problema encontrado
```

### 7.3 Agregar Nuevo Modo

```
Crea un nuevo modo llamado '[Nombre del Modo]' con slug '[slug-del-modo]'.
Debe [describir propósito].
Crea mode-config.yaml y 7 archivos de reglas XML en modes/[slug-del-modo]/.
El modo debe tener permisos para [listar directorios/patrones].
```

### 7.4 Agregar Nueva Habilidad

```
Crea una nueva habilidad llamada '[Nombre de Habilidad]' para el modo [nombre-modo].
Debe [describir capacidad].
Crea SKILL.md en skills/[slug-habilidad]/ con frontmatter YAML,
secciones de Capacidades, Uso, Entrada, Salida, Limitaciones y Suposiciones.
```

### 7.5 Depurar Problema de Carga de Modo

```
Depura por qué el modo [slug-del-modo] no está cargando correctamente.
1. Verifica que mode-config.yaml existe y es YAML válido
2. Verifica que los 7 archivos de reglas XML existen y son XML bien formado
3. Verifica que los permisos de archivo no son demasiado restrictivos
4. Verifica conflictos con otros modos
5. Reporta hallazgos y solución sugerida
```

### 7.6 Depurar Habilidad No Encontrada

```
Depura por qué la habilidad [nombre-habilidad] no se encuentra.
1. Verifica que skills/[nombre-habilidad]/SKILL.md existe
2. Verifica que el frontmatter YAML tiene nombre y descripción
3. Verifica que la habilidad está en la lista de habilidades del modo correcto
4. Verifica conflictos de nombres
5. Reporta hallazgos y solución sugerida
```

### 7.7 Actualizar Permisos de Modo

```
Actualiza los permisos para el modo [slug-del-modo] para permitir edición de:
- [nuevo-patron-1]/**/*
- *.[nueva-extension]
Actualiza modes/[slug-del-modo]/mode-config.yaml y verifica el cambio.
```

### 7.8 Generar Documentación de Modo

```
Genera documentación para el modo [slug-del-modo] incluyendo:
1. Propósito del modo y cuándo usar
2. Lista de 5 habilidades con descripciones
3. Resumen del flujo de trabajo
4. Permisos de archivo
5. Protocolos de comunicación (transferencias hacia/desde este modo)
Salida como markdown adecuado para inclusión en README o wiki.
```

---

## 8. Mantenimiento

### 8.1 Actualizar desde Remoto

```bash
cd innovation-content
git pull origin main
# Re-instalar modos y habilidades si se agregaron nuevos
```

### 8.2 Respaldar Personalizaciones

```bash
# Respaldar configuraciones de modos personalizados
cp ~/.roo/modes/*.yaml backups/modes/

# Respaldar habilidades personalizadas
cp -r ~/.agents/skills/* backups/skills/

# Respaldar reglas personalizadas
cp -r ~/.roo/rules-* backups/rules/
```

### 8.3 Compatibilidad de Versiones

| Versión de Contenido de Innovación | Versión Mínima de Roo Code | Notas |
|-------------------------------------|----------------------------|-------|
| 1.0.x | 3.8 | Lanzamiento inicial |
| 1.1.x | 3.8 | Guía del equipo de soporte y guía del usuario |
| 1.1.1 | 3.8 | Versiones en español de toda la documentación |

---

## 9. Contacto y Escalamiento

| Tipo de Problema | Contacto | Ruta de Escalamiento |
|------------------|----------|---------------------|
| Problemas de instalación | Equipo de Soporte | Líder Técnico |
| Problemas de comportamiento de modo | Desarrollador de Modos | Líder del Proyecto |
| Problemas de habilidades | Desarrollador de Habilidades | Líder del Proyecto |
| Solicitudes de funciones | Líder del Proyecto | Propietario del Producto |

---

## 10. Apéndice

### 10.1 Referencia de Estructura de Archivos

```
innovation-content/
├── modes/
│   └── [slug-del-modo]/
│       ├── mode-config.yaml
│       └── rules/
│           ├── 1_workflow.xml
│           ├── 2_best_practices.xml
│           ├── 3_common_patterns.xml
│           ├── 4_decision_guidance.xml
│           ├── 5_examples.xml
│           ├── 6_error_handling.xml
│           └── 7_communication.xml
├── skills/
│   └── [slug-habilidad]/
│       └── SKILL.md
└── docs/
    ├── plan.md
    ├── srs.md
    ├── support-team-guide.md
    ├── user-guide.md
    ├── plan-ES.md
    ├── srs-ES.md
    ├── support-team-guide-ES.md
    └── user-guide-ES.md
```

### 10.2 Tarjeta de Referencia Rápida

| Tarea | Comando/Acción |
|-------|----------------|
| Instalar modos | `cp modes/*/mode-config.yaml ~/.roo/modes/` |
| Instalar reglas | `cp -r modes/*/rules/* ~/.roo/rules-[slug]/` |
| Instalar habilidades | `cp -r skills/* ~/.agents/skills/` |
| Validar YAML | `yamllint mode-config.yaml` |
| Validar XML | `xmllint --noout regla.xml` |
| Probar modo | Cambiar a modo en Roo Code |
| Probar habilidad | Invocar habilidad por nombre en modo |