lggarrison/agent-skills - Configuración de repositorio

Configuración de repositorio

Un repositorio nuevo necesita la misma base cada vez: una licencia, una forma de reportar problemas de seguridad, un README, plantillas que hagan útiles los PRs y los issues, y un CI que ejecute las mismas comprobaciones que un contribuyente ejecuta localmente. Esta habilidad es una lista de verificación para esa base y una forma de trabajar a través de ella.

Las reglas del repositorio son lo primero

Lee lo que el repositorio ya tiene antes de añadir nada: AGENTS.md / CLAUDE.md, CONTRIBUTING.md, archivos existentes .github/, el manifiesto del paquete y sus scripts, y cualquier configuración de CI. Donde establezcan una convención (rama por defecto, licencia, herramientas, ubicaciones de archivos), síguela. Nunca sobrescribas un archivo existente para que coincida con una plantilla aquí. Extiéndelo, o déjalo y menciona la brecha.

Flujo de trabajo

1. Definir la tarea

• Iniciar: un repositorio nuevo o casi vacío. Trabaja toda la lista de verificación.
• Completar: a un repositorio existente le falta parte de ella. Añade solo lo que falta.
• Auditar: reporta lo que falta o es débil, y no cambies nada.

2. Hacer inventario

Enumera qué archivos de la lista de verificación existen, y lee el manifiesto (package.json, pyproject.toml, go.mod, Cargo.toml, etc.) para el lenguaje, los scripts, y si el proyecto se publica. Encuentra la rama por defecto con git remote show origin o gh repo view --json defaultBranchRef. No le preguntes al usuario nada que puedas aprender de esta manera.

3. Preguntar sobre las decisiones clave

Estas son decisiones del usuario. Pregunta una vez, en una ronda corta, y recomienda donde la evidencia lo respalde:

• Licencia, y el nombre del titular de los derechos de autor.
• Contacto de seguridad: reporte privado de vulnerabilidades de GitHub, una dirección de correo electrónico, o ambos.
• Contacto del código de conducta, si se añade uno.
• Rama base de PR, si no es la rama por defecto.
• Publicado o no: en un registro de paquetes, o como artefacto de release.
• Matriz de CI: qué sistemas operativos y versiones de runtime soportar.

4. Escribir los archivos

Trabaja la lista de verificación de arriba a abajo, y omite las secciones que no apliquen.

• Obtén el texto canónico; no lo recuerdes. Obtén el texto de la licencia de gh api licenses/<spdx-id> --jq .body (por ejemplo mit o apache-2.0), luego completa el año y el titular. Obtén un código de conducta de su fuente oficial, como el Contributor Covenant.
• Adapta las plantillas. Comienza desde templates/. Reemplaza cada <placeholder>, y cambia los comandos a los que existan en este repositorio. Una plantilla que enumera un script que el repositorio no tiene es peor que ninguna plantilla.
• Una lista de comprobaciones. La lista de verificación de la plantilla de PR, CONTRIBUTING.md, el hook de pre-commit y CI deben nombrar los mismos comandos. Cuando uno cambie, cambia los otros.
• Pregunta antes de cambiar configuraciones. La protección de ramas, los conjuntos de reglas y el reporte privado de vulnerabilidades son configuraciones del repositorio, no archivos. Propónlos y aplícalos solo cuando el usuario esté de acuerdo.

5. Verificar

• Cada comando nombrado en una plantilla, hook o trabajo de CI se ejecuta localmente y pasa.
• No queda ningún <placeholder> en ningún archivo.
• Los formularios de issues y los flujos de trabajo son YAML válido. Los formularios de issues solo aparecen en la rama por defecto, así que revísalos allí después de fusionar.
• Los enlaces resuelven, incluyendo la URL de la política de seguridad.
• Las comprobaciones de formato y lint del propio repositorio pasan en los nuevos archivos.

6. Reportar

Di qué añadiste, qué dejaste intacto y por qué, las configuraciones del repositorio que propusiste, y cualquier decisión clave aún abierta.

Lista de verificación

R es requerido, rec es recomendado y opt es opcional.

Herramientas

• R git, y el runtime del lenguaje y el gestor de paquetes.
• rec Un gestor de versiones de runtime (nvm, fnm, pyenv, etc.) que coincida con el archivo de versión fijada.
• rec gh, autenticado con gh auth login, para mantenedores.

Legal y comunitario

• R LICENSE.
• R SECURITY.md: versiones soportadas, cómo reportar de forma privada y qué pueden esperar los reportadores después de reportar.
• rec CONTRIBUTING.md: configuración, las comprobaciones a ejecutar, convenciones de ramas y commits, y cómo se revisan los PRs.
• rec CODE_OF_CONDUCT.md, con un contacto de aplicación real.
• rec CHANGELOG.md en formato Keep a Changelog.

Documentación

• R README.md: qué es, cómo instalarlo, un ejemplo de uso mínimo y enlaces a CONTRIBUTING.md, SECURITY.md y la licencia.
• opt AGENTS.md: el punto de entrada neutral para agentes de codificación. Proporciona los comandos a ejecutar y las reglas a seguir, y enlaza a otros documentos en lugar de repetirlos.
• opt RELEASING.md, para proyectos publicados. Ver Publicación.

