Codex vs Claude Code Skills: Configuración, Ajustes y Cómo Compartir Skills Entre Ambos

Name

Soren Atelier

Updated on 10/2/2026

Las "skills" se están convirtiendo rápidamente en la unidad portátil de reutilización para agentes de programación con IA. Una skill es una carpeta que agrupa instrucciones, scripts opcionales y archivos de referencia en algo que un agente puede descubrir y aplicar de manera confiable. Si trabajas con más de una herramienta de programación con IA, probablemente ya hayas sentido la fricción de mantener configuraciones separadas para cada una.

OpenAI Codex y Anthropic Claude Code admiten skills, y ambos se basan en el estándar abierto Agent Skills. Codex indica explícitamente que sus skills se construyen sobre ese estándar y utilizan "progressive disclosure" para gestionar el contexto de manera eficiente. Claude Code también sigue el estándar Agent Skills mientras añade sus propias extensiones como controles de invocación, subagentes e inyección dinámica de contexto.

Esa base compartida es lo que hace posible un flujo de trabajo de "escribir una vez, usar en ambas herramientas" — si tienes cuidado con dónde residen las skills, cómo difieren los ajustes y qué campos de frontmatter son portátiles. Esta guía desglosa cada diferencia práctica y te muestra cómo compartir una única skill entre ambos agentes.

Comparación Rápida: Skills de Codex vs Skills de Claude Code

Modelo Mental: Mismo SKILL.md, Ecosistemas Diferentes

Ambas herramientas comparten la idea central: un directorio con un archivo SKILL.md que contiene frontmatter YAML (name, description) e instrucciones en Markdown. El agente lee los metadatos para decidir cuándo usar la skill y carga las instrucciones completas cuando la activa. Las diferencias están en las rutas de descubrimiento, los formatos de configuración y las funcionalidades avanzadas.

Qué Significa "Skills" para Codex

Las skills de Codex son directorios que contienen un SKILL.md obligatorio y opcionalmente scripts/, references/, assets/, además de un archivo opcional agents/openai.yaml para metadatos de interfaz y dependencias (como servidores MCP).

Codex carga primero los metadatos de la skill y solo carga las instrucciones completas si decide utilizarla. Esto se denomina progressive disclosure — mantiene las ventanas de contexto ligeras inyectando solo lo que el agente realmente necesita.

Qué Significa "Skills" para Claude Code

Las skills de Claude Code también se basan en SKILL.md y funcionan como comandos slash reutilizables. Claude puede invocarlas automáticamente cuando son relevantes, o puedes ejecutarlas directamente mediante /skill-name.

Claude Code fusionó explícitamente los comandos slash personalizados con las skills:

• .claude/commands/review.md y .claude/skills/review/SKILL.md ambos crean /review
• Las skills añaden archivos de soporte, control de invocación y carga automática cuando son relevantes

Cómo Crear e Instalar una Skill en Codex

1. Estructura del Directorio de la Skill

Como mínimo, una skill de Codex necesita:

my-skill/
  SKILL.md

Una skill completa puede incluir:

my-skill/
  SKILL.md
  scripts/
    run-check.sh
  references/
    CHECKLIST.md
  assets/
    diagram.png
  agents/
    openai.yaml

El SKILL.md debe incluir name y description en su frontmatter YAML.

2. Dónde Descubre Codex las Skills

Codex escanea múltiples ubicaciones con un orden de precedencia definido:

Codex también soporta explícitamente carpetas de skills con symlinks y sigue el destino del symlink durante el escaneo.

3. Usar Herramientas Integradas para Skills

Codex proporciona dos asistentes integrados:

• $skill-creator — genera la estructura de un nuevo directorio de skill con el formato correcto
• $skill-installer — descarga e instala skills desde fuentes externas

4. Habilitar o Deshabilitar Skills en la Configuración

Codex puede deshabilitar una skill sin eliminarla añadiendo entradas bajo [[skills.config]] en la configuración TOML:

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Reinicia Codex después de cambiar la configuración.

5. Formato de Configuración de Codex

La configuración de Codex reside en archivos TOML con un orden de precedencia claro:

