¿Qué es una Skill en Claude Code? Ejemplo: skill para conectar con PostgreSQL

Una skill en Claude Code es una receta reutilizable que el modelo carga automáticamente cuando detecta que aplica al contexto. Es la forma más limpia de extender las capacidades de Claude para tareas específicas de tu día a día: gestionar tu base de datos, desplegar a un servidor, manejar workflows de n8n, formatear documentación. En este artículo te explico qué son exactamente, en qué se diferencian de los MCP y te enseño a crear una skill real para conectar con PostgreSQL y modificar datos desde Claude.

¿Qué es exactamente una skill?

En Claude Code una skill es un directorio que vive en ~/.claude/skills/ con esta estructura mínima:

~/.claude/skills/
└── nombre-de-tu-skill/
    ├── SKILL.md          # Instrucciones que Claude lee
    └── scripts/          # Opcional: scripts que la skill ejecuta
        └── herramienta.py

El SKILL.md es el corazón. Lleva un frontmatter YAML con metadatos y, debajo, las instrucciones en Markdown que Claude usará cuando active la skill. El frontmatter define dos cosas clave:

• name: identificador único.
• description: cuándo aplicar la skill. Esto es lo más importante. Claude lee este texto y decide si activarla. Si la descripción es vaga, la skill no se dispara. Si es precisa, se activa justo cuando toca.

Skill vs MCP vs comando custom: ¿qué uso cuándo?

La diferencia clave: las skills se activan solas cuando Claude detecta que aplican. Los MCP son tools siempre disponibles. Los comandos requieren que el usuario los invoque.

¿Por qué crear tus propias skills?

Algunas tareas que ganan muchísimo con una skill propia:

• Gestión de base de datos: consultar, exportar, modificar tablas (lo que vamos a montar en este tutorial).
• Despliegue a tu VPS: una skill que conecte por SSH y haga deploy con tus comandos exactos.
• Workflows de n8n: skill que crea/actualiza workflows vía la API de n8n self-hosted.
• Plantillas de proyecto: skill que genera la estructura base de un nuevo cliente con tu boilerplate.
• Revisión de PRs: skill que analiza diffs con criterios específicos de tu equipo.

El patrón es siempre el mismo: "si me veo escribiendo el mismo bloque de instrucciones tres veces en distintas sesiones, es candidato a skill".

Tutorial: skill para conectar con PostgreSQL

Vamos a construir una skill que permita a Claude consultar y modificar tu base de datos PostgreSQL con un simple "actualiza el campo X de la tabla Y".

Paso 1: Crear la estructura de carpetas

Abre un terminal y crea los directorios:

mkdir -p ~/.claude/skills/postgres-db/scripts
cd ~/.claude/skills/postgres-db

(En Windows con Git Bash o WSL: misma ruta. En PowerShell sería ~\.claude\skills\postgres-db\scripts.)

Paso 2: Escribir el SKILL.md

Crea el archivo SKILL.md con este contenido:

---
name: postgres-db
model: haiku
description: >
  Gestionar bases de datos PostgreSQL: conectar, consultar, explorar esquemas,
  modificar registros, exportar datos. Usar esta skill siempre que el usuario
  mencione PostgreSQL, Postgres, consultas SQL, tablas, migraciones, o quiera
  explorar/gestionar una base de datos.
---

# PostgreSQL Database Manager

Skill para conectar y gestionar bases de datos PostgreSQL desde Claude Code.

## Requisitos

- Python 3 con `psycopg2-binary` instalado
- Acceso de red al servidor PostgreSQL
- Credenciales con permisos adecuados (mínimo SELECT; UPDATE/INSERT
  si vas a modificar)

## Obtener credenciales

Antes de ejecutar nada, asegúrate de tener:
- `host` (ej: localhost, easypanel.miempresa.com)
- `port` (típicamente 5432)
- `dbname` (nombre de la base de datos)
- `user` y `password`

Si no las tienes, pídelas al usuario explícitamente. NUNCA asumas
credenciales por defecto en producción.

## Operaciones disponibles

Usa el script `scripts/pg_query.py` con estos comandos:

### Test de conexión
```bash
python ~/.claude/skills/postgres-db/scripts/pg_query.py \
  --host HOST --port PORT --db DBNAME --user USER \
  --password PASS --test
```

### Ejecutar query SELECT
```bash
python ~/.claude/skills/postgres-db/scripts/pg_query.py \
  --host HOST --port PORT --db DBNAME --user USER \
  --password PASS --query "SELECT * FROM tabla LIMIT 10"
```

### Ejecutar UPDATE/INSERT/DELETE
Mismo comando con la query correspondiente. El script detecta operaciones
de escritura y pide confirmación antes de ejecutar.

## Notas de seguridad

