themominpro/universal-skill-creator

Universal Skill Creator

1. Reencuadre Central e Invariantes No Negociables

• Modelo Mental: Una habilidad de clase mundial es un sistema operativo procedimental bajo demanda, NO un prompt no estructurado. Combina propiedad intelectual privada del profesional con compuertas de código determinista (Arquitectura Híbrida de Tres Zonas) que se adhieren estrictamente a references/agentskills_spec.md.
• Aviso de Entorno: Python 3 y las herramientas estándar de descubrimiento del espacio de trabajo están preinstaladas. NO intente instalar gestores de paquetes a menos que una importación explícita falle.
• Invariante Dura 1 (Compuerta Cero-Olores): Nunca entregue una habilidad que falle python3 scripts/audit_skill.py <ruta>. Todos los olores estructurales de diseño deben auditarse y resolverse.
• Invariante Dura 2 (Mandato de Creación de Scripts): Siempre que una habilidad candidata realice validaciones, comprobaciones de esquemas o comparaciones de AST, DEBE crear la utilidad ejecutable complementaria en scripts/validate.py (0 tokens de contexto para el código del script).
• Invariante Dura 3 (Supervivencia a la Compactación): Las invariantes, los avisos de paquetes y la Tabla de Enrutamiento de Tareas DEBEN residir dentro de los primeros 1.000 tokens de SKILL.md para evitar el desgarro por compactación (references/compaction_resilience.md).
• Invariante Dura 4 (Estándar de Producción): Cada habilidad debe incluir un dialecto estándar del dominio, una Tabla Anti-Racionalización y casos de prueba de evaluación verificables.
• Invariante Dura 5 (Compuerta de Comportamiento, No Solo de Estructura): Una habilidad que pasa la auditoría y la seguridad pero no supera la línea base sin habilidad, no sobrevive a la presión, o no enruta correctamente en modo stub, NO se publica. Consulte references/baseline_grading.md, references/pressure_scenarios.md, references/stub_router_mode.md y references/render_qa.md.
• Invariante Dura 6 (Solo Estructura de Ejemplo): Los ejemplos enviados muestran solo estructura, disparador, flujo de trabajo, tabla de decisiones, script de validación y evaluaciones. NO copie las reglas de dominio de un ejemplo en una nueva habilidad. Construya cada nueva habilidad a partir del SOP, la transcripción y la investigación de dominio del usuario.

---

2. Tabla de Enrutamiento de Tareas

Intención del Usuario / Tipo de Entrada	Flujo de Trabajo de Creación Recomendado	Referencia Bajo Demanda de Apoyo
Habilidad Comercial B2B (para venta / entrega a cliente)	Ejecutar Pipeline Completo de 6 Fases (Fases 0–5)	references/competitor_teardown_protocol.md
Notas en bruto / SOP / Transcripción de Desarrollador	Ejecutar Pipeline Completo de Creación de 6 Fases	references/domain_knowledge_ingestion.md
Habilidad que requiere APIs externas o servidores MCP	Ejecutar Descubrimiento de Herramientas de Fase 1 + Cableado MCP	references/mcp_tool_patterns.md
Auditar o corregir una habilidad existente	Ejecutar Auditoría y Parche de 26 Olores con Cero Tokens	references/smell_taxonomy_26.md
Creación interactiva de múltiples turnos	Aplicar Protocolo de Triage de Ambigüedad OMSC	references/question_triage_omsc.md
Habilidad sensible a versiones (CLI, API, guía cambiante)	Usar Modo Stub / Router, solo puntero de 40-60 líneas	references/stub_router_mode.md
Cualquier habilidad, en cada etapa de decisión	Ejecutar Puntos de Control de QA, máx. 2 preguntas por punto de control, registrar cada punto de control	references/qa_checkpoints.md
Entrada en formato .docx, .pdf, .ppt o similar	Usar primero la lectura nativa del arnés (Claude Code / Claude); el extractor es un respaldo opcional, solo necesario antes del script de léxico de solo texto	scripts/extract_text.py
Demostrar que una habilidad realmente ayuda	Ejecutar Presión + Calificación de Línea Base + QA de Renderizado	references/pressure_scenarios.md, references/baseline_grading.md, references/render_qa.md

---

3. Fase 0: Inteligencia de Mercado Profunda y Desglose de Competidores

Antes de redactar instrucciones, ejecute el reconocimiento competitivo usando agents/niche_researcher.md:

• Paso 0.1 (Desglose de Competidores): Busque habilidades públicas existentes, prompts o instrucciones personalizadas en este nicho.
  • Audite las ofertas de los competidores contra la taxonomía de 26 Olores (references/competitor_teardown_protocol.md).
  • Identifique sus fallos estructurales (por ejemplo, slop genérico de IA, Buffet de Opciones, scripts de validación faltantes).
  • Defina el antídoto que corrige los fallos estructurales de los competidores.
• Paso 0.2 (Ingesta de Literatura y Dialecto del Dominio):
  • Ingiera libros relevantes, documentos técnicos, transcripciones de podcasts y SOPs empresariales, en cualquiera de estos formatos: .txt, .md, .docx, .pdf, notas y transcripciones.
  • Regla de formato, priorizando el arnés, NO una regla estricta: Claude Code y Claude leen .md, .pdf, .docx, .ppt y formatos similares de forma nativa, por lo tanto, use la lectura del propio arnés primero. No fuerce la extracción cuando el arnés ya haya leído el archivo.
  • El extractor de paquetes en scripts/extract_text.py es un respaldo opcional, solo para arneses o scripts que necesitan texto plano. Su único uso obligatorio es el script de léxico, que solo lee texto, así que si ejecuta el léxico en un .docx o .pdf, extraiga a .txt primero:

  python3 scripts/extract_text.py ruta/a/fuente.docx --output evals/fuente.txt
  python3 scripts/extract_text.py ruta/a/fuente.pdf --output evals/fuente.txt
  

  • Los PDFs escaneados solo con imágenes no tienen capa de texto: el extractor advierte y no devuelve texto. No invente texto para ellos; use OCR fuera de este paquete y registre ese paso, o deje que Claude lea el archivo de forma nativa si puede.
  • Siga references/domain_knowledge_ingestion.md para extraer:
    1. Acrónimos autoritativos de la industria, métricas y dialecto estándar (por ejemplo, MEDDPICC, CAC payback, hook dwell-time).
    2. Términos candidatos para el léxico mediante python3 scripts/build_domain_lexicon.py <fuentes> --output evals/lexicon.json.
    3. Umbrales algorítmicos y fórmulas medibles.
    4. Listas de alta densidad de modos de fallo no obvios ("footguns").

---

4. Fase 1: Descubrimiento del Entorno y Herramientas (Compuerta de Zona 1)

Copie y ejecute este paso de descubrimiento antes de escribir cualquier documentación:

• Paso 1.1 (Sondear Entorno y Herramientas): Ejecute el script de descubrimiento incluido:

  python3 scripts/discover_env.py
  

  (En Windows PowerShell, use python3 scripts/discover_env.py)
  • Inspeccione la salida en busca del SO detectado, binarios CLI disponibles (git, docker, python, etc.) y servidores MCP activos.
  • Si la habilidad candidata involucra un servicio externo (por ejemplo, Figma, GitHub, Postgres), verifique si existe una herramienta MCP o CLI coincidente en el entorno.

---

5. Fase 2: Descubrimiento Silencioso del Espacio de Trabajo y Triage OMSC

• Paso 2.1 (Lectura Silenciosa del Contexto): Inspeccione los archivos de configuración del repositorio activo (package.json, pyproject.toml, Cargo.toml, .env.example, historial de git).
  • Regla Estricta: Nunca le haga al usuario una pregunta sobre lenguaje, framework o herramienta que pueda descubrirse leyendo archivos en el espacio de trabajo.