Flags CLI > perfiles > config de proyecto (.codex/config.toml) > config de usuario (~/.codex/config.toml) > config de sistema > valores por defecto

Las skills pueden controlarse mediante estos ajustes, y esos ajustes pueden tener alcance por proyecto.

Cómo Crear e Instalar una Skill en Claude Code

1. Estructura del Directorio de la Skill

Las skills de Claude Code son directorios con SKILL.md como punto de entrada. Los archivos adicionales son opcionales:

my-skill/
  SKILL.md
  template.md
  examples/
    sample.md
  scripts/
    validate.sh

Referencia los archivos de soporte desde tu SKILL.md para que Claude sepa qué contienen y cuándo cargarlos.

2. Dónde Descubre Claude Code las Skills

Claude Code tiene múltiples ámbitos con precedencia:

Claude Code también soporta descubrimiento anidado en monorepos: si estás editando packages/frontend/..., también busca en packages/frontend/.claude/skills/.

3. El Formato de SKILL.md: YAML + Markdown

Las skills de Claude Code tienen dos partes — frontmatter YAML e instrucciones en Markdown:

---
name: explain-code
description: Explains code with visual diagrams and analogies.
---
 
When explaining code:
1) Start with an analogy
2) Draw an ASCII diagram
3) Walk step-by-step
4) Highlight a gotcha

El name se convierte en el /slash-command, y description ayuda a Claude a decidir cuándo cargarla automáticamente.

4. Funcionalidades Extendidas de Skills en Claude Code

Claude Code extiende el estándar con funcionalidades no disponibles en Codex:

Esta es la diferencia práctica más importante: las skills de Claude pueden comportarse como mini-flujos de trabajo con preprocesamiento y subagentes, mientras que las skills de Codex enfatizan el empaquetado de instrucciones, recursos y scripts con carga progresiva.

5. Formato de Configuración de Claude Code

Los ajustes de Claude Code están en JSON, con alcance por gestionado/usuario/proyecto/local, y son editables mediante /config en el REPL interactivo:

• Usuario: ~/.claude/settings.json
• Proyecto: .claude/settings.json
• Sobreescrituras locales: .claude/settings.local.json

Diferencias Clave: Desglose Lado a Lado

Rutas de Descubrimiento

Codex:        .agents/skills/  →  $HOME/.agents/skills/  →  /etc/codex/skills/
Claude Code:  .claude/skills/  →  ~/.claude/skills/       →  enterprise managed

Esta es la razón principal por la que compartir skills requiere symlinks o un repositorio compartido.

Formatos de Configuración

UX de Activación

• Codex: lista /skills y mención con $ en CLI/IDE; selección implícita desde description
• Claude Code: invocación /skill-name; carga automática basada en description

Extensiones Específicas de Cada Herramienta

• Codex: agents/openai.yaml opcional para metadatos de interfaz y declaraciones de dependencias (ej., servidores MCP)
• Claude Code: campos de frontmatter como disable-model-invocation, context: fork, preprocesamiento de comandos (!`…`), paso de argumentos

El Núcleo Compartido: Estándar Abierto Agent Skills

Si quieres que una skill funcione tanto en Codex como en Claude Code, ancla el contenido en la especificación Agent Skills. Esto es lo que requiere la especificación:

Campos de Frontmatter Requeridos

Codex requiere ambos campos. Claude Code es más flexible (puede asignar el name por defecto del directorio), pero para reutilización entre agentes, trata ambos como obligatorios.

Referencias a Archivos

La especificación recomienda referenciar archivos usando rutas relativas desde la raíz de la skill:

See [the reference guide](references/REFERENCE.md) for details.
 
Run the extraction script:
scripts/extract.py

Mantén las referencias a un solo nivel de profundidad para evitar cadenas anidadas complejas.

Cómo Compartir una Skill Entre Ambos Agentes Usando Symlinks

El patrón más limpio para usar una skill en ambas herramientas:

1. Mantener un único repositorio o carpeta canónica de skills
2. Crear symlinks de esas carpetas de skills hacia la ruta de descubrimiento de cada agente

Configuración Paso a Paso

Supón que guardas las skills compartidas en ~/shared-agent-skills/:

~/shared-agent-skills/
  code-review/
    SKILL.md
    references/
      REVIEW_CHECKLIST.md
  test-writer/
    SKILL.md
    scripts/
      run-tests.sh

Vincular en un proyecto para Codex:

mkdir -p .agents/skills
ln -s ~/shared-agent-skills/code-review .agents/skills/code-review
ln -s ~/shared-agent-skills/test-writer .agents/skills/test-writer

Vincular en el mismo proyecto para Claude Code:

mkdir -p .claude/skills
ln -s ~/shared-agent-skills/code-review .claude/skills/code-review
ln -s ~/shared-agent-skills/test-writer .claude/skills/test-writer

O vincular a nivel de usuario para todos los proyectos:

# Codex (ámbito de usuario)
ln -s ~/shared-agent-skills/code-review $HOME/.agents/skills/code-review
 
# Claude Code (ámbito de usuario)
ln -s ~/shared-agent-skills/code-review ~/.claude/skills/code-review

Notas de Compatibilidad con Symlinks

Si el listado de /skills de Claude Code no muestra tu skill vinculada, aún puedes invocarla directamente por nombre.

Una Plantilla Portátil de SKILL.md

Aquí tienes una plantilla compatible con la especificación que funciona en ambos agentes:

---
name: code-review
description: >
  Perform a structured code review for correctness, security,
  performance, and readability. Use when asked to review a
  diff, PR, or when preparing changes for merge.
license: MIT
compatibility: >
  Intended for coding agents (Codex, Claude Code) in Git repos.
  Requires read access to the repo.
metadata:
  owner: platform-team
  version: "1.0.0"
---
 
# Code Review Skill
 
## Inputs
- A diff, PR link, or list of changed files.
- The relevant module/service context.
 
## Process
1. Identify the goal of the change and expected behavior.
2. Review for correctness (edge cases, error handling).
3. Review for security (authz/authn, injection risks, secrets).
4. Review for performance (N+1 queries, hot paths, allocations).
5. Review for maintainability (naming, structure, tests).
6. Summarize findings with:
   - Must-fix items
   - Suggestions
   - Positive notes
 
## Reference checklist
See [our checklist](references/REVIEW_CHECKLIST.md) for the full list.

Añadir Metadatos Específicos de Codex (Opcional)

Añade agents/openai.yaml para metadatos de interfaz y dependencias de Codex. Otras herramientas lo ignorarán:

# agents/openai.yaml
display_name: "Code Review"
icon: "🔍"
dependencies:
  mcp_servers:
    - github

Añadir Funcionalidades Específicas de Claude Code (Opcional)

Para flujos de trabajo exclusivos de Claude, puedes añadir frontmatter extendido en una skill con alcance específico de Claude o en una sobreescritura dentro de .claude/:

---
name: code-review
description: Structured code review with security focus.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff*)
context: fork
---

Mejores Prácticas para Skills Multi-Agente

1. Mantén el Contenido Portátil en la Carpeta Compartida

Limítate a los campos de la especificación Agent Skills (name, description) y usa references/ con enlaces relativos para documentos extensos y checklists. Esto asegura que ambos agentes puedan analizar y utilizar la skill.

2. Aísla las Funcionalidades Avanzadas de Cada Herramienta

• Para Claude Code: context: fork, preprocesamiento con ! y allowed-tools son potentes pero específicos de Claude
• Para Codex: agents/openai.yaml es específico de Codex pero está limpiamente separado en su propio archivo

Ninguna herramienta falla con campos desconocidos — simplemente los ignora. Pero por claridad, mantener las funcionalidades específicas de cada herramienta en archivos o sobreescrituras dedicadas es una mejor práctica.

3. Usa un Repositorio Git Compartido para las Skills

shared-agent-skills/          # Repositorio Git
├── code-review/
│   ├── SKILL.md
│   └── references/
├── test-writer/
│   ├── SKILL.md
│   └── scripts/
├── setup-links.sh            # Script instalador de symlinks
└── README.md

Un simple setup-links.sh puede automatizar la creación de symlinks:

#!/bin/bash
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
 
# Vincular en el ámbito de usuario de Codex
mkdir -p "$HOME/.agents/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.agents/skills/$name"
done
 
