CLI Creator

¿Qué hace CLI Creator?

Enrutador para construir y auditar herramientas CLI de Python de grado de producción, así como habilidades y plantillas relacionadas con CLI. Úsalo para decidir la forma de la CLI, mantener la superficie de comandos pequeña, preservar la instalabilidad y aplicar resultados de revisión. Esta habilidad se mantiene ligera: lee solo las referencias que necesitas.

Cuándo Usarlo

• Nueva CLI de Python o árbol de comandos.
• Refactorización, simplificación o limpieza de empaquetado de CLI.
• Revisión/auditoría de CLI, incluyendo UX, configuración, errores, caché y flujo de lanzamiento.
• Habilidad de agente, andamio o plantilla que se comporte como un paquete CLI.
• Verificación de instalación, wheel o comportamiento de console-script.

Selección del Tipo de CLI

Tipo	Sesgo
Utilidad centrada en comandos	Enrutador delgado, códigos de salida estrictos, salida JSON/plana.
Herramienta basada en configuración	Descubrimiento de configuración, precedencia, reproducibilidad.
Asistente interactivo	Flujo/máquina de estados, indicaciones, recuperación.
CLI híbrida	Árbol de comandos pequeño más orquestación reutilizable.
CLI de rendimiento intensivo	Importaciones diferidas, E/S acotada, caché/progreso.
CLI extensible/con complementos	Contrato de extensión estable y registro.

No fuerces una arquitectura de asistente en una herramienta centrada en comandos. No fuerces una forma de script único en un producto en crecimiento.

Reglas Fundamentales

• Prefiere la CLI más pequeña que resuelva el trabajo del usuario.
• Usa la ruta CLI mínima/YAGNI: si la herramienta tiene uno o dos comandos, sin estado persistente, sin red, sin complementos y sin credenciales, mantenla pequeña; no agregues Rich, Pydantic, platformdirs, capas de caché, doctor o registros de complementos a menos que resuelvan un problema inmediato.
• Mantén estables los nombres, banderas, códigos de salida, claves de configuración y modos de salida.
• Haz que los valores predeterminados sean útiles y seguros.
• Separa el enrutamiento, la lógica de dominio, E/S, configuración, persistencia, renderizado e integraciones.
• Mantén la salida de máquina editable con modo JSON o plano.
• Verifica que el comando README sea el console-script instalado.

Reglas de Carga de Referencias

Lee solo las referencias necesarias para la tarea:

• Creación o refactorización: references/creation-playbook.md.
• Revisión o auditoría: references/review-rubric.md y references/pitfalls-and-solutions.md.
• Detalles de implementación, empaquetado, seguridad, comportamiento multiplataforma, salida Rich, caché o proveedores de LLM: references/technical-best-practices.md.
• Para el mantenimiento de habilidades/paquetes, consulta las carpetas de gobernanza de la raíz del espacio de trabajo skill-ir/, evals/, scripts/, reports/ y registry/ cuando existan. Estas son ayudas de enrutamiento del lado del mantenedor, no están incluidas dentro de una copia de habilidad instalada.

No dupliques esas referencias aquí. Cárgalas solo cuando la tarea actual las necesite.

Flujo de Creación de Nueva CLI o Habilidad

1. Determina la forma del producto: quién lo ejecuta, bajo qué presión está y qué debe almacenarse en caché, recordarse u olvidarse.
2. Diseña la superficie de comandos con unos pocos comandos estables y ejemplos reales.
3. Elige la pila más pequeña que se ajuste.
   • Typer o Click para la mayoría de las CLI.
   • argparse solo para herramientas pequeñas compatibles con la biblioteca estándar.
4. Elige la arquitectura más pequeña que sobrevivirá las próximas dos versiones.
5. Implementa el bucle del producto: entrada, validación, ejecución, renderizado, persistencia, código de salida, sugerencia de recuperación.
6. Verifica antes de enviar.

Ejemplos de Superficie de Comandos

my-cli run
my-cli init
my-cli config show
my-cli doctor
my-cli cache clear
my-cli check PATH
my-cli fetch QUERY --json
my-cli export ID --output result.md

Reglas:

• Usa argumentos para objetos de dominio requeridos.
• Usa opciones para modificadores, modos de salida y comportamiento opcional.
• Proporciona --json o --format json para automatización.
• Proporciona --quiet, --verbose y --debug de manera consistente.
• Evita sorpresas de red o mutación en comandos que suenan de solo lectura.

