Skills de Claude Code: cómo crear una propia herramienta

⏱️ Lectura: 16 min

Un agente de Claude Code puede refactorizar un monorepo entero y escribir la migración de base de datos sola, pero si necesita que hagas clic en un diálogo de permisos se queda mudo frente a una terminal que nadie está mirando. Las Skills de Claude Code resuelven justo ese tipo de bache, y el repositorio big-arrow-on-the-screen, publicado bajo licencia MIT, es un caso real para mostrarlo: dibuja una flecha enorme sobre cualquier ventana de macOS para señalar qué botón apretar.

📑 En este artículo

1. TL;DR
2. ¿Qué son las Skills de Claude Code?
3. Por qué importa: el problema que resuelve big-arrow-on-the-screen
4. Cómo funciona una skill por dentro: la anatomía de SKILL.md
   1. Cómo decide el modelo cuál cargar
5. Ejemplo real: la skill big-arrow paso a paso
6. Cómo crear tu propia extensión de agente
7. Cómo empezar: instalar y probar tu propia skill
8. Comparativa: Skills vs MCP vs subagentes
9. Casos de uso reales
10. Errores comunes y buenas prácticas
11. Profundizando: permisos, seguridad y el modelo de ejecución
12. Preguntas frecuentes
    1. ¿Las Skills de Claude Code funcionan igual en Codex?
    2. ¿Hace falta permiso de macOS para que un script dibuje sobre la pantalla?
    3. ¿Esta extensión de agente puede reemplazar un servidor MCP?
    4. ¿Dónde se instalan las skills de un proyecto frente a las globales?
    5. ¿Hace falta saber Swift para escribir una skill como la de big-arrow?
13. Referencias
    1. 📚 Artículos relacionados

Lo interesante no es la flecha. Es el mecanismo que la conecta con el agente sin tocar una sola línea del modelo. Este artículo usa ese proyecto real como caso de estudio para explicar qué es una skill, cómo la descubre el modelo y cómo construir tu propia extensión de agente desde cero.

TL;DR

• Un archivo SKILL.md con YAML al inicio alcanza para que Claude Code descubra y active una skill nueva.
• big-arrow-on-the-screen combina un binario Swift sin daemon con una skill instalable via bigarrow install-skill.
• Una descripción vaga en el frontmatter nunca gana la selección del modelo, sin importar qué tan útil sea la skill.
• Un script de shell o cualquier binario ejecutable puede ser el cuerpo real de una skill, sin SDK propietario.
• MCP conecta al agente con sistemas externos con estado; una skill resuelve una tarea puntual sin levantar un servidor.

¿Qué son las Skills de Claude Code?

Las Skills de Claude Code son paquetes de instrucciones, metadatos y scripts opcionales que extienden lo que el agente puede hacer sin modificar su código base. Cada skill vive en una carpeta con un archivo SKILL.md. El modelo lee primero su descripción y, solo si aplica a la tarea pedida, carga el resto del contenido.

Pensalo como una biblioteca de manuales en el escritorio de un empleado nuevo. Nadie memoriza los cuarenta manuales el primer día, pero cuando un cliente pregunta algo puntual, el empleado busca el manual correcto, lo lee y recién ahí actúa. Claude Code hace lo mismo: mantiene una lista corta de nombres y descripciones, y abre el contenido completo de una skill solo cuando el pedido del usuario calza con esa descripción.

Ese mecanismo se llama progressive disclosure (revelación progresiva). Evita que cada skill instalada consuma espacio de contexto todo el tiempo; el costo de tener cien skills instaladas es, en la práctica, cien líneas de nombre y descripción, no cien documentos completos cargados de entrada. La carpeta puede incluir, además del SKILL.md, cualquier script o archivo que las instrucciones necesiten. Esa es la segunda capa de revelación progresiva: no solo se decide qué skill cargar, sino qué partes de esa skill vale la pena leer para la tarea puntual.

Por qué importa: el problema que resuelve big-arrow-on-the-screen

Un agente que automatiza tareas reales en una computadora tarde o temprano choca con un paso que solo un humano puede, o debe, autorizar: un diálogo de permisos del sistema, una verificación en dos pasos, un CAPTCHA, una firma. El agente encuentra el botón correcto, pero no puede ni debe apretarlo.

