honest-cv

CVs honestos y seguros para ATS a partir de un inventario de habilidades que tú verificas: las habilidades que te faltan nunca se imprimen, cada PDF es revisado por dos extractores de texto, y las mejoras de nivel requieren tu confirmación. Adapta CVs a ofertas de empleo, revisa cartas de presentación, redacta textos para LinkedIn, prepara entrevistas y realiza seguimiento de solicitudes. Funciona localmente, para cualquier profesión, en inglés y español.

GitHub

Documentación

honest-cv

CVs honestos y compatibles con ATS, adaptados a cada puesto, generados por tu agente de IA. honest-cv es un servidor MCP, una CLI y una habilidad de Claude Code. Mantiene una única fuente de verdad sobre tu experiencia y la convierte en PDF y DOCX para cada tipo de puesto. Nunca afirma una habilidad que no tienes.

Leer en español

Demo: skill checklists including your own, scoring a job post, a verified build, a cover letter that refuses a skill the person lacks, LinkedIn texts and logging the application

Por qué

Muchos CVs que no reciben respuestas no fallan por el diseño. Fallan por la orientación y por detalles que rompen silenciosamente la extracción de texto. La IA facilita el problema opuesto: un modelo llenará felizmente tu CV con palabras clave que no puedes defender en una entrevista. honest-cv está construido alrededor de tres ideas:

El código impone la honestidad, no un prompt. Cada habilidad tiene un nivel. Una habilidad en nivel de familiaridad siempre se etiqueta como tal, y una habilidad que no tienes nunca se imprime. Subir un nivel requiere evidencia escrita y tu confirmación, que el servidor te pide directamente. El modelo no puede confirmar en tu nombre.
Las carencias se miden contra tu propio inventario. Para cada palabra clave que pide una oferta de empleo, honest-cv te dice cuál de los tres casos es:
- la tienes, pero este CV no la muestra;
- solo la conoces a nivel de familiaridad;
- no la tienes.
La seguridad ATS se comprueba en cada compilación. Cada PDF pasa por dos extractores de texto (pypdf y pdfminer.six). La compilación verifica que el texto es de una columna, no tiene ligaduras, mantiene cada fecha en la línea de su puesto, sigue el orden de lectura correcto e incluye cada viñeta.

El servidor es determinista y no necesita clave API. El modelo del cliente MCP dirige la conversación; honest-cv valida, compila, verifica y mide. Mantiene tu perfil en una carpeta de tu máquina y nunca lo envía a ningún sitio: consulta Privacidad para saber qué hace tu cliente de IA con él.

A generated one-page CV for the fictional Ada Example

Inicio rápido

honest-cv necesita uv. Typst y las fuentes se incluyen dentro del paquete, así que no hay nada más que instalar. Funciona en Linux (glibc) en x86_64 y ARM64, macOS en Intel y Apple Silicon, y Windows en x64. Alpine Linux y Windows en ARM no son compatibles, porque el paquete typst no publica wheels para ellos.

Claude Code

claude mcp add honest-cv -- uvx honest-cv serve --profile ~/cv-profile

Para instalar también la habilidad, que guía la entrevista y la adaptación:

mkdir -p ~/.claude/skills/honest-cv
curl -fsSL https://raw.githubusercontent.com/JesusCabreraReveles/honest-cv/master/skills/honest-cv/SKILL.md \
  -o ~/.claude/skills/honest-cv/SKILL.md

Luego sigue Tu primer CV, paso a paso.

Cursor

Añade esto a ~/.cursor/mcp.json, o a .cursor/mcp.json en un proyecto:

{
  "mcpServers": {
    "honest-cv": {
      "command": "uvx",
      "args": ["honest-cv", "serve", "--profile", "/absolute/path/to/cv-profile"]
    }
  }
}

Claude Desktop

Edita claude_desktop_config.json:

en macOS, ~/Library/Application Support/Claude/;
en Windows, %APPDATA%\Claude\.

Añade el mismo bloque mcpServers que en el ejemplo de Cursor y reinicia la aplicación. Si la aplicación no encuentra uvx, usa su ruta absoluta (which uvx).

Cómo confirma cada cliente una mejora de habilidad

Subir el nivel de una habilidad requiere tu propia confirmación, que el servidor pide mediante la elicitación MCP. No todos los clientes la soportan todavía:

Cliente	Dónde confirmas
Claude Code	En el chat: un formulario con un campo "no / sí" por mejora, hasta 10 a la vez. Solo se guardan las que respondes "sí"; Decline no guarda nada.
Claude Desktop	En una terminal. El servidor rechaza el cambio y te da el comando a ejecutar: `uvx honest-cv skill <profile> "<name>" <level> --evidence "..."`.
Otros clientes	En el chat si soportan elicitación; si no, en una terminal como arriba.

Tu primer CV, paso a paso

Este recorrido usa Claude Code; cualquier cliente MCP funciona igual, solo cambia la configuración.

1. Instala uv y añade honest-cv. Solo una vez. En macOS o Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh        # Windows: see docs.astral.sh/uv
claude mcp add honest-cv -- uvx honest-cv serve --profile ~/cv-profile

~/cv-profile es la carpeta donde vivirá tu perfil. No tiene que existir todavía, y no debería estar dentro de un repositorio público. Instala también la habilidad (Claude Code arriba).

2. Empieza la entrevista. Abre Claude Code en cualquier carpeta (claude) y escribe, en tu propio idioma, "Entrevístame para mi CV", o ejecuta /mcp__honest-cv__interview. El asistente mantiene tu idioma durante toda la conversación. Puedes responder por voz con el dictado de tu sistema (en macOS: Ajustes del Sistema → Teclado → Dictado): te lee nombres y números antes de guardarlos, porque el dictado los oye mal. Así va:

Tú: Entrevístame para mi CV.

Asistente: La carpeta ~/cv-profile no existe todavía. ¿La creo? … Toda la entrevista puede llevar unas horas, pero todo se guarda sobre la marcha. Una primera sesión con tus datos de contacto, tus dos puestos más recientes y la lista de habilidades es suficiente para un primer CV. ¿Tienes una exportación de datos de LinkedIn o un JSON Resume para empezar?

Importa, si puedes (opcional). Descarga la exportación de datos de LinkedIn (consulta Importar) y dale al asistente la ruta del ZIP. Tus puestos, educación y logros entran, y las habilidades llegan sin nivel para que las marques.
Contacto, puestos y educación. Pregunta de pocas en pocas y te lee nombres y números antes de guardar. Luego pregunta una vez sobre certificaciones, cursos y cualquier cosa que hayas escrito.
Logros, puesto por puesto. Para cada puesto: qué hizo el equipo, qué hiciste tú y qué cambió, con números. Redacta una viñeta y la guarda solo después de que apruebes la redacción.
Habilidades. Ofrece una lista de verificación, p. ej. backend-jvm + engineering-lead, o la tuya propia para cualquier profesión. Abre ~/cv-profile/checklist.md en tu editor, pon P, L, F o X en cada línea, añade dónde la usaste después de " — ", guarda y dile al asistente "hecho". Pide la evidencia que falta, en grupos. Luego un formulario te pide confirmar las mejoras: solo se guarda lo que respondes "sí".
Tus mayores logros. Un logro suele cubrir varias habilidades. Luego pregunta sobre tus habilidades P principales que ningún logro muestra todavía; el resto puede esperar a una oferta de empleo.

3. Compila tu primer CV. El asistente propone una variante por cada tipo de puesto al que te postulas (por ejemplo "plataforma" o "gerente de ingeniería"): título, resumen y qué viñetas mostrar. Una vez que la apruebas:

Tú: Compila mi CV de plataforma en inglés y español.

El PDF y el DOCX caen en ~/cv-profile/out/, ya verificados para seguridad ATS. Sin un cliente de IA, lo mismo es uvx honest-cv build ~/cv-profile -v platform -l en.

4. Adáptalo a una oferta de empleo. Pega la oferta, o ejecuta /mcp__honest-cv__tailor_for_job:

Tú: Aquí hay una oferta de empleo: (pégala). ¿Qué tan bien encajo y qué debería cambiar?

Obtienes la cobertura de cada variante, las palabras clave que faltan divididas en la tienes pero este CV no la muestra, solo familiaridad y no la tienes, más las que marcaste en tu lista pero aún no has respaldado con evidencia (pregunta dónde las usaste), una variante adaptada para aprobar y la compilación. Luego puede redactar una carta de presentación, que check_claims verifica antes de compilarse, y registrar la solicitud con el texto de la oferta y qué preparar para la entrevista. Cuando consigues la entrevista, "ayúdame a preparar la entrevista" redacta preguntas probables con respuestas de tus propios logros.

