Communitygithub.com

AdarGit008/baseline-skill

El skill /baseline para Claude Code — un verificador de preparación de proyectos sin dependencias (69 reglas). Instálalo en ~/.claude/skills/baseline.

¿Qué es baseline-skill?

Este skill proporciona un estándar de preparación de proyectos comprobable, compuesto por 69 reglas, cada una respaldada por una verificación que un ejecutor Node sin dependencias realiza sobre un repositorio *en reposo*. Los bloqueos fallan en CI (código de salida 1); los juicios que un script no puede hacer se resuelven mediante un libro de registro de aprobaciones fechado. El objetivo principal es: *no confíes en una promesa escrita — haz que algo la verifique.* El skill es compatible con Claude Code y su uso principal es como herramienta de línea de comandos. El usuario invoca el skill con diferentes modos: `score` (por defecto) para ejecutar las verificaciones y obtener un informe de preparación, `init` para configurar el baseline en un repositorio, `fix` para corregir fallos encontrados, y `explain` para obtener explicaciones detalladas de reglas individuales. El ejecutor (`check.mjs`) carga las reglas desde `rules.json` y requiere solo Node ≥ 18 y git. Utiliza perfiles (`core`, `service`, `advanced`) para adaptar las verificaciones al tipo de proyecto. Los resultados se presentan agrupados por categoría, destacando bloqueadores (FAIL) y advertencias (WARN), junto con un porcentaje de preparación general. Las reglas manuales (SIGN-OFF) requieren un juicio humano registrado en un libro de aprobaciones, evitando falsas automatizaciones.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add AdarGit008/baseline-skill

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

project-baseline

Un estándar de preparación comprobable: 69 reglas, cada una respaldada por una verificación que un ejecutor Node sin dependencias realiza sobre un repositorio en reposo. Los bloqueos fallan en CI (código de salida 1); los juicios que un script no puede hacer se resuelven mediante un libro de registro de aprobaciones fechado. El objetivo principal: no confíes en una promesa escrita — haz que algo la verifique.

El conjunto de herramientas se encuentra junto a este archivo: check.mjs (ejecutor), rules.json (las 69 reglas), config.example.json, templates/, README.md (guía de inicio rápido), REFERENCE.md (referencia completa: tabla de reglas, categorías, diagramas de arquitectura, configuración de CI) y GLOSSARY.md (definiciones en lenguaje sencillo de términos de DevOps/cadena de suministro).

Resuelve primero el directorio del skill. $SKILL_DIR a continuación significa la ruta absoluta del directorio que contiene este SKILL.md — resuélvela a una ruta concreta antes de ejecutar cualquier comando (no pases la cadena literal $SKILL_DIR al shell). Normalmente es ~/.claude/skills/baseline. check.mjs carga rules.json desde su propio directorio, por lo que ambos deben permanecer juntos; invoca siempre el ejecutor mediante su ruta absoluta (node "<abs>/check.mjs" …) en lugar de copiarlo a otro lado. El ejecutor solo necesita Node ≥ 18 y git; si falta node, indícaselo al usuario en lugar de adivinarlo.

Al ser invocado

Determina la intención a partir de las palabras del usuario y elige un modo. Por defecto, usa score si no se especifica.

Modo: score (por defecto) — "ejecutar baseline", "/baseline", "verificar este repositorio"

  1. Selecciona el repositorio objetivo: una ruta explícita en la solicitud, o el directorio de trabajo actual. Confirma que parece un repositorio (tiene un manifiesto o .git).
  2. Ejecuta el ejecutor (legible para humanos):
    node "$SKILL_DIR/check.mjs" --repo <destino>
    
    • Añade --no-exec si NO debes ejecutar el comando de bootstrap/prueba del repositorio (BUILD-05) — por ejemplo, repositorio no confiable, sin tiempo para ejecutar pruebas, o el comando no está configurado. Prefiere ejecutarlo cuando sea seguro, ya que BUILD-05 es la verificación principal.
    • Añade --profile advanced si el usuario quiere las reglas expertas (SBOM, análisis de código, pruebas de mutación, integridad de símbolos, escaneo de vulnerabilidades de dependencias, cobertura mínima). El perfil service se activa automáticamente para project_type=service.
    • Añade --json cuando quieras analizar los resultados programáticamente en lugar de mostrar la puntuación.
  3. Presenta el resultado al usuario, comenzando con los bloqueadores (estos fallan en CI), luego las advertencias que vale la pena corregir. Agrupa por categoría. No muestres las 69 filas completas — resume: % de preparación, número de bloqueadores y los FAIL/advertencias notables específicos con su detalle de una línea. Ofrece corregir o preparar el andamiaje.