Higiene del editor y Git

• R .gitignore para el lenguaje, la salida de compilación y los archivos de entorno local.
• rec .gitattributes con * text=auto eol=lf, para que los finales de línea no cambien entre sistemas operativos.
• rec .editorconfig para charset, nueva línea final y sangría.

Plantillas y automatización de GitHub

Si el repositorio no está en GitHub, usa los equivalentes del anfitrión.

• rec .github/PULL_REQUEST_TEMPLATE.md. Ver Plantillas.
• rec Formularios de issues en .github/ISSUE_TEMPLATE/: bug_report.yml, feature_request.yml y un config.yml que desactive issues en blanco y dirija los reportes de seguridad al canal privado. Ver Plantillas.
• rec .github/dependabot.yml, con una entrada por cada ecosistema de paquetes que use el repositorio, más github-actions.
• R .github/workflows/ci.yml, ejecutando las mismas comprobaciones que la plantilla de PR en cada PR y cada push a la rama por defecto.
• opt .github/release.yml, para agrupar notas de release generadas por etiqueta.
• opt .github/workflows/release.yml, solo para proyectos publicados.
• rec Protección de rama o un conjunto de reglas en la rama por defecto que requiera CI. Esto es una configuración, así que pregunta primero.

Node.js y TypeScript

Omita esta sección para otros lenguajes y aplique las mismas ideas con las herramientas de ese ecosistema: una versión de runtime fijada, un formateador, un linter, un ejecutor de pruebas, un solo comando "verificar todo" y una matriz de CI.

Runtime y metadatos

• rec .nvmrc, y engines.node en package.json, que coincidan entre sí.
• R package.json repository, homepage, bugs, license y author.
• rec "type": "module" para ESM nativo.

TypeScript (solo proyectos TypeScript)

• R typescript y un tsconfig.json, con un npm run build que compile.
• No conviertas un proyecto JavaScript a TypeScript. Para un proyecto nuevo, si usar TypeScript es decisión del usuario.

Formato y lint

• rec Prettier (.prettierrc.json, .prettierignore) y una configuración plana de ESLint.
• rec Scripts lint, lint:fix, format y format:check.

Pruebas unitarias

• R Un npm test que ejecute las pruebas unitarias.
• rec Vitest, con pruebas junto al código (src/**/*.test.ts) y fixtures compartidos en test/.

Pruebas de extremo a extremo (opt, para proyectos con UI o flujos de navegador)

• rec @playwright/test, un playwright.config.ts y pruebas en e2e/.
• rec Un script npm run test:e2e.
• rec playwright-report/, test-results/ y blob-report/ en .gitignore.
• rec Un trabajo de CI que instale navegadores con npx playwright install --with-deps y suba el informe cuando una prueba falle.
• opt Para una CLI sin navegador, ejecuta pruebas de extremo a extremo a través de una configuración separada de Vitest.

Hooks de Git (solo desarrollo local)

• rec Husky con un hook pre-commit que ejecute lint-staged.
• rec Un script prepare que omita instalar Husky cuando CI esté configurado o NODE_ENV=production, para que las instalaciones en CI y producción no fallen.
• opt Un hook pre-push que ejecute las pruebas unitarias.

Puerta de calidad

• rec Un script, como check, que ejecute lint, format:check, las pruebas unitarias, la compilación y las pruebas de extremo a extremo en ese orden. CI y los contribuyentes lo ejecutan.
• rec Una matriz de CI en los sistemas operativos y las versiones de Node.js soportadas.

Publicación

Para proyectos publicados en un registro de paquetes. Estos son opt para todo lo demás.

• rec Una lista blanca "files" en package.json (o .npmignore), verificada con npm pack --dry-run.
• rec Un script prepublishOnly que ejecute la compilación.
• rec Publicación desde CI con npm Trusted Publishing (OIDC, id-token: write), para que no se almacene ningún token de larga duración como secreto.
• rec RELEASING.md que cubra cómo se eligen las versiones (semver), cómo se etiqueta un release, las comprobaciones que bloquean una etiqueta incorrecta y cómo revertir.

Plantillas

Archivo	Copiar a
templates/PULL_REQUEST_TEMPLATE.md	.github/PULL_REQUEST_TEMPLATE.md
templates/ISSUE_TEMPLATE/bug_report.yml	.github/ISSUE_TEMPLATE/bug_report.yml
templates/ISSUE_TEMPLATE/feature_request.yml	.github/ISSUE_TEMPLATE/feature_request.yml
templates/ISSUE_TEMPLATE/config.yml	.github/ISSUE_TEMPLATE/config.yml

Los marcadores de posición se escriben <como-esto>. Por ejemplo, reemplaza <runtime-version-command> con node --version, python --version o go version. Los otros comandos en las plantillas son ejemplos de un proyecto Node.js. Reemplázalos con los del repositorio.