• Paso 2.2 (Puntos de Control de QA, Obligatorios en Cada Etapa): Siga references/qa_checkpoints.md. El triage de la Fase 2 por sí solo no es suficiente. En cada punto de control, presente un resumen de decisión de 5 líneas, haga como máximo 2 preguntas con un valor predeterminado (Recomendado), y regístrelo:

  python3 scripts/record_qa.py evals/qa-checkpoints.json --checkpoint teardown-domain --summary "nicho, antídoto, principales footguns" --question "¿El límite del nicho es correcto? (Recomendado: sí)" --confirmed
  

  • Punto de Control 1, después de la Fase 0: teardown-domain, nicho, competidores, lagunas, fortalezas, antídoto, principales footguns.
  • Punto de Control 2, después de la arquitectura, antes del borrador: arquitectura, estructura de 6 niveles, tabla de enrutamiento, lista de scripts, lista de referencias, lo que NO hará.
  • Punto de Control 3, después del borrador del flujo de trabajo, antes de las compuertas: draft-workflow, pasos en orden, tablas de decisión, entradas anti-racionalización, ejemplo entrada/salida.
  • Punto de Control 4, después de las compuertas, antes del empaquetado: compuertas, calificación de auditoría, seguridad, excusas de presión cerradas, delta de línea base, QA de renderizado.
  • Punto de Control 5, antes del envío, después del disparador y el paquete: envío, resultados del disparador, contenido del paquete, estado del guardián, estado stub/router si corresponde.
  • Alto radio de explosión, comercial o arquitectura mutuamente excluyente: espere la respuesta del usuario en ese punto de control antes de continuar. Bajo radio de explosión: se permite presentar el resumen y continuar con el valor predeterminado recomendado, pero el resumen y las respuestas asumidas aún deben registrarse. Un punto de control sin registro no ocurrió.
• Paso 2.3 (El Filtro de Ambigüedad OMSC):
  • Verifique si el Objetivo, la Métrica, el Alcance o las Restricciones contienen incógnitas bloqueantes (references/decision_matrices_and_escalation.md).
  • Si es de Bajo Radio de Explosión / Flujo de Trabajo Estándar: Proceda inmediatamente usando los valores predeterminados del dominio. Haga 0 preguntas.
  • Si es de Alto Radio de Explosión / Rama de UX Mutuamente Excluyente: Pause y haga como máximo 1 a 3 preguntas compactas:
    1. Adjunte (Recomendado) a la opción predeterminada más segura.
    2. Proporcione 2–3 opciones con letras y compensaciones de una línea.

---

6. Fase 3: Síntesis Híbrida de 3 Zonas

Cree la estructura completa de carpetas de la habilidad: <nombre-habilidad>/ que contenga SKILL.md, scripts/, references/ y assets/.

• Paso 3.1 (Redactar SKILL.md mediante Arquitectura de 6 Niveles): Adopte el rol de agents/architect.md para sintetizar la especificación principal usando assets/master_template.md:
  • Byte 0: Comienza inmediatamente con ---. Cero corchetes angulares en el frontmatter.
  • Nivel 1 (Tokens 1–500): Modelo mental del dominio e Invariantes No Negociables.
  • Nivel 2 (Tokens 500–1,000): Tabla de Enrutamiento de Tareas (mata los olores TOB/MDT).
  • Nivel 3 (Tokens 1,000–1,500): Descubrimiento Silencioso y Triage de Ambigüedad OMSC.
  • Nivel 4 (Tokens 1,500–3,000): Pasos numerados con listas de verificación - [ ] copiables.
  • Nivel 5 (Tokens 3,000–4,200): Footguns de Dominio de Alta Densidad y Tabla Anti-Racionalización.
  • Nivel 6 (Tokens 4,200–4,800): Lo Que Esta Habilidad NO Hace (mata el olor NG).
  • Límite Total del Cuerpo: Manténgase por debajo de 450 líneas (<5.000 tokens).
• Paso 3.2 (Sintetizar Scripts Deterministas Complementarios y Plantillas Secretas): Adopte el rol de agents/script_smith.md:
  • Para validación: cree scripts/validate.py usando assets/script_templates/validator_template.py.
  • Para mutaciones por lotes/destructivas: cree scripts/validate_plan.py.
  • Si se declara requires_secrets: en SKILL.md: cree .env.example en la raíz de la habilidad con URL de panel y valores de marcador de posición.
  • Asegúrese de que los scripts emitan JSON compacto a stdout y salgan con 0 en caso de éxito / 1 en caso de fallo.
• Paso 3.3 (Delegar Documentos Profundos a Referencias Planas): Si los manuales de dominio, esquemas o guías secundarias exceden las 50 líneas, colóquelos en references/<tema>.md.
  • Invariante: Las referencias deben ser planas (exactamente 1 salto de profundidad desde SKILL.md).

---

7. Fase 4: Auditoría Estructural de 26 Olores con Cero Tokens y Evaluaciones

• Paso 4.1 (Ejecutar Linter Estático Automatizado): Ejecute el linter estructural contra el directorio de la habilidad recién generada:

  python3 scripts/audit_skill.py ruta/a/habilidad-generada
  