El README del proyecto lista varios de estos casos reales: un asistente que pide hacer clic en Permitir sin saber si estás mirando la terminal; una guía de tres pasos en Keynote; elegir la pestaña correcta entre catorce abiertas en Chrome; ayudar a un familiar a guardar un PDF por videollamada. En todos los casos, la solución no es que el agente actúe por vos. Es que te señale exactamente dónde actuar.

Por diseño, esta extensión de agente nunca hace clic, nunca tipea y nunca captura pantalla: solo dibuja. Es una ventana transparente, superpuesta a todo, que ignora los clics del mouse y deja tu foco de teclado intacto. Según el repositorio, dibujar esa flecha no requiere ningún permiso especial de macOS, y el binario completo es un solo ejecutable Swift sin demonio en segundo plano, sin ícono en la barra de menú, sin cuenta y sin telemetría.

Cómo funciona una skill por dentro: la anatomía de SKILL.md

Toda skill arranca con un bloque YAML delimitado por tres guiones, con al menos dos campos obligatorios: name y description. Después del segundo delimitador viene el cuerpo en Markdown, instrucciones en lenguaje natural que el modelo sigue como si fueran parte de su propio prompt, pero solo cuando decide que esa skill aplica.

La skill más simple posible tiene dos archivos. Primero, el SKILL.md:

---
name: hola-mundo
description: Saluda al usuario y dice la hora del sistema. Usar cuando pida un saludo, la hora, o quiera probar que las skills funcionan.
---

# Hola mundo

Cuando te saluden o pidan la hora, ejecuta `bash saludar.sh`
sin argumentos y devolve la salida tal cual, sin texto extra.

Y el script que ese archivo invoca, saludar.sh, en la misma carpeta:

#!/usr/bin/env bash
echo "Hola desde tu primera skill. Hora del sistema: $(date '+%H:%M:%S')"

Al pedirle a Claude Code «saludame» con esa skill instalada, la respuesta incluye una línea como esta, con la hora real del momento en que corrió:

Hola desde tu primera skill. Hora del sistema: 14:32:07

flowchart TD
A["~/.claude/skills/"] --> B["hola-mundo/"]
B --> C["SKILL.md"]
B --> D["saludar.sh"]
A --> E["big-arrow/"]
E --> F["SKILL.md"]
E --> G["bin/bigarrow"]

Las dos skills conviven en la misma carpeta de nivel superior sin pisarse: cada una es un directorio independiente, y Claude Code las recorre a todas antes de decidir cuál usar.

Cómo decide el modelo cuál cargar

La decisión se basa exclusivamente en el campo description. El modelo compara el pedido del usuario contra esa frase corta de cada skill instalada, y recién después de elegir una abre el SKILL.md completo junto con los scripts que necesite.

sequenceDiagram
participant U as Usuario
participant A as Agente
participant S as Carpeta de skills
U->>A: pide algo en lenguaje natural
A->>S: lee nombre y descripcion de cada skill
S-->>A: lista corta de candidatas
A->>S: carga el SKILL.md completo de la mejor candidata
S-->>A: instrucciones y scripts
A->>U: ejecuta el script y responde

Ejemplo real: la skill big-arrow paso a paso

La instalación de big-arrow-on-the-screen es exclusiva de macOS, vía Homebrew:

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill

El segundo comando copia el SKILL.md y las instrucciones de uso del CLI a la carpeta de skills de Claude Code, y de Codex si está instalado, según describe el repositorio. A partir de ahí, pedirle al agente que señale un botón ya no requiere escribir el comando a mano: el agente lo arma solo a partir de las instrucciones de la skill.

Un ejemplo tomado del README muestra cómo se ve ese comando una vez armado:

bigarrow point --element "Allow" --app "System Settings" \
 --text "Franz, click Allow: Ghostty may control your Mac"

Ese comando dibuja una flecha apuntando al botón «Allow» dentro de System Settings, con un rótulo de texto al lado. El clic real sigue siendo tuyo; Big Arrow solo señala.

Cómo crear tu propia extensión de agente

La diferencia entre la skill «hola mundo» de arriba y una skill útil de verdad suele ser una sola cosa: que el script reciba argumentos en vez de hacer siempre lo mismo. El siguiente ejemplo envuelve el comando wc de Unix para contar líneas y palabras de un archivo.

