plugin-dev

1. Misión

Este meta-skill asegura la gobernanza técnica completa del ecosistema IA: el diseño, la creación y el refinamiento continuo de los Skills compartidos (.agents/skills/), las Reglas de oro y directivas permanentes (.agents/rules/), así como la capitalización continua del conocimiento de paquetes ([NombrePkg]_IA_CONTEXT.md).

Principios Fundacionales Inviolables:

• Single Source of Truth (SSOT): Toda regla, especificación o directiva debe residir en una única ubicación con autoridad. La duplicación de instrucciones en múltiples archivos está formalmente prohibida.
• DRY (Don't Repeat Yourself): Nunca reescribir o duplicar una directiva existente. Cualquier skill o documento debe explotar la regla existente mediante una simple referencia o enlace.
• Aplica sistemáticamente los patrones de referencia de Anthropic (feature-dev, claude-code-setup, pr-review-toolkit), vela por la no contradicción de las reglas, documenta los nuevos flujos de trabajo y consigna las retroalimentaciones en forma de fichas de incidentes YAML.

2. Activación y Límites

• Cuándo activarlo:
  • Fin de conversación / Retrospectiva de sesión: Invocado por /plugin-dev para proponer un plan de enriquecimiento del archivo [NombrePkg]_IA_CONTEXT.md del paquete tratado y de las competencias movilizadas, consignando los descubrimientos, trampas y mecánicas aprendidas durante la sesión.
  • Solicitud de creación de un nuevo skill ("Crea un skill para gestionar las pruebas automatizadas", "Agrega un skill diseñar-arquitectura").
  • Refinamiento o corrección de un skill existente tras un retorno de experiencia ("Modifica el skill feature-dev para prohibir X").
  • Creación, actualización o auditoría de una Regla comportamental ("Agrega una regla para mostrar los skills utilizados", "Modifica la regla crítica sobre las migraciones en critical-rules.md").
  • Documentación de un nuevo flujo de trabajo.
  • Auditoría de conformidad de las competencias, coherencia de las directivas, eliminación de duplicaciones (DRY/SSOT) y control SemVer.
• Cuándo NO activarlo:
  • Redacción o simplificación de tutoriales ➔ Usar tutorial-writer.
  • Desarrollo de componentes o estilos Jekyll ➔ Usar dev-jekyll.
  • Sincronización del núcleo técnico compartido (Core Theme) ➔ Usar sync-theme.
  • Inicialización de agente o diagnóstico de proyecto ➔ Usar project-setup.

3. Entradas y Recursos a Cargar

• Prioridad 1: .agents/skills/plugin-dev/resources/anthropic-skill-patterns.md (Patrones oficiales Anthropic encapsulados).
• Prioridad 2: Archivos de reglas:
  • .agents/rules/critical-rules.md (Reglas críticas invariables).
  • .agents/rules/*.md (Directivas de ejecución y estilo).
• Prioridad 3: .agents/templates/generic-skill.md (Plantilla en 10 secciones) y .agents/templates/workflow-blueprint.md (Modelo de flujo).
• Prioridad 4: Registro catalog.yaml y CHANGELOG.md del Hub Global.

4. Restricciones y Reglas Inviolables

• Principios Cardinales SSOT (Single Source of Truth) y DRY:
  • Toda convención, directiva o especificación debe existir en un único lugar.
  • Las reglas comportamentales residen en .agents/rules/[nombre].md. Las competencias nunca deben duplicar el texto de estas reglas sino referenciarlas directamente.
• Formato Normalizado de Archivos de Contexto de Paquete:
  • Todo archivo de contexto de paquete debe obligatoriamente llamarse modules/[NombrePkg]/[NombrePkg]_IA_CONTEXT.md (ej: PkgRealizacionTarea_IA_CONTEXT.md).
• Minimalismo Estricto de .agents/references/ (Encapsulación Mono-Competencia):
  • El directorio transversal .agents/references/ debe contener el mínimo estricto de archivos, reservado exclusivamente a convenciones y estándares compartidos por al menos 2 competencias.
  • Todo archivo metodológico, guía, catálogo o plantilla utilizado por una sola competencia DEBE OBLIGATORIAMENTE ser movido y encapsulado en <skill>/resources/ (principio de divulgación progresiva de Anthropic).
• Bloque inspiration Obligatorio: Todo skill creado o modificado DEBE imperativamente incluir la metadato inspiration: en su frontmatter YAML con su fuente, su plugin de referencia y su patrón.
• Respeto Estricto de las 10 Secciones: Ningún skill puede ser publicado si omite alguna de las 10 secciones normalizadas.
• Jerarquía y No Contradicción de las Reglas:
  • Una regla local (.agents/rules/) prevalece sobre una recomendación general, pero no debe violar una regla crítica de seguridad (critical-rules.md) sin arbitraje explícito.
  • Cada regla debe ser concisa, unívoca y contar con un activador explícito (trigger: always_on o condicional).
• Validación Automatizada: Toda modificación de skill debe ser validada por node scripts/validate-skills.js.
• Ficha de Incidente YAML: Toda corrección producto de un error del agente debe generar una ficha en tests/feedbacks/INC-xxx.yaml.

5. Procedimiento Paso a Paso (Flujo de Diseño y Refinamiento)

Ruta A: Creación de un Nuevo Skill

1. Paso 1: Análisis de la Necesidad y Patrón Anthropic:
   • Consultar resources/anthropic-skill-patterns.md para seleccionar el patrón más cercano (feature-dev, setup, review, etc.).
2. Paso 2: Redacción del SKILL.md:
   • Rellenar la plantilla de 10 secciones.
   • Formular la descripción en 3ª persona especificando claramente los casos de activación y exclusión.
   • Rellenar el bloque YAML inspiration.
   • Encapsular los posibles recursos de acompañamiento propios del skill en su subcarpeta resources/.
3. Paso 3: Control Determinista:
   • Ejecutar node scripts/validate-skills.js.
4. Paso 4: Registro en el Catálogo:
   • Agregar la entrada en catalog.yaml y documentar en CHANGELOG.md.

Ruta B: Refinamiento de un Skill Existente

1. Paso 1: Diagnóstico y Ficha YAML:
   • Crear tests/feedbacks/INC-[NUM].yaml con el contexto, el comportamiento observado y la corrección buscada.
2. Paso 2: Corrección Quirúrgica:
   • Agregar la regla en la Sección #4 (Restricciones) o una prueba binaria en la Sección #8 (Checklist).
3. Paso 3: Incremento SemVer:
   • Actualizar la versión (ej: 1.0.1) y registrar en CHANGELOG.md.

Ruta C: Creación o Modificación de una Regla (Rules)

1. Paso 1: Calificación del Nivel de Regla:
   • Regla global de ingeniería / seguridad ➔ Agregar en .agents/rules/critical-rules.md o .agents/rules/general-principles.md.
   • Regla comportamental de agente de proyecto ➔ Agregar en .agents/rules/[nombre-de-la-regla].md.
2. Paso 2: Redacción Concisa e Inviolable:
   • Formular imperativos claros ("El agente debe...", "Prohibición formal de...").
   • Dar un ejemplo directo del formato esperado.
   • Respetar el principio SSOT: si la regla ya existe, nunca duplicarla.
3. Paso 3: Sincronización y Notificación:
   • Repercutir la modificación en el Hub o el proyecto local y registrar la evolución en CHANGELOG.md.

Ruta D: Capitalización Continua al Final de la Conversación (/plugin-dev)

1. Paso 1: Retrospectiva e Identificación de Descubrimientos:
   • Identificar el o los paquetes tratados durante la sesión reciente.
   • Extraer las mecánicas específicas que el agente tuvo que investigar o deducir:
     • Tablas y modelos implicados, relaciones y hooks de negocio.
     • Particularidades del ViewStateService o de los filtros de la tabla.
     • Servicios temporales, jobs u observers recién introducidos.
     • Trampas o edge cases resueltos (ej: cálculos falseados por omisión de filtros padres).
2. Paso 2: Evaluación de las Brechas Documentales:
   • Comparar estos descubrimientos con el contenido existente de modules/[NombrePkg]/[NombrePkg]_IA_CONTEXT.md.
   • Verificar si alguna competencia (feature-dev) o regla se beneficiaría de una directiva adicional.
3. Paso 3: Propuesta de Plan de Enriquecimiento:
   • Someter al diseñador un plan claro y estructurado detallando las adiciones propuestas:
     • Para [NombrePkg]_IA_CONTEXT.md (nuevos servicios, filtros clave, sección Trampas y Recomendaciones).
     • Para las competencias, si aplica.
4. Paso 4: Ejecución tras Validación:
   • Una vez validado, enriquecer el archivo [NombrePkg]_IA_CONTEXT.md para que toda futura sesión de mantenimiento disponga inmediatamente de este conocimiento capitalizado.

6. Gestión de Ambigüedades y Decisiones

• Arbitraje Ubicación de los Recursos (Skill vs Agente):
  • Si el recurso es explotado exclusivamente por un skill particular (ej: plantillas editoriales de un redactor, catálogo técnico propio) ➔ Ubicación obligatoria: <skill>/resources/[archivo].md (cargado bajo demanda en la sección 3 del skill).
  • Si el recurso define un estándar de ingeniería transversal compartido por 2 competencias o más ➔ Ubicación: .agents/references/conventions/ o .agents/references/architecture/.
• Arbitraje Skill vs Regla:
  • Si la instrucción es una restricción permanente o un guardarraíl transversal (ej: visualización de competencias, estilo de respuesta, prohibición de migración) ➔ Crear una Regla (.agents/rules/).
  • Si la instrucción describe una secuencia instrumentalizada con activación bajo demanda, entradas, lógica paso a paso y entregables ➔ Crear un Skill (SKILL.md).
• Si la regla solicitada es exclusiva de Solicode LMS: no modificar el estándar del Hub global, sino registrarla en .agents/rules/ y .agents/references/conventions/project-conventions.md.

7. Formato de Salida y Entregables

• El archivo SKILL.md completo o el archivo de regla (.agents/rules/*.md).
• La actualización de catalog.yaml y CHANGELOG.md.
• El resultado de la ejecución del script validate-skills.js (0 errores).

8. Control de Calidad (Checklist Binaria)

• El frontmatter YAML del skill contiene el bloque inspiration completo (fuente, plugin, patrón)?
• La descripción está en 3ª persona y especifica cuándo activar y cuándo no activar?
• Las 10 secciones normalizadas están todas presentes y completas?
• Se respeta el principio SSOT (Single Source of Truth) y la regla DRY (ninguna directiva duplicada entre archivos)?
• El directorio .agents/references/ es mínimo y está libre de todo recurso mono-competencia?
• Los recursos mono-competencia están rigurosamente encapsulados en <skill>/resources/?
• Si se trata de una regla, es concisa, no contradictoria con critical-rules y cuenta con un ejemplo claro?
• El script node scripts/validate-skills.js se ejecuta con éxito?

9. Gestión de Errores Frecuentes

Error Típico	Causa	Solución Inmediata
Depositar un recurso específico a nivel de Agente	Falta de granularidad en la encapsulación	Mover el archivo bajo <skill>/resources/ y referenciarlo como recurso interno
Crear un skill para una simple regla pasiva	Confusión entre regla y flujo instrumentalizado	Trasladar la instrucción a .agents/rules/
Olvido del metadato inspiration	Falta de atención	Agregar sistemáticamente el bloque inspiration en el frontmatter
Regla local en conflicto con el estándar Hub	Falta de auditoría previa	Auditar .agents/rules/critical-rules.md antes de formalizar la regla

10. Ejemplos Concretos (Few-Shot)

Ejemplo de invocación A (Skill): "Crea el skill tutorial-writer inspirado en content-authoring." Comportamiento: El agente carga anthropic-skill-patterns.md, extrae el patrón de redacción estructurada, redacta las 10 secciones con inspiration: { plugin: "content-authoring" }, aísla las plantillas didácticas en tutorial-writer/resources/, y registra la competencia en catalog.yaml.

Ejemplo de invocación B (Regla): "Agrega una regla que imponga la visualización de los skills utilizados al final de cada mensaje." Comportamiento: El agente aplica la Ruta C de plugin-dev, redacta .agents/rules/visualizacion-skills.md, actualiza .agents/rules/critical-rules.md, y aplica inmediatamente el formato requerido.