• Paso 4.2 (Ejecutar Escaneo de Seguridad Determinista): Ejecute el escáner de seguridad AST para verificar que no haya ejecución remota de código, inyección de shell o fugas de credenciales:

  python3 scripts/security_scan.py ruta/a/habilidad-generada
  

• Paso 4.3 (Parchear Todas las Violaciones y Olores): Si la auditoría informa alguna violación, adopte el rol de agents/smell_auditor.md:
  • Laguna de Racionalización (RL): Agregue una Tabla Anti-Racionalización explícita que refute las excusas del modelo.
  • Buffet de Opciones (TOB): Reemplace las listas de herramientas con una única herramienta predeterminada por escenario.
  • Cuerpo Extenso (LSB): Mueva fragmentos de código largos a references/ o assets/.
  • Vuelva a ejecutar audit_skill.py hasta que el estado sea PASS con una Calificación de A o A+.
• Paso 4.4 (Ejecutar Evaluaciones Comparativas Empíricas): Ejecute casos de prueba para establecer tasas de aprobación de tareas verificables:

  python3 scripts/run_evals.py ruta/a/habilidad-generada
  

  • Para revisiones, adopte el rol de agents/comparator.md para realizar una comparación doble ciego contra la línea base.
• Paso 4.5 (Escenarios de Presión, Obligatorio): Genere escenarios de presión combinados, luego ejecute cada uno SIN la habilidad y CON la habilidad, registrando las excusas textuales (references/pressure_scenarios.md):

  python3 scripts/generate_pressure_scenarios.py ruta/a/habilidad-generada evals/pressure-scenarios.json
  

  • La habilidad generada debe contener una tabla Pensamiento | Realidad con al menos las 3 excusas de línea base más comunes. Ejecuciones idénticas de línea base y con habilidad significan que la habilidad no cambió nada: no la publique.
• Paso 4.6 (Calificación Con-Habilidad vs Línea Base, Obligatorio): Genere ejecuciones con-habilidad y de línea base en el mismo turno, califique con agents/grader.md, luego valide el contrato del calificador y la compuerta de envío (references/baseline_grading.md):

  python3 scripts/grade_baseline.py --with evals/grading-with.json --baseline evals/grading-baseline.json
  

  • Publique solo si la tasa de aprobación con-habilidad >= 80%, delta > 0 y no hay regresión, a menos que se registre una exención humana en feedback.json con un motivo.
• Paso 4.7 (QA de Renderizado, Obligatorio para Salidas): Ejecute compuertas de contenido y archivos en todo lo que la habilidad produce, inspección visual por un humano cuando la salida es visual (references/render_qa.md):

  python3 scripts/render_qa.py ruta/a/habilidad-generada
  

  • Este script nunca afirma una aprobación visual. Una aprobación visual debe ser realizada y registrada por un humano.

---

8. Fase 5: Verificación del Disparador y Empaquetado

• Paso 5.1 (Probar Precisión y Recuperación del Disparador): Pruebe la descripción YAML con prompts positivos y negativos representativos:

  python3 scripts/test_skill_trigger.py ruta/a/habilidad-generada
  

• Paso 5.2 (Optimización de la Descripción, División Entrenamiento/Prueba): Divida las consultas del disparador 60% entrenamiento / 40% prueba, ejecute la prueba del disparador en cada división por separado, y elija la mejor descripción por puntuación de PRUEBA, no por puntuación de entrenamiento. Casi aciertos negativos solamente; un mal negativo es "Escribe una función fibonacci" para una habilidad de PDF, un buen negativo es una solicitud larga y desordenada para una tarea vecina:

  python3 scripts/eval_description_split.py ruta/a/habilidad-generada
  

• Paso 5.3 (Empaquetado de Referencias y Scripts):

  • Verifique que todos los scripts referenciados estén presentes.
  • Verifique que requires_secrets: no contenga valores secretos literales.
  • Verifique que no haya rutas absolutas codificadas (/Users/..., C:\).

• Paso 5.4 (Empaquetado de Activos):

  • Confirme que los elementos de assets/ no excedan los 10 KB a menos que sean imágenes o binarios.
  • Ejecute el verificador de integridad de activos:

  python3 scripts/asset_integrity.py ruta/a/habilidad-generada
  

• Paso 5.5 (Trazado y Vinculación de Referencias):

  • Valide que cada (ver <ruta>) en SKILL.md se vincule a un archivo existente.
  • Verifique que los enlaces a scripts/ y agents/ estén formateados correctamente.