Expectativas de Verificación

Siempre verifica la superficie de comandos, la ruta de instalación y la ruta del wheel cuando sean importantes:

• --help para el comando raíz y cada comando de nivel superior.
• Instalación limpia en un nuevo entorno.
• Ruta de configuración faltante o primera ejecución cuando la herramienta tiene configuración.
• Ruta de configuración no válida o error cuando la herramienta valida entrada.
• Ruta de éxito más modo JSON/editable cuando sea compatible.
• Actualización de caché y limpieza de caché cuando la herramienta tenga caché.
• Metadatos de empaquetado y console-script.
• Instalación del wheel desde fuera del repositorio cuando quieras confianza en la instalación.

Usa este paquete compacto cuando sea aplicable:

uv venv /tmp/cli-audit
. /tmp/cli-audit/bin/activate
uv pip install -e .
cli-creator-skill --help
cli-creator-skill install
uv build
uv pip install dist/*.whl
python -m pytest

Flujo de Revisión

Al auditar una CLI existente o una habilidad/plantilla relacionada con CLI:

Antes de revisar, lee:

• references/review-rubric.md
• references/pitfalls-and-solutions.md

Lee references/technical-best-practices.md cuando la auditoría toque detalles de implementación, empaquetado, seguridad, comportamiento multiplataforma, salida Rich, almacenamiento en caché o proveedores de LLM.

Luego:

1. Inspecciona la forma del repositorio: diseño del paquete, puntos de entrada de comandos, archivos de configuración, pruebas, documentación, CI.
2. Ejecuta ayuda: --help raíz y ayuda a nivel de comando.
3. Rastrea un comando exitoso desde el callback hasta el servicio de dominio y el renderizador.
4. Rastrea una ruta de fallo e inspecciona la calidad del error.
5. Verifica la precedencia de la configuración: banderas, env, configuración del proyecto, configuración del usuario, valores predeterminados.
6. Verifica la seguridad: secretos, ejecución de shell, manejo de rutas, configuración/complementos inseguros, telemetría, tiempos de espera de subprocesos, cadena de suministro de dependencias.
7. Verifica el rendimiento: importaciones de inicio, tiempos de espera de red, comportamiento de caché, descubrimiento de archivos.
8. Verifica la automatización: códigos de salida, salida JSON, separación de stdin/stdout/stderr, comportamiento sin TTY.
9. Verifica el empaquetado: versión de Python, dependencias, scripts, wheels, comandos README.
10. Puntúa cada área de la rúbrica con references/review-rubric.md.
11. Devuelve primero los hallazgos, luego las correcciones priorizadas.

Salida de Auditoría Requerida

La salida de la auditoría debe incluir estas secciones, en este orden:

**Hallazgos**

**Puntuaciones**

| Área | Puntuación | Notas |
|---|---:|---|

**Orden de Reparación**

**Brechas de Prueba**

**Comandos de Verificación**

Notas de Mantenimiento

• Mantén esta habilidad como un enrutador; coloca los detalles de implementación en las cuatro referencias.
• Mantén los ejemplos de comandos, los encabezados de auditoría y el paquete de verificación sincronizados con el lanzamiento del paquete.
• Para la gobernanza del lado del mantenedor, usa las carpetas skill-ir/, evals/, scripts/, reports/ y registry/ de la raíz del espacio de trabajo cuando estén presentes; no finjas que son parte de la habilidad instalada.

En Qué Ayuda Esta Habilidad

• Diseñar una nueva CLI de Python desde cero.
• Revisar una CLI existente en cuanto a UX, empaquetado, errores, configuración del modelo, almacenamiento en caché y mantenibilidad.
• Estructurar aplicaciones Typer, Click, argparse o híbridas.
• Construir flujos naturales de CLI de múltiples turnos sin hacer que los usuarios sientan que están llenando un formulario.
• Agregar diagnósticos, caché, memoria de perfil y flujos de configuración de primera ejecución cuando realmente sean necesarios.
• Revisar habilidades y plantillas relacionadas con CLI en cuanto a claridad de activación, integridad de referencias, plantillas de comandos, contratos de salida y estrategia de mantenimiento.

Base de Diseño

Esta habilidad destila la experiencia del mantenedor y los patrones de documentación oficial para empaquetado de Python, Typer, Click, Rich, uv, Ruff, Pydantic e integración con proveedores de LLM. No incluye código ni instrucciones de repositorios de terceros no oficiales.