Agent Skills con Claude Code SKILL.md

Qué es SKILL.md

Un archivo SKILL.md es la forma en que Claude Code entiende y ejecuta un skill. Vive en .claude/skills/<nombre-skill>/ y combina metadatos YAML en el frontmatter con instrucciones procedimentales en markdown.

Estructura de la carpeta

Directorio.claude/
- Directorioskills/
  - Directoriodns-management/
    SKILL.md
    Directorioreferences/
    cloudflare-api-guide.md
    Directorioscripts/
    validate_record.py

SKILL.md — definición del skill: frontmatter + instrucciones
references/ — documentación de apoyo que Claude lee como contexto
scripts/ — scripts auxiliares que Claude puede ejecutar con Bash

Frontmatter del SKILL.md

---
name: dns-management
description: "Gestiona registros DNS via Cloudflare API para el dominio configurado"
allowed-tools: Bash(curl *) Bash(python *) Read
---

Campo	Descripción
`name`	Identificador único del skill
`description`	Qué hace — Claude lo usa para decidir cuándo invocar el skill
`allowed-tools`	Tools de Claude Code que el skill puede usar

allowed-tools restringe qué puede ejecutar Claude cuando está usando este skill. En este caso solo puede hacer curl o correr scripts Python — no puede hacer Write, Edit ni otras operaciones de filesystem.

Contenido del SKILL.md

El cuerpo del archivo son instrucciones procedimentales en markdown:

## Variables de entorno requeridas

- CLOUDFLARE_API_TOKEN
- CLOUDFLARE_ZONE_ID
- CLOUDFLARE_DOMAIN

## Flujo recomendado

Antes de crear o modificar un registro, siempre:
1. Lista los registros existentes para verificar duplicados
2. Ejecuta la operación
3. Valida que el registro resuelve correctamente

## Tipos de registro permitidos

Solo: A, CNAME, MX, TXT
No crear: NS, SOA, SRV — pueden romper la zona DNS

## Operaciones disponibles

- **Listar:** GET /zones/{zone_id}/dns_records
- **Crear:** POST /zones/{zone_id}/dns_records
- **Buscar:** GET con filtro ?name=&type=
- **Actualizar:** PUT /zones/{zone_id}/dns_records/{record_id}
- **Validar:** python scripts/validate_record.py <dominio> <ip_esperada>

Script auxiliar: `validate_record.py`

Valida que un registro DNS resuelve al valor esperado. Claude lo invoca con Bash:

#!/usr/bin/env python3
"""Valida que un registro DNS resuelve al valor esperado."""

def validate(domain: str, expected_ip: str) -> bool:
    import socket
    resolved = socket.gethostbyname(domain)
    return resolved == expected_ip

# Claude ejecuta esto internamente
python .claude/skills/dns-management/scripts/validate_record.py \
  api.tudominio.com 203.0.113.50

Referencia: `cloudflare-api-guide.md`

Referencia rápida de los endpoints de Cloudflare que Claude lee como contexto cuando trabaja con el skill:

## Autenticación
Authorization: Bearer {CLOUDFLARE_API_TOKEN}

## Endpoints principales
GET  /zones/{zone_id}/dns_records
POST /zones/{zone_id}/dns_records
PUT  /zones/{zone_id}/dns_records/{record_id}

## Formato de respuesta
{ "result": [{ "id": "...", "type": "A", "name": "api", "content": "1.2.3.4" }] }

Cómo usarlo en Claude Code

Copia la carpeta al proyecto donde quieras usarlo:
```
cp -r .claude/ /tu/proyecto/.claude/
```
Abre Claude Code en ese directorio. Claude detectará automáticamente los skills en .claude/skills/.

Invoca el skill con lenguaje natural:

> Crea el subdominio staging.tudominio.com apuntando a 10.0.0.5
> Lista todos los registros DNS actuales
> Migra mail.tudominio.com a la IP 5.6.7.8

Diferencia con Python/ADK

	Python / ADK	Claude Code (SKILL.md)
Tipo de restricción	Capa 2 — arquitectónica	Capa 1 — instrucciones
`delete` imposible?	Sí — la función no existe	No — Claude podría hacer curl DELETE si quisiera
Requiere código Python	Sí	No — Claude ejecuta curl directamente
Mejor para	Producción, sistemas críticos	Desarrollo, tareas de infraestructura con supervisión