Modo: init — "configurar baseline aquí", "adoptar el estándar", "preparar andamiaje baseline"

  1. Copia el conjunto de herramientas en el repositorio (sugiere tools/baseline/), o haz referencia a él en su lugar.
  2. Prepara los artefactos, solo si faltan (nunca sobrescribas sin preguntar):
    cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json
    cp "$SKILL_DIR/templates/CLAIMS.json"   <repo>/docs/CLAIMS.json      # solo si el repositorio hace afirmaciones externas
    cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md    # si no existe un documento de estado
    mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json
    
  3. Edita baseline.config.json según la realidad del repositorio: establece project_type, bootstrap_command (el comando de instalación+prueba para BUILD-05) y makes_external_claims (falso omite las reglas CLAIM-*). Las claves opt-in *_globs (frescura/generados/fundamento) permanecen vacías hasta que el repositorio adopte esas convenciones.
  4. Muéstrales la configuración de CI del README.md y convierte el trabajo baseline en una verificación obligatoria (esa es la regla BUILD-06).
  5. Ejecuta una primera puntuación.

Modo: fix — "corregir los fallos del baseline", "poner esto en verde"

  1. Puntúa primero. Para cada bloqueador/advertencia que el usuario quiera abordar, aplica el campo fix de la propia regla (léelo de rules.json) como ediciones concretas en el repositorio — añade la licencia faltante, fija la acción a un SHA, añade el .env a .gitignore y rota el secreto, añade la prueba negativa, etc.
  2. Para las reglas manual (aprobación), no falsifiques una verificación — ayuda al usuario a hacer el juicio (radio de explosión, revisión de arte previo, cuña/foso) y registra una entrada fechada en .project-baseline/signoff.json.
  3. Vuelve a puntuar para confirmar.

Modo: explain — "¿qué verifica SEC-03?", "¿por qué falló CTX-05?"

Lee la regla de rules.json (cada una tiene title, rationale, fix, source y la verificación check) y explícala claramente, además de lo que el ejecutor buscó realmente. Para jerga desconocida (SBOM, SLSA, procedencia, libro de registro de aprobaciones, …), GLOSSARY.md en este directorio tiene definiciones en lenguaje sencillo.

Cómo decide el ejecutor (para que puedas interpretar las líneas de detalle)

  • PASS / FAIL / WARN / SIGN-OFF / SKIP por regla. Solo los FAIL de tipo blocker establecen el código de salida 1.
  • SKIP significa que la regla no aplicaba: project_type incorrecto (n/a for <type>), un perfil desactivado (profile 'advanced' off), una función opt-in no adoptada, o nada que verificar. Un SKIP nunca cuenta en contra de la preparación.
  • Perfiles: core siempre se ejecuta; service se ejecuta automáticamente cuando project_type=service; advanced se ejecuta solo con --profile advanced o profiles:["advanced"] en la configuración.
  • Las afirmaciones son opt-in: CLAIM-* solo se ejecutan si existe un registro de afirmaciones o makes_external_claims:true está establecido explícitamente. Un repositorio sin registro de afirmaciones no es penalizado.
  • La configuración se autodetecta de forma sensata; baseline.config.json en la raíz del repositorio la anula. Las claves están documentadas en config.example.json.
  • El ejecutor no tiene dependencias (Node ≥ 18 + git) y es resistente a fallos: una regla cuya verificación no puede evaluarse se degrada a SKIP, nunca interrumpe la ejecución.

Notas

  • Nunca presentes una advertencia como un bloqueador ni viceversa — la gravedad está en rules.json y en la salida del ejecutor.
  • Prefiere ejecutar BUILD-05 realmente (omite --no-exec) cuando el repositorio sea confiable y el comando de bootstrap esté configurado — una verificación principal en verde es la señal más fuerte.
  • La justificación completa, la tabla de reglas, las descripciones de categorías, los diagramas de arquitectura y el fragmento de CI están en REFERENCE.md de este directorio — léelo si el usuario quiere profundizar.

Skills relacionados