5. Vuelve cualquier día. Di "continuemos mi entrevista de CV": empieza desde lo que falta. Cuando necesites actualizar tu perfil de LinkedIn, di "actualiza mi LinkedIn".

Tu perfil

Un perfil es una carpeta con cuatro archivos YAML. Crea uno con honest-cv init ~/cv-profile, o deja que el prompt interview lo rellene contigo. Mantenlo fuera de repositorios públicos.

Archivo	Qué contiene
`profile.yaml`	Datos de contacto, puestos, educación, certificaciones, publicaciones, cursos e idiomas.
`bullets.yaml`	Un conjunto de logros, cada uno con un `id`, un `role` y `tags`.
`skills.yaml`	Tu inventario de habilidades, con niveles y evidencia.
`variants.yaml`	Un plan de CV por tipo de puesto. Una variante puede heredar de otra con `extends:`.

Cualquier texto puede ser una sola cadena o una cadena por idioma: {en: ..., es: ...}. Los CVs se pueden compilar en inglés y en español.

Nivel	Significado	En el CV
`P`	Usado en producción en un trabajo	Se muestra
`L`	Tu propio proyecto o laboratorio	Se muestra
`F`	Familiaridad	Solo en la línea etiquetada "Familiaridad"
`X`	No la tienes	Nunca se muestra, pero se registra para que los informes de carencias sean honestos

Listas de verificación de habilidades

Registrar docenas de habilidades una pregunta a la vez es lento. Una lista de verificación es un archivo Markdown que marcas en tu editor, una letra por línea:

## Messaging and streaming
evidence: Payments platform at Acme, 2020–2026
- [P] Kafka — reconciliation flow, 2M events a day · years: 6 · last year: 2026
- [F] RabbitMQ — a workshop and the official tutorials
- [X] NATS

El texto después de " — " es la evidencia, y una línea evidence: bajo un encabezado cubre esa sección. Las líneas sin evidencia nunca se guardan: vuelven como pendientes, y tu asistente te pregunta sobre ellas en grupos. Las mejoras se confirman una vez para todo el archivo.

Las listas de verificación vienen en inglés y español (--lang es): los nombres en español son sinónimos de los ingleses, así que una habilidad que marcas en español sigue coincidiendo con una oferta en inglés.

honest-cv checklist list                                     # backend-jvm, platform-sre, ...
honest-cv checklist new ~/cv-profile backend-jvm engineering-lead
honest-cv checklist apply ~/cv-profile ~/cv-profile/checklist.md

Cualquier profesión funciona. Las listas integradas cubren software (backend, frontend, móvil, datos, plataforma/SRE, QA, seguridad, ML/IA, embebido, desarrollo de juegos, arquitectura, liderazgo de ingeniería) y análisis de datos/BI, gestión de productos y proyectos, diseño UX, marketing, ventas, soporte al cliente, finanzas y contabilidad, recursos humanos, cadena de suministro, enfermería y enseñanza. Una plantilla es solo una lista Markdown en este formato: guarda la tuya (o una que alguien compartió) en ~/cv-profile/checklists/ y aparece en checklist list y se combina con las demás en checklist new, que también acepta una ruta. Una plantilla puede declarar sinónimos, como same: Work Breakdown Structure = WBS, y la puntuación del puesto, las carencias y la verificación de la carta los usan, junto con sus nombres de habilidades. Empieza desde examples/checklists/event-planning.md. También puedes aplicar un archivo que marcaste tú mismo, en inglés o español (años, último uso). Cuando terminas, honest-cv nombra las habilidades P y L que ningún logro muestra, y tu asistente te pide un ejemplo real de cada una.

honest-cv checklist list ~/cv-profile                        # yours too, e.g. accounting
honest-cv checklist new ~/cv-profile accounting engineering-lead

Se aceptan nuevas listas para otros tipos de puestos: consulta CONTRIBUTING.md.

Consulta examples/ada/ para un perfil completo y ficticio con tres variantes, una oferta de empleo y sus palabras clave.

Privacidad

honest-cv en sí no hace llamadas de red. Sin cuentas, sin telemetría, sin claves API. Tu perfil es una carpeta de archivos YAML en tu máquina, y el motor de PDF y las fuentes se ejecutan localmente. Puedes comprobarlo: cada comando funciona con la red apagada.
Tu cliente de IA es otro asunto. Lo que el modelo del cliente lea a través de las herramientas va al proveedor de ese modelo, bajo los términos del proveedor, como cualquier otra cosa que compartas en un chat. Eso incluye tus habilidades, viñetas y el texto de tus CVs.
Algunos clientes copian archivos a la nube. Para editar archivos directamente, Claude Desktop puede pedir acceso a la carpeta del perfil y decir que los archivos salen de tu dispositivo. Las herramientas de edición de honest-cv hacen que eso sea innecesario: rechaza la solicitud y pide al asistente que use las herramientas.
Ejecutarlo en un servicio alojado lo saca de tu máquina. Directorios como Glama ofrecen desplegar honest-cv en sus servidores o probarlo en el navegador. Funciona, pero entonces tu perfil y tus CVs viven en ese servicio, bajo sus términos. Para tus datos reales, ejecútalo en tu propio ordenador con uvx honest-cv.
Si no quieres que nada salga de tu máquina, usa solo la CLI (build, verify, score, skill) y edita los archivos YAML tú mismo.

Importa lo que ya tienes

honest-cv import lee un archivo JSON Resume o la exportación de datos de LinkedIn (Configuración → Privacidad de datos → Descargar tus datos, un ZIP de CSVs, o su carpeta si tu navegador lo descomprimió). Solicita el archivo completo: el básico, que se ofrece al elegir archivos, solo tiene tu titular y resumen, sin roles. Contacto, roles, educación, certificaciones, idiomas y los logros de cada rol se incorporan a tu perfil; con un titular y un resumen también crea una primera variante, para que build funcione de inmediato.

Solo añade lo que falta en tu perfil y nunca sobrescribe. Prueba --dry-run primero.
Los logros importados se etiquetan como imported: revisa su redacción.
Las habilidades llegan sin nivel, porque ninguno de los formatos indica si usaste una habilidad en producción. Van a imported-skills.md, una lista de verificación para que marques.

El perfil "Guardar como PDF" de LinkedIn cambia el diseño sin aviso, por lo que no se analiza: con un cliente MCP, el prompt import_linkedin_pdf lee su texto y propone cada sección para que la apruebes.

Haz seguimiento de tus solicitudes

honest-cv apps mantiene un registro en applications.yaml, dentro de tu carpeta de perfil: qué variante y archivos se enviaron a cada empresa, y cada estado con su fecha (draft, applied, interview, offer, rejected, withdrawn). Registrar la misma empresa y rol nuevamente lo actualiza. Con un cliente MCP, tu asistente ofrece registrar una solicitud después de crear el CV o la carta, y list_applications señala aquellas sin novedades durante dos semanas. Guarda una copia de cada archivo que enviaste en sent/, ya que la próxima compilación sobrescribe out/, y el texto de la oferta de empleo en posts/, ya que los enlaces caducan, y qué preparar para la entrevista: pregúntale a tu asistente "¿qué necesitaba preparar para Acme?".

Cuando consigas la entrevista, di "ayúdame a preparar la entrevista de Acme" (o ejecuta el prompt interview_prep). Para cada palabra clave de la oferta guardada, honest-cv presenta tu nivel, tu evidencia y las viñetas que lo respaldan, comenzando por las del CV que enviaste. Tu asistente redacta las posibles preguntas con respuestas STAR tomadas solo de esas viñetas, respuestas honestas para lo que solo conoces a nivel de familiaridad o no tienes, y preguntas para hacerles. Las notas que apruebes se guardan en prep/. Sin un cliente de IA: honest-cv apps prep ~/cv-profile acme_sre -k "Kafka,Scala".

honest-cv linkedin convierte una variante en los textos de LinkedIn, cada uno dentro de su límite: el titular (tu título y hasta cinco habilidades de producción), Acerca de (el resumen y las viñetas de impacto), una descripción por puesto a partir de sus viñetas, y la lista de habilidades. Los escribe en un archivo Markdown para copiar. Las habilidades son solo P y L: LinkedIn no puede etiquetar familiaridad, por lo que las habilidades F quedan fuera, y las habilidades X nunca aparecen. Con un cliente MCP, el prompt linkedin_profile pule la redacción y la verifica con check_claims.

Exportación

Para ir en la otra dirección, honest-cv export escribe una variante como JSON Resume para otras herramientas y sitios de CV, con las mismas reglas que el CV: las habilidades X nunca aparecen, y las habilidades F solo en un grupo "Familiaridad" con ese nivel.

Cartas de presentación

El prompt cover_letter redacta una carta de una página para una oferta de empleo a partir de tus propias viñetas. Antes de que se compile, check_claims lee el texto contra tu perfil:

Los problemas bloquean la compilación: una habilidad que marcaste como X, o una habilidad de familiaridad presentada como experiencia ("Uso Rust en producción" cuando Rust es F; "Estoy familiarizado con Rust" está bien).
Las advertencias son para que las revises: una tecnología que ni tu inventario ni tus viñetas muestran, o un número que no aparece en ninguna parte de tu perfil. Si es verdad, regístralo primero; si no, se elimina de la carta.

La carta usa las fuentes del CV y pasa las mismas verificaciones ATS. Sin un cliente de IA, escríbela en un archivo de texto (párrafos separados por líneas en blanco) y usa honest-cv letter check y letter build.

CLI

Ejecuta cualquier comando con uvx honest-cv ..., o instálalo una vez con uv tool install honest-cv para escribir solo honest-cv.

honest-cv init ~/cv-profile                        # create the profile templates
honest-cv build ~/cv-profile -v backend -l en -l es # PDF + DOCX, verified on every build
honest-cv verify any-cv.pdf --text                  # check any PDF, even one made elsewhere
honest-cv score ~/cv-profile -k "Kubernetes,Go" -p "Rust"   # coverage per variant, with gaps
honest-cv skill ~/cv-profile "Rust" L --evidence "CLI tool on GitHub"  # asks you to confirm
honest-cv import ~/cv-profile linkedin-export.zip --dry-run         # or resume.json
honest-cv export ~/cv-profile -v backend -l en                       # JSON Resume
honest-cv apps log ~/cv-profile --company Acme --role "SRE" -s applied -v platform
honest-cv apps list ~/cv-profile                                     # latest first, with counts
honest-cv apps prep ~/cv-profile acme_sre -k "Kafka,Scala"           # what backs each keyword, for the interview
honest-cv linkedin ~/cv-profile -v platform -l en                    # texts to paste into LinkedIn
honest-cv remove skill ~/cv-profile "Kafka"                          # asks you to confirm
honest-cv letter check ~/cv-profile letter.txt -k "Kubernetes,Go"     # claims your profile doesn't support
honest-cv letter build ~/cv-profile letter.txt --company Acme --role "Platform Engineer" -l en
honest-cv serve --profile ~/cv-profile              # the MCP server, over stdio

verify funciona en cualquier PDF. Usa --text para ver exactamente qué extrae un analizador. Su verificación single_column también detecta un defecto común: una fecha alineada a la derecha, que los analizadores separan de su rol.

Herramientas y prompts de MCP

Nombre	Qué hace
`init_profile`	Crea una carpeta de perfil con plantillas comentadas.
`get_inventory`	Devuelve tus habilidades, agrupadas por nivel, con años y evidencia.
`set_skill`	Añade o cambia una habilidad. Para subir su nivel necesita evidencia y te pide confirmación.
`set_skills`	Añade o cambia varias habilidades a la vez. Las mejoras se confirman con una pregunta que lista cada cambio.
`checklist_list`	Lista las listas de verificación integradas.
`checklist_new`	Fusiona las listas de verificación integradas en un archivo, precargado desde tu inventario.
`checklist_apply`	Guarda las habilidades marcadas en una lista de verificación y devuelve las líneas que aún necesitan evidencia.
`add_bullet`	Añade un logro al grupo.
`remove_skill`, `remove_bullet`, `remove_role`, `remove_publication`	Elimina definitivamente y quita cada uso en las variantes. Un rol con viñetas necesita `with_bullets`. Los clientes preguntan antes de ejecutarlos.
`set_contact`	Cambia los datos de contacto: nombre, correo, teléfono, ubicación, enlaces.
`set_profile_details`	Reemplaza la lista de certificaciones, la lista de cursos y la línea de idiomas hablados.
`upsert_role`	Añade un rol en orden de fechas, o cambia campos de uno existente.
`upsert_education`	Añade o cambia una entrada de educación.
`upsert_publication`	Añade o cambia un libro, artículo o documento que la persona escribió. Cada variante muestra todos, o los que lista.
`save_variant`	Añade o reemplaza una variante. Cada referencia se verifica antes de guardar.
`list_variants`	Lista las variantes después de la herencia, con sus textos de viñetas y las viñetas que ninguna variante usa.
`build_cv`	Genera un PDF y/o DOCX y lo verifica.
`verify_pdf`	Ejecuta las verificaciones ATS en cualquier PDF y devuelve su texto extraído.
`score_job`	Mide la cobertura de palabras clave de cada variante. El cliente extrae las palabras clave.
`gap_report`	Agrupa las palabras clave faltantes según lo que puedes hacer honestamente con cada una.
prompt `interview`	Llena tu inventario y grupo de viñetas, una pregunta a la vez.
`check_claims`	Verifica cualquier texto contra tu perfil: bloquea habilidades X y familiaridad vendida como experiencia, señala lo que el perfil no muestra.
`build_letter`	Genera una carta de presentación en PDF y DOCX, una página, con las verificaciones ATS del CV. Se niega mientras `check_claims` encuentre problemas.
prompt `tailor_for_job`	Puntúa las variantes, explica las brechas, adapta una variante y reconstruye.
prompt `cover_letter`	Redacta una carta para una oferta de empleo a partir de tus viñetas, verifica sus afirmaciones y la compila.
`import_profile`	Importa JSON Resume o una exportación de datos de LinkedIn, añadiendo solo lo que falta. Para un PDF de LinkedIn devuelve el texto.
`export_json_resume`	Exporta una variante como JSON Resume; las habilidades X nunca aparecen y las habilidades F mantienen su etiqueta.
`log_application`	Registra una solicitud (empresa, rol, variante de CV, archivos enviados, el texto de la oferta, qué preparar) o un nuevo estado, con su fecha.
`linkedin_profile`	Titular de LinkedIn, Acerca de, descripciones de puesto y habilidades (solo P y L) a partir de una variante, dentro de los límites de LinkedIn.
`list_applications`	Lista las solicitudes, las más recientes primero, con un conteo por estado y las que no tienen novedades durante 14+ días.
`interview_prep`	Para una solicitud: la oferta guardada y, por palabra clave, tu nivel, evidencia y las viñetas que lo respaldan. Guarda las notas de preparación.
prompt `import_linkedin_pdf`	Convierte el PDF de "Guardar como PDF" de LinkedIn en un perfil, sección por sección, con tu aprobación.
prompt `linkedin_profile`	Pule los textos de LinkedIn de una variante sin añadir afirmaciones, verificado con `check_claims`.
prompt `interview_prep`	Prepara una entrevista: posibles preguntas, respuestas STAR de tus propias viñetas, respuestas honestas para las brechas.

Garantías ATS

La plantilla las aplica. verify las verifica en cada compilación, y el conjunto de pruebas se ejecuta en CI en Linux, macOS y Windows:

Una columna. Sin tablas de diseño, imágenes, iconos, encabezados o pies de página.
Ligaduras y kerning desactivados, sin separación silábica, y términos como "CI/CD", URLs y correos nunca se dividen entre líneas.
El orden de lectura es igual al orden de origen. Las fechas están en la misma línea que su rol.
El texto es extraíble tanto por pypdf como por pdfminer.six, y ambos coinciden.
Las fuentes (Carlito, compatible métricamente con Calibri) están incrustadas y son idénticas en cada máquina.

Desarrollo

uv sync
uv run pytest
uv run honest-cv build examples/ada -l en -l es

El .mcp.json del repositorio registra honest-cv-dev con el perfil ficticio, para que Claude Code en esta carpeta pueda usar tu copia de trabajo. Consulta CONTRIBUTING.md.

Licencia

MIT. La fuente Carlito incluida está bajo la SIL Open Font License; consulta src/honest_cv/render/fonts/OFL.txt.