- NUNCA ejecutes DELETE, DROP, TRUNCATE sin confirmar explícitamente
  con el usuario el alcance exacto.
- Antes de modificaciones masivas, ejecuta primero un SELECT con la
  misma cláusula WHERE para validar cuántas filas se afectarán.
- Si surge cualquier duda durante una operación, PARA y pregunta al
  usuario antes de continuar.

Fíjate en la description del frontmatter: ahí está la magia. Claude lee ese texto en cada sesión y decide si la skill aplica al contexto. Si dices "ayúdame a actualizar el campo precio en la tabla productos de mi Postgres", Claude reconoce el match y activa la skill antes de hacer nada.

Paso 3: Implementar el script Python

Crea scripts/pg_query.py:

#!/usr/bin/env python3
"""
pg_query.py — Helper para que Claude Code interactúe con PostgreSQL.
"""
import argparse
import sys
import psycopg2
from psycopg2.extras import RealDictCursor

def conectar(args):
    return psycopg2.connect(
        host=args.host,
        port=args.port,
        dbname=args.db,
        user=args.user,
        password=args.password,
        connect_timeout=10
    )

def test_conexion(args):
    try:
        conn = conectar(args)
        cur = conn.cursor()
        cur.execute("SELECT version()")
        version = cur.fetchone()[0]
        conn.close()
        print(f"OK — Conectado a: {version}")
        return 0
    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        return 1

def ejecutar_query(args):
    query_lower = args.query.strip().lower()
    operaciones_destructivas = ('delete', 'drop', 'truncate', 'alter')

    if any(query_lower.startswith(op) for op in operaciones_destructivas):
        print("⚠️ Operación destructiva detectada. Para confirmar añade --force",
              file=sys.stderr)
        if not args.force:
            return 1

    try:
        conn = conectar(args)
        cur = conn.cursor(cursor_factory=RealDictCursor)
        cur.execute(args.query)

        if cur.description:  # SELECT
            filas = cur.fetchall()
            for fila in filas:
                print(dict(fila))
            print(f"\n{len(filas)} fila(s)")
        else:  # INSERT/UPDATE/DELETE
            conn.commit()
            print(f"OK — {cur.rowcount} fila(s) afectada(s)")

        conn.close()
        return 0
    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        return 1

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--host', required=True)
    parser.add_argument('--port', type=int, default=5432)
    parser.add_argument('--db', required=True)
    parser.add_argument('--user', required=True)
    parser.add_argument('--password', required=True)
    parser.add_argument('--query', help='SQL a ejecutar')
    parser.add_argument('--test', action='store_true',
                        help='Solo probar conexión')
    parser.add_argument('--force', action='store_true',
                        help='Permitir operaciones destructivas')
    args = parser.parse_args()

    if args.test:
        sys.exit(test_conexion(args))
    elif args.query:
        sys.exit(ejecutar_query(args))
    else:
        parser.error("Usa --test o --query")

if __name__ == '__main__':
    main()

Paso 4: Instalar la dependencia

pip install psycopg2-binary

Paso 5: Probar la skill en Claude Code

Reinicia Claude Code (cerrar y abrir) para que detecte la skill nueva. Después, en una sesión cualquiera, pídele algo como:

"Conecta a mi PostgreSQL en localhost:5432 base mi_db
usuario postgres y dime qué tablas tengo."

Claude debería:

1. Detectar que tu petición encaja con la skill postgres-db.
2. Cargar el SKILL.md en contexto.
3. Pedirte la contraseña si no se la has dado.
4. Lanzar el script con los parámetros adecuados.
5. Presentarte el resultado.

Si no se activa, revisa la description del frontmatter: probablemente no incluye palabras que coincidan con tu petición. Una description bien afinada es la mitad del éxito de una skill.

Atajo: pídele a Claude que cree la skill por ti

Todo lo anterior es la versión "a mano" para que entiendas qué hace cada pieza. Pero una vez sabes cómo funciona una skill, lo más eficiente es no escribirlas tú: Claude Code trae una skill oficial llamada skill-creator que automatiza el proceso entero.

Para usarla, abre una sesión nueva de Claude Code y suéltale algo así:

"Créame una skill para conectar con mi base de datos PostgreSQL.
Debe permitir hacer SELECT, INSERT, UPDATE y DELETE, detectar
operaciones destructivas y pedir confirmación. Usa Python con
psycopg2."

Lo que pasa por debajo:

1. Claude detecta el match con la skill-creator de Anthropic y la activa automáticamente.
2. Te hace preguntas concretas: nombre de la skill, descripción, dependencias, qué operaciones cubrir, ejemplos de uso.
3. Genera el SKILL.md con frontmatter correcto, una description bien afinada para que la skill se active cuando toca, y el script Python o Bash asociado.
4. Lo coloca en ~/.claude/skills/<nombre>/ con la estructura correcta.
5. Te da instrucciones para probarla y, si quieres, evaluar su comportamiento con casos de prueba.

Es la forma habitual de crear skills cuando ya las dominas: dictas la intención, Claude monta la receta. En 2-3 minutos tienes algo funcional que luego pulir si hace falta.

Elegir el modelo de la skill: no mates moscas a cañonazos

Hay un detalle que casi nadie aprovecha y que marca la diferencia en el coste mensual de Claude si usas skills con frecuencia: puedes indicar en el frontmatter qué modelo debe usar Claude cuando active esa skill.

Es tan simple como añadir una línea model: ... al YAML del SKILL.md:

---
name: postgres-db
model: haiku   # ← aquí
description: >
  Gestionar bases de datos PostgreSQL...
---

Las opciones son haiku, sonnet y opus. Y la regla práctica es sencilla:

Por defecto las skills heredan el modelo de la sesión principal, que suele ser Sonnet. Eso significa que cada vez que activas una skill que solo ejecuta queries SQL, estás pagando precio Sonnet por una tarea de Haiku. Si la usas 50 veces al día, la diferencia acumulada en un mes es muy real.

Truco extra: incluso dentro de una skill que use Sonnet, puedes delegar las partes mecánicas a un sub-agente Haiku con el tool Agent. Así pagas Sonnet solo por la parte de razonamiento y Haiku por el grunt work. Es el patrón que usan las skills de Anthropic más afinadas.

Casos de uso reales una vez tienes la skill

Esta skill simple te permite ahora pedirle a Claude cosas como:

• "Exporta a CSV los últimos 100 pedidos de mi tabla orders donde el estado sea PENDIENTE"
• "Actualiza el precio de todos los productos de la categoría X subiéndolos un 10%" (Claude hará primero un SELECT para confirmar cuántas filas se ven afectadas).
• "Crea un índice en la columna email de la tabla usuarios para acelerar las búsquedas"
• "Dame el esquema completo de la tabla facturas con tipos de columnas y constraints"

Es la diferencia entre estar copiando queries SQL todo el día y tener un asistente que las entiende y ejecuta por ti.

Buenas prácticas al crear skills

• Description detallada y con triggers claros. Si no aparecen las palabras que el usuario suele usar, la skill no se activa.
• Permisos mínimos. Crea un usuario de BD con solo los permisos necesarios. No uses tu superusuario.
• Confirmación explícita en operaciones destructivas. El script de arriba lo hace con --force. Sin ese flag, rechaza DELETE/DROP/TRUNCATE.
• Logs y trazabilidad. Guarda en algún sitio cada query ejecutada (especialmente las de escritura) para poder auditar después.
• No hardcodear credenciales. Si guardas tu skill en git, pasa las credenciales como argumentos o por variables de entorno, nunca dentro del SKILL.md.
• Delegación a Haiku para tareas mecánicas. Si la skill se va a usar mucho, lanzar la ejecución vía Agent con modelo Haiku abarata los costes.

Limitaciones de este nivel

• ✅ Funciona contra cualquier PostgreSQL accesible por red.
• ✅ Detecta operaciones destructivas y obliga a --force.
• ✅ Activación automática cuando Claude detecta el contexto.
• ❌ Sin pooling de conexiones. Cada query abre y cierra. Para producción intensiva, mejor un MCP server con conexión persistente.
• ❌ Sin auditoría persistente. Las queries no se guardan en un log. Hay que añadirlo aparte.
• ❌ Credenciales pasadas por línea de comandos. Aparecen en el historial. Mejor migrar a archivo de credenciales o keyring.

El siguiente paso

Crear skills bien diseñadas es uno de los grandes saltos cuando empiezas a programar con Claude Code en serio. La diferencia entre quien improvisa cada sesión y quien tiene un arsenal de skills bien afinadas para sus flujos de trabajo es enorme: lo segundo es 5x más rápido y los resultados son consistentes.

Combinado con SDD (Spec-Driven Development), tienes la base para llevar Claude Code de "juguete entretenido" a "herramienta seria de productividad". Si quieres aprenderlo bien, con casos reales como skills para deploy, workflows de n8n, plantillas de proyecto y patrones avanzados, échale un ojo al curso de Programación asistida con IA de nacaIA Academy.

Próximos pasos

1. Crea la skill siguiendo este tutorial con una base de datos de pruebas (NO producción la primera vez).
2. Personaliza el SKILL.md añadiendo operaciones específicas de tu negocio.
3. Identifica otras 2-3 tareas repetitivas en tu día a día y conviértelas en skills.
4. Si quieres dominar Claude Code, SDD y skills avanzadas con casos reales, echa un vistazo al curso de Programación asistida en nacaIA Academy.