---
name: contar-palabras
description: Cuenta lineas y palabras de un archivo de texto local. Usar cuando el usuario pida el tamano, el largo o cuantas palabras tiene un archivo.
---

# Contar palabras

Cuando pidan el tamano de un archivo, ejecuta:

wc -l -w "$1"

wc siempre devuelve primero las lineas y despues las palabras,
sin importar en que orden pediste las opciones.

Si le pedís a Claude Code «¿cuántas palabras tiene notas.txt?» con esa skill instalada, el agente corre el comando y la salida literal se ve así:

  12  54 notas.txt

Doce líneas, cincuenta y cuatro palabras. La misma estructura, nombre, descripción y un comando envuelto, sirve para casi cualquier CLI que ya tengas instalado: un linter interno, una herramienta propia, o el binario de bigarrow con flags distintos según el caso.

Cómo empezar: instalar y probar tu propia skill

La única dependencia es tener Claude Code instalado y autenticado en tu máquina. No hace falta ningún SDK ni toolchain adicional para una skill basada en shell. En macOS y Linux, los comandos son idénticos:

mkdir -p ~/.claude/skills/hola-mundo
cd ~/.claude/skills/hola-mundo
cat > SKILL.md <<'EOF'
---
name: hola-mundo
description: Saluda al usuario y dice la hora del sistema. Usar cuando pida un saludo o quiera probar que las skills funcionan.
---

# Hola mundo

Ejecuta `bash saludar.sh` y devolve la salida tal cual.
EOF
cat > saludar.sh <<'EOF'
#!/usr/bin/env bash
echo "Hola desde tu primera skill. Hora del sistema: $(date '+%H:%M:%S')"
EOF
chmod +x saludar.sh

En Windows, los mismos tres elementos (la carpeta, el SKILL.md y el script) se crean a mano desde un editor de texto dentro de %USERPROFILE%\.claude\skills\hola-mundo, sin necesidad de heredocs de bash.

💡 Tip: escribí la descripción como la ficha de un buscador interno, con los sinónimos que un usuario real tipearía («saludo», «hora», «probar skill»), porque es la única parte que el modelo lee siempre, aunque nunca llegue a abrir el resto del archivo.

Para confirmar que funcionó, abrí una sesión nueva de Claude Code y escribí «saludame». Si la skill cargó, la respuesta trae la hora real devuelta por el script; si Claude contesta con un saludo genérico sin esa hora, la descripción no fue lo bastante específica como para que la elija. No hay, por ahora, un comando que liste qué skills están cargadas en memoria en ese instante. Lo que sí podés verificar con certeza es que el archivo existe y el YAML es válido, revisando a mano que el bloque entre los dos --- tenga name y description.

Comparativa: Skills vs MCP vs subagentes

Antes de escribir la próxima skill vale la pena ubicar las Skills de Claude Code frente a las otras dos formas de extender un agente: un servidor MCP y un subagente con su propio contexto.

flowchart LR
A["Agente"] -->|lee localmente| B["Skill en disco"]
A -->|protocolo MCP| C[("Servidor MCP")]
C --> D[("Base de datos o API externa")]
B --> E["Script o binario local"]

Casos de uso reales

Más allá de señalar botones, el mismo patrón de skill sirve para envolver cualquier herramienta de línea de comandos en lenguaje natural.

• Soporte a usuarios no técnicos: guiar a un familiar a guardar un PDF o aceptar un permiso durante una videollamada, sin dar acceso remoto a la máquina.
• Documentación visual: grabar un tutorial señalando cada control en una app compleja, en vez de escribir «el botón de arriba a la derecha».
• Depuración de coordenadas: apuntar a las coordenadas que devuelve una API de accesibilidad y mirar si caen donde deberían, antes de automatizar un clic real.
• Herramientas internas envueltas en lenguaje natural: convertir un linter, un script de deploy o un generador de reportes en algo que el equipo invoca charlando, no memorizando flags.

Errores comunes y buenas prácticas

