Buenas prácticas

Las buenas Skills son concisas, están bien estructuradas y se prueban con uso real. Esta guía ofrece decisiones prácticas de autoría para ayudarte a escribir Skills que Claude pueda descubrir y usar de forma eficaz.

Para el contexto conceptual sobre cómo funcionan Skills, consulta el resumen de Skills.

Principios centrales

La concisión es clave

La ventana de contexto es un recurso compartido. Tu Skill comparte esa ventana con todo lo demás que Claude necesita saber: el prompt del sistema, el historial de conversación, los metadatos de otras Skills y la solicitud real del usuario.

No todos los tokens de tu Skill tienen un coste inmediato. Al inicio solo se precargan los metadatos (name y description) de todas las Skills. Claude lee SKILL.md solo cuando la Skill se vuelve relevante, y lee archivos adicionales solo cuando los necesita. Aun así, la concisión en SKILL.md importa: una vez cargado, cada token compite con el historial de conversación y otros contextos.

Suposición predeterminada: Claude ya es muy inteligente.

Añade solo el contexto que Claude no tenga ya. Cuestiona cada pieza de información:

• "¿Claude necesita realmente esta explicación?"
• "¿Puedo asumir que Claude ya sabe esto?"
• "¿Este párrafo justifica su coste en tokens?"

Buen ejemplo: conciso:

## Extract PDF text

Use pdfplumber for text extraction:
```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Mal ejemplo: demasiado largo:

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

La versión concisa asume que Claude sabe qué son los PDF y cómo funcionan las bibliotecas.

Establecer grados de libertad adecuados

Ajusta el nivel de especificidad a la fragilidad y variabilidad de la tarea.

Alta libertad sirve cuando hay varios enfoques válidos, las decisiones dependen del contexto y las heurísticas guían la ejecución.

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

Libertad media sirve cuando existe un patrón preferido, cierta variación es aceptable y la configuración afecta al comportamiento.

## Generate report

Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```

Baja libertad sirve cuando las operaciones son frágiles, la consistencia es crítica o debe seguirse una secuencia concreta.

## Database migration

Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

Piensa en Claude como un robot que explora un camino. En un puente estrecho con precipicios a ambos lados, solo hay una ruta segura: proporciona instrucciones exactas y guardarraíles. En un campo abierto sin peligros, muchas rutas llevan al éxito: da una dirección general y confía en que Claude encuentre el mejor camino.

Probar con todos los modelos que piensas usar

Skills actúan como añadidos al modelo, así que su eficacia depende del modelo subyacente. Prueba tu Skill con todos los modelos con los que planeas usarla.

• Claude Haiku: ¿la Skill da suficiente orientación?
• Claude Sonnet: ¿la Skill es clara y eficiente?
• Claude Opus: ¿evita explicar de más?

Lo que funciona perfectamente en Opus puede necesitar más detalle en Haiku. Si vas a usar la Skill con varios modelos, apunta a instrucciones que funcionen bien con todos.

Estructura de Skill

Convenciones de nombre

Usa patrones de nombre consistentes para que las Skills sean fáciles de referenciar y comentar. Recomendamos usar gerundios (verb + -ing) para nombres de Skills, porque describen claramente la actividad o capacidad.

Buenos ejemplos: "Processing PDFs", "Analyzing spreadsheets", "Managing databases", "Testing code", "Writing documentation".

Alternativas aceptables: frases nominales como "PDF Processing" o formas orientadas a la acción como "Process PDFs".

Evita nombres vagos como "Helper", "Utils", "Tools"; nombres demasiado genéricos como "Documents", "Data", "Files"; y patrones inconsistentes dentro de tu colección.

La consistencia facilita referenciar Skills, entenderlas de un vistazo, organizarlas y mantener una biblioteca profesional y coherente.

Escribir descripciones eficaces

El campo description habilita el descubrimiento de Skills y debe incluir tanto lo que hace la Skill como cuándo usarla.

Sé específico e incluye términos clave. Claude usa la descripción para elegir la Skill correcta entre potencialmente más de 100 Skills disponibles. La descripción debe darle suficiente información para seleccionar esta Skill; el resto de SKILL.md contiene los detalles de implementación.

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Evita descripciones vagas como:

description: Helps with documents

description: Processes data

description: Does stuff with files

Patrones de divulgación progresiva

SKILL.md funciona como una vista general que dirige a Claude hacia materiales detallados según sea necesario, como la tabla de contenidos de una guía de incorporación. Para una explicación completa, consulta Cómo funcionan Skills.

Guía práctica:

• Mantén el cuerpo de SKILL.md por debajo de 500 líneas
• Divide contenido en archivos separados al acercarte a ese límite
• Usa los patrones siguientes para organizar instrucciones, código y recursos

Una Skill básica empieza con un único SKILL.md con metadatos e instrucciones.

A medida que la Skill crece, puedes agrupar contenido adicional que Claude carga solo cuando hace falta.

La estructura completa puede verse así:

pdf/
|-- SKILL.md              # Main instructions (loaded when triggered)
|-- FORMS.md              # Form-filling guide (loaded as needed)
|-- reference.md          # API reference (loaded as needed)
|-- examples.md           # Usage examples (loaded as needed)
`-- scripts/
  |-- analyze_form.py   # Utility script (executed, not loaded)
  |-- fill_form.py      # Form filling script
  `-- validate.py       # Validation script

Patrón 1: guía de alto nivel con referencias

---
name: PDF Processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude carga FORMS.md, REFERENCE.md o EXAMPLES.md solo cuando los necesita.

Patrón 2: organización por dominio

En Skills con varios dominios, organiza el contenido por dominio para evitar cargar contexto irrelevante. Si un usuario pregunta por métricas de ventas, Claude solo necesita esquemas de sales, no finanzas ni marketing.

bigquery-skill/
|-- SKILL.md (overview and navigation)
`-- reference/
  |-- finance.md (revenue, billing metrics)
  |-- sales.md (opportunities, pipeline)
  |-- product.md (API usage, features)
  `-- marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing -> See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts -> See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption -> See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email -> See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

Patrón 3: detalles condicionales

Muestra contenido básico y enlaza contenido avanzado.

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude lee REDLINING.md u OOXML.md solo si el usuario necesita esas funciones.

Evitar referencias profundamente anidadas

Claude puede leer solo parcialmente archivos referenciados desde otros archivos referenciados. Al encontrar referencias anidadas, puede usar comandos como head -100 para previsualizar en lugar de leer todo el archivo, lo que produce información incompleta.

Mantén las referencias a un nivel desde SKILL.md. Todos los archivos de referencia deberían enlazarse directamente desde SKILL.md.

# Malo
SKILL.md -> advanced.md -> details.md

# Bueno
SKILL.md enlaza directamente advanced.md, reference.md y examples.md

Estructurar archivos largos con tabla de contenidos

En archivos de referencia de más de 100 líneas, incluye una tabla de contenidos al inicio para que Claude vea el alcance completo aun si hace lecturas parciales.

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

Workflows y bucles de feedback

Usar workflows para tareas complejas

Divide operaciones complejas en pasos claros y secuenciales. Para workflows especialmente complejos, proporciona una checklist que Claude pueda copiar en su respuesta y marcar conforme avanza.

## Research synthesis workflow

Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

Read all documents in `sources/`, identify recurring themes, cross-reference major claims, summarize by theme, and verify that every claim cites the correct source.

Este patrón también sirve para tareas de análisis sin código. Para Skills con código, una checklist puede indicar scripts concretos:

## PDF form filling workflow

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

Run: `python scripts/analyze_form.py input.pdf`
Run: `python scripts/validate_fields.py fields.json`
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.

Los pasos claros impiden que Claude omita validaciones críticas.

Implementar bucles de feedback

Patrón común: ejecutar validador -> corregir errores -> repetir.

Este patrón mejora mucho la calidad. En Skills sin código, el "validador" puede ser STYLE_GUIDE.md: Claude lo lee y compara el contenido con sus reglas. En Skills con código, valida inmediatamente después de cada edición, corrige los errores y solo continúa cuando la validación pasa.

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails, read the error, fix XML, and validate again
4. **Only proceed when validation passes**
5. Rebuild and test the output document