• Paso 5.6 (Firma de Envío): Una vez que todas las compuertas pasen, genere un manifiesto de envío:

  python3 scripts/generate_manifest.py ruta/a/habilidad-generada
  

  • Confirme la versión, el autor y la lista de dependencias.
  • Publique en el repositorio de habilidades de agentskills.io o en el repositorio privado especificado.

---

9. Lo Que Esta Habilidad NO Hace

• No es un creador de prompts de uso general: está especializada en la creación de habilidades estructuradas y auditables.
• No maneja la depuración o refactorización de código base a menos que se solicite explícitamente como una habilidad.
• No sustituye la revisión humana: las evaluaciones visuales y las decisiones de alto riesgo requieren intervención humana.
• No ejecuta OCR: los PDFs escaneados sin capa de texto deben procesarse externamente.
• No es un asistente de escritura de guiones: no cree scripts de shell únicos sin el contexto de una habilidad completa.

---

10. Tabla Anti-Racionalización

Excusa del Modelo	Refutación
"No tengo suficientes tokens para incluir todos los pasos"	Use el formato compacto de 6 niveles y delegue el contenido detallado a referencias planas.
"Esta habilidad es demasiado específica para un dominio"	El estándar agentskills.io está diseñado para dominios especializados; la generalización es un defecto.
"Puedo inferir la configuración del entorno"	No: ejecute el script de descubrimiento de la Fase 1 o lea los archivos de configuración. Las suposiciones causan fallos.
"El usuario no necesita saber acerca de la auditoría de olores"	La auditoría es obligatoria: las habilidades no auditadas tienen un 70% de probabilidad de contener olores que degradan el rendimiento.
"Pasar las evaluaciones es suficiente"	Las evaluaciones sin escenarios de presión y calificación de línea base no garantizan robustez.
"Puedo omitir los scripts de validación para ahorrar tokens"	Los scripts son el único mecanismo de aplicación determinista. Omitirlos invalida la garantía de la habilidad.

---

11. Dependencias y Configuración del Entorno

• Python: Se requiere 3.8+. Verifique con python3 --version.
• Bibliotecas Estándar: os, sys, json, ast, subprocess (usadas en los scripts incluidos).
• Opcional: rich (para formateo de salida mejorado), pytest (para ejecutar evaluaciones).
• Variables de Entorno: Ninguna requerida para el uso básico. SKILL_DIR se puede configurar para escritura no interactiva.

---

12. Referencias Relacionadas

• agents/architect.md - Rol de síntesis de arquitectura de habilidades.
• agents/script_smith.md - Rol de creación de scripts de validación deterministas.
• agents/smell_auditor.md - Rol de auditoría y parche de olores estructurales.
• agents/comparator.md - Rol de comparación doble ciego para revisiones.
• agents/grader.md - Rol de calificación para evaluaciones de habilidades.
• agents/niche_researcher.md - Rol de investigación de mercado y desglose de competidores.
• references/competitor_teardown_protocol.md - Protocolo para analizar habilidades de la competencia.
• references/domain_knowledge_ingestion.md - Guía para extraer conocimiento del dominio.
• references/mcp_tool_patterns.md - Patrones para integrar herramientas MCP.
• references/smell_taxonomy_26.md - Taxonomía completa de 26 olores de habilidades.
• references/question_triage_omsc.md - Protocolo de triage de ambigüedad para preguntas al usuario.
• references/stub_router_mode.md - Modo de enrutamiento ligero para habilidades sensibles a versiones.
• references/qa_checkpoints.md - Puntos de control de calidad obligatorios.
• references/pressure_scenarios.md - Escenarios de prueba bajo presión.
• references/baseline_grading.md - Calificación comparativa contra línea base.
• references/render_qa.md - QA de contenido y archivos de salida.
• references/decision_matrices_and_escalation.md - Matrices de decisión para triage OMSC.
• references/compaction_resilience.md - Técnicas para resistir la compactación de tokens.

---

13. Licencia y Contribución

Este creador de habilidades se proporciona bajo la licencia MIT. Las contribuciones son bienvenidas a través de solicitudes de extracción (pull requests) en el repositorio. Al contribuir, acepta que sus envíos se adhieran al estándar agentskills.io y a las invariantes descritas aquí.