• Descripción vaga: una description como «ayuda con archivos» casi nunca gana la selección frente a skills con descripciones específicas; escribila pensando en las palabras exactas que un usuario real tipearía.
• Scripts sin permiso de ejecución: olvidar el chmod +x rompe la skill en el primer uso, con un error de permiso denegado que no dice nada sobre el SKILL.md.
• Una skill que hace demasiado: si el cuerpo mezcla cinco tareas distintas, dividila en varias skills con nombres propios; el modelo elige mejor entre opciones angostas que entre una genérica.
• Rutas absolutas del autor original: un script que asume una ruta fija del autor falla en cualquier otra máquina; usá rutas relativas a la carpeta de la skill.
• Dar por hecho la dependencia: big-arrow necesita macOS y Homebrew; documentá siempre qué sistema operativo y qué binarios externos espera tu skill antes de que alguien la instale a ciegas.

Profundizando: permisos, seguridad y el modelo de ejecución

Un script dentro de una skill corre, por defecto, con los mismos permisos de la cuenta que ejecuta Claude Code. No hay una sandbox automática que separe el código de una skill del código que escribirías vos mismo en esa terminal. Instalar una skill de un repositorio ajeno equivale, en términos de riesgo, a copiar y correr un script que bajaste de internet.

El README de big-arrow-on-the-screen insiste en lo que el binario no hace. No captura pantalla, no hace clics, no tipea y no tiene telemetría. Son afirmaciones verificables porque el código es abierto bajo MIT: cualquiera puede leer el Swift fuente y confirmar que la única operación es dibujar una ventana superpuesta.

⚠️ Ojo: antes de instalar una skill de terceros, abrí el SKILL.md y los scripts que trae; son texto plano y Markdown, así que leerlos antes de confiarles tu usuario no toma más de un minuto.

Esto también marca cuándo este complemento para el agente no es la herramienta correcta. Si varias personas o servicios sin confianza mutua necesitan la misma integración, con límites de cuota y autenticación propios, conviene un servidor MCP con su propio control de acceso en vez de un script local que corre con los permisos de quien lo invoca.

📖 Resumen en Telegram: Ver resumen

Tu próximo paso: creá la carpeta ~/.claude/skills/hola-mundo de la sección «Cómo empezar», pedile a Claude que te salude, y después comparala con el SKILL.md real de big-arrow-on-the-screen.

Preguntas frecuentes

¿Las Skills de Claude Code funcionan igual en Codex?

big-arrow-on-the-screen se instala como skill tanto en Claude Code como en Codex porque ambos leen el mismo formato de carpeta con SKILL.md y frontmatter; lo que cambia es el cliente que interpreta ese archivo, no su contenido.

¿Hace falta permiso de macOS para que un script dibuje sobre la pantalla?

Según el repositorio, dibujar la flecha en sí no pide ningún permiso del sistema. Identificar un elemento puntual de una app con la flag --element sí puede requerir acceso a la API de accesibilidad de macOS, dependiendo de cómo lo implemente cada versión del binario.

¿Esta extensión de agente puede reemplazar un servidor MCP?

Para una tarea local y puntual, sí. Para conectar a un sistema externo con estado propio, autenticación y múltiples clientes simultáneos, no. Ahí un servidor MCP sigue siendo la pieza correcta, como se ve en la tabla comparativa de arriba.

¿Dónde se instalan las skills de un proyecto frente a las globales?

Las skills globales viven en ~/.claude/skills/ y están disponibles en cualquier proyecto; las skills específicas de un repositorio se guardan dentro de .claude/skills/ junto al código, de forma similar a como un CLAUDE.md convive con el proyecto.

¿Hace falta saber Swift para escribir una skill como la de big-arrow?

No. big-arrow-on-the-screen usa Swift para su propio binario, pero el script que invoca una skill puede ser bash, Python, Node o cualquier ejecutable: lo único que el SKILL.md necesita es saber qué comando correr y con qué argumentos.

Referencias

• GitHub: franzenzenhofer/big-arrow-on-the-screen: repositorio MIT con el CLI y la skill usados como caso de estudio en este artículo.
• Claude Code: página oficial del producto y canal de acceso al CLI de Anthropic.
• Model Context Protocol: especificación abierta usada en la comparativa de este artículo.
• Anthropic en GitHub: organización con los repositorios públicos relacionados a Claude Code.

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.

Imagen destacada: Foto de Ilya Pavlov en Unsplash