Guías de contenido

Evitar información sensible al tiempo

No incluyas información que quedará obsoleta. En lugar de decir "antes de agosto de 2025 usa la API antigua; después usa la nueva", mantén un método actual y coloca patrones antiguos en una sección separada.

## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>

Usar terminología consistente

Elige un término y úsalo en toda la Skill. Usa siempre "API endpoint", "field" y "extract"; no mezcles "API endpoint", "URL", "API route" y "path", ni "field", "box", "element" y "control". La consistencia ayuda a Claude a entender y seguir instrucciones.

Patrones comunes

Patrón de plantilla

Proporciona plantillas para el formato de salida y ajusta el nivel de rigidez a tus necesidades.

## Report structure

ALWAYS use this exact template structure:
```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

Si necesitas flexibilidad, presenta un formato predeterminado sensato y permite adaptar las secciones según el análisis.

Patrón de ejemplos

Cuando la calidad depende de ver ejemplos, proporciona pares de entrada/salida.

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Follow this style: type(scope): brief description, then detailed explanation.

Los ejemplos muestran estilo y nivel de detalle con más claridad que una descripción sola.

Patrón de workflow condicional

Guía a Claude por puntos de decisión.

## Document modification workflow

1. Determine the modification type:
 **Creating new content?** -> Follow "Creation workflow" below
 **Editing existing content?** -> Follow "Editing workflow" below

2. Creation workflow:
 - Use docx-js library
 - Build document from scratch
 - Export to .docx format

3. Editing workflow:
 - Unpack existing document
 - Modify XML directly
 - Validate after each change
 - Repack when complete

Evaluación e iteración

Crear evaluaciones primero

Crea evaluaciones antes de escribir documentación extensa. Así aseguras que la Skill resuelve problemas reales y no requisitos imaginados.

1. Ejecuta Claude sin Skill en tareas representativas y documenta fallos
2. Crea tres escenarios que prueben esas brechas
3. Mide una línea base sin la Skill
4. Escribe instrucciones mínimas para resolver las brechas
5. Ejecuta evaluaciones, compara con la línea base y refina

{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
  "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
  "Extracts text content from all pages in the document without missing any pages",
  "Saves the extracted text to a file named output.txt in a clear, readable format"
]
}

Desarrollar Skills iterativamente con Claude

El proceso más eficaz incluye a Claude. Trabaja con una instancia ("Claude A") para crear una Skill que usarán otras instancias ("Claude B"). Claude A ayuda a diseñar y refinar instrucciones; Claude B las prueba en tareas reales.

Primero completa una tarea sin Skill con Claude A. Observa qué contexto, preferencias y conocimiento procedimental repites. Después identifica el patrón reutilizable y pide a Claude A que cree una Skill que capture ese patrón. Revisa que no haya explicaciones innecesarias, mejora la arquitectura de información y prueba con Claude B en casos relacionados. Si Claude B falla o se salta una regla, vuelve a Claude A con una observación concreta y refina.

Para Skills existentes, alterna entre trabajar con Claude A, probar con Claude B y observar el comportamiento de Claude B. Comparte Skills con tu equipo, pregunta si se activan cuando corresponde, si las instrucciones son claras y qué falta. Este ciclo mejora Skills con comportamiento observado, no con suposiciones.

Observar cómo Claude navega Skills

Presta atención a rutas de exploración inesperadas, referencias importantes que Claude no sigue, dependencia excesiva de ciertos archivos o contenido empaquetado que nunca se usa. Itera sobre esas observaciones. name y description son especialmente críticos porque Claude los usa para decidir si debe activar la Skill.

Antipatrones a evitar

Evitar rutas estilo Windows

Usa siempre barras normales en rutas, incluso en Windows.

• Bien: scripts/helper.py, reference/guide.md
• Evita: scripts\helper.py, reference\guide.md

Evitar demasiadas opciones

No presentes múltiples enfoques salvo que sea necesario.

**Bad example: Too many choices**:
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default**:
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

Avanzado: Skills con código ejecutable

Estas secciones se centran en Skills con scripts ejecutables. Si tu Skill solo usa instrucciones Markdown, salta a Checklist para Skills eficaces.

Resolver, no delegar el problema

Al escribir scripts, maneja condiciones de error en lugar de dejarlas para Claude.

def process_file(path):
  """Process a file, creating it if it doesn't exist."""
  try:
      with open(path) as f:
          return f.read()
  except FileNotFoundError:
      print(f"File {path} not found, creating default")
      with open(path, 'w') as f:
          f.write('')
      return ''
  except PermissionError:
      print(f"Cannot access {path}, using default")
      return ''

También documenta los parámetros de configuración para evitar "voodoo constants". Si no sabes por qué un valor es correcto, Claude tampoco lo sabrá.

# HTTP requests typically complete within 30 seconds
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
MAX_RETRIES = 3

Proporcionar scripts utilitarios

Aunque Claude podría escribir un script, los scripts preparados son más fiables, ahorran tokens, ahorran tiempo y aseguran consistencia.

Aclara si Claude debe ejecutar el script o leerlo como referencia.

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```

**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
```

**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

Usar análisis visual

Cuando las entradas pueden renderizarse como imágenes, haz que Claude las analice.

## Form layout analysis

1. Convert PDF to images:
```bash
   python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

Crear salidas intermedias verificables

Para tareas complejas, usa el patrón "plan-validate-execute": Claude crea primero un plan estructurado, un script lo valida y solo después se ejecuta. En una actualización de 50 campos de PDF desde una hoja de cálculo, crea un changes.json, valídalo, ejecuta y verifica. Esto detecta errores temprano, permite verificación objetiva, facilita iterar sin tocar originales y ofrece mensajes de error concretos.

Empaquetar dependencias

Skills se ejecutan con limitaciones específicas:

• claude.ai: puede instalar paquetes de npm y PyPI y obtener repositorios de GitHub
• Anthropic API: no tiene red ni instalación de paquetes en tiempo de ejecución

Lista paquetes necesarios en SKILL.md y verifica disponibilidad en la documentación de la herramienta de ejecución de código.

Entorno de ejecución

Skills se ejecutan en un entorno con sistema de archivos, bash y ejecución de código. Los metadatos se precargan al inicio; los archivos se leen bajo demanda; los scripts se ejecutan sin cargar su contenido completo; y los archivos grandes no consumen contexto hasta que se leen. Usa rutas con barras normales, nombres descriptivos, organización por dominio, scripts para operaciones deterministas y una intención clara entre "Run analyze_form.py" y "See analyze_form.py".

Referencias a herramientas MCP

Si una Skill usa herramientas MCP, usa nombres completamente cualificados.

Formato: ServerName:tool_name

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

No asumir que las herramientas están instaladas

No asumas paquetes disponibles.

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```

Notas técnicas

Requisitos de YAML frontmatter

El frontmatter de SKILL.md incluye solo name (máximo 64 caracteres) y description (máximo 1024 caracteres). Consulta el resumen de Skills.

Presupuestos de tokens

Mantén el cuerpo de SKILL.md por debajo de 500 líneas. Si lo supera, divídelo con los patrones de divulgación progresiva descritos antes.

Checklist para Skills eficaces

Calidad central

• La descripción es específica e incluye términos clave
• La descripción incluye qué hace y cuándo usar la Skill
• SKILL.md tiene menos de 500 líneas
• Los detalles adicionales están en archivos separados si hace falta
• No hay información sensible al tiempo, o está en "old patterns"
• La terminología es consistente
• Los ejemplos son concretos
• Las referencias a archivos están a un nivel
• La divulgación progresiva se usa correctamente
• Los workflows tienen pasos claros

Código y scripts

• Los scripts resuelven problemas en lugar de delegarlos a Claude
• El manejo de errores es explícito y útil
• No hay "voodoo constants"
• Los paquetes requeridos están listados y verificados
• Los scripts tienen documentación clara
• No hay rutas estilo Windows
• Hay validación para operaciones críticas
• Hay bucles de feedback para tareas de calidad crítica

Pruebas

• Se crearon al menos tres evaluaciones
• Se probó con Haiku, Sonnet y Opus
• Se probó con escenarios reales
• Se incorporó feedback del equipo si aplica

Siguientes pasos