# Vincular en el ámbito de usuario de Claude Code
mkdir -p "$HOME/.claude/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.claude/skills/$name"
done
 
echo "Skills vinculadas para Codex y Claude Code."

4. Versiona Tus Skills

Incluye un campo version en los metadatos y etiqueta los releases en tu repositorio compartido de skills. Cuando una skill cambia su comportamiento, incrementar la versión ayuda a los equipos a rastrear qué cambió y cuándo.

Si utilizas agentes de programación con IA como Codex o Claude Code para flujos de trabajo de análisis de datos, herramientas como PyGWalker (opens in a new tab) pueden convertir tus DataFrames en visualizaciones interactivas — y puedes construir una skill que integre PyGWalker en el kit de herramientas de tu agente para exploración de datos bajo demanda.

Preguntas Frecuentes

¿Qué es el estándar abierto Agent Skills?

El estándar abierto Agent Skills es una especificación que define cómo los agentes de programación con IA descubren y utilizan paquetes de skills reutilizables. Establece un formato común — un directorio con un archivo SKILL.md que contiene frontmatter YAML e instrucciones en Markdown — para que las skills sean portátiles entre diferentes herramientas de agentes.

¿Puedo usar el mismo SKILL.md tanto en Codex como en Claude Code?

Sí. Ambos agentes se basan en el estándar Agent Skills y reconocen archivos SKILL.md con frontmatter name y description. El requisito clave es colocar la skill en la ruta de descubrimiento de cada agente (.agents/skills/ para Codex, .claude/skills/ para Claude Code), lo cual puedes hacer con symlinks desde una única ubicación canónica.

¿Cuáles son las principales diferencias entre las skills de Codex y las de Claude Code?

Las diferencias principales son las rutas de descubrimiento (.agents/skills/ vs .claude/skills/), los formatos de configuración (TOML vs JSON) y las funcionalidades de extensión. Claude Code añade bifurcación de contexto con subagentes, preprocesamiento de comandos shell y controles de acceso a herramientas. Codex añade agents/openai.yaml para metadatos de interfaz y dependencias de servidores MCP. El formato base de SKILL.md es compatible en ambos.

¿Funcionan los symlinks para compartir skills entre agentes?

Codex soporta explícitamente carpetas de skills con symlinks y sigue los destinos. Claude Code también funciona con symlinks para invocación, aunque el comando de listado /skills puede no detectar skills con symlinks en algunas versiones. Aún puedes invocar skills vinculadas por nombre incluso si no aparecen en la lista.

¿Qué campos de frontmatter son obligatorios para skills portátiles?

La especificación Agent Skills requiere name (debe coincidir con el directorio padre, minúsculas con guiones, 1-64 caracteres) y description (ayuda a los agentes a decidir cuándo usar la skill). Tanto Codex como Claude Code soportan estos campos. Campos adicionales como license, compatibility y metadata son opcionales pero recomendados.

¿Dónde debo colocar las skills para acceso a nivel de usuario?

Para Codex, coloca las skills en $HOME/.agents/skills/. Para Claude Code, usa ~/.claude/skills/. Ambas ubicaciones hacen que las skills estén disponibles en todos los proyectos sin necesidad de configuración por repositorio.

Conclusión

Las skills de Codex y Claude Code comparten más ADN de lo que sus diferentes ecosistemas sugieren. Ambos se basan en el estándar abierto Agent Skills, ambos usan SKILL.md como punto de entrada y ambos soportan carga progresiva basada en las descripciones de las skills. Las diferencias prácticas — rutas de descubrimiento, formatos de configuración y funcionalidades de extensión — son reales pero manejables.

La mejor estrategia es mantener una única fuente de verdad para tus skills, ceñirte a los campos requeridos por la especificación (name y description) para el núcleo portátil, y usar symlinks para que cada agente vea la misma carpeta de skills. Mantén las funcionalidades avanzadas específicas de cada herramienta (la bifurcación de subagentes de Claude, los metadatos YAML de Codex) en sus respectivos archivos de extensión. De esta manera, obtienes portabilidad sin sacrificar las capacidades avanzadas de ninguna de las dos herramientas.