Creando Skills Agénticos: Buenas PrácticasCreando Skills Agénticos: Buenas Prácticas

Parece que el desarrollo agéntico está convergiendo hacia los skillsSe abre en una nueva pestaña, y tiene todo el sentido.

Los skills son archivos con instrucciones que añaden nuevas capacidades a los agentes de IA. En estos archivos describes cómo debe comportarse un agente, dándole contexto e información ampliada cuando aborda una tarea relevante para ese skill.

Déjame mostrarte en esta edición cómo puedes crear skills agénticos robustos para usar menos tokens y obtener mejores resultados.

También compartiré mis skills más valiosos hasta la fecha a lo largo de esta edición de la newsletter.

#¿Cuál es el propósito de los skills?

Si pensamos en los humanos, cualquiera puede especializarse en distintos campos o herramientas. La especialización abre la puerta a entregas de mayor calidad. Como dijo Bruce Lee:

“

No temo al hombre que ha practicado 10.000 patadas una vez, temo al hombre que ha practicado una patada 10.000 veces.

”

Y como humanos, también podemos aprender skills que otros tienen.

Por ejemplo, disfruto mucho usando el método bullet journal y conozco a mucha gente que también lo usa. Es un skill que adquirí a lo largo de los años, no nací con él.

Diferentes skills pueden enseñarse a otros. Lleva tiempo y esfuerzo integrar ese conocimiento.

Lo mismo aplica a la IA. Enséñale una vez, obtén el comportamiento para siempre:

• Sin repetición. Deja de pegar las mismas instrucciones cada sesión.
• Consistencia. Dada la misma tarea, deberías obtener el mismo resultado, entre compañeros y a lo largo del tiempo.
• Apalancamiento compuesto. Cada skill que escribes hace la siguiente tarea más barata.
• Ahorro de tokens. Un skill preciso le gana a un prompt largo.

#¿Qué aspecto tiene un skill?

Los skills agénticos se basan en una especificación abierta creada por AnthropicSe abre en una nueva pestaña, así que mientras sigas este formato sencillo, todos los agentes de IA pueden interactuar con tus skills.

Los skills para agentes de IA no son más que archivos markdown, como el siguiente:

---
name: remember
description: Capture and persist learnings to improve future sessions.
Use when the user says "remember this", a useful pattern emerges, or a project convention is established.
---

# Remember

Capture knowledge so future sessions benefit from it.

## Workflow

1. **Capture** — extract what was learned, why it matters, and an example.
2. **Route** — decide where it belongs (CLAUDE.md, an existing skill, or a new skill).
3. **Propose** — show the user the exact change before applying.
4. **Apply** — only after approval.

## Example

User: "Always use `??` instead of `||` for nullish defaults." → Add to CLAUDE.md under TypeScript conventions.

Estos archivos se colocan en un directorio que tu sistema de IA elegido detectará. Como uso Claude Code, los creo en ./project/.claude/skills. Tienen la siguiente estructura:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

#Dónde colocar tus skills

Los skills viven en uno de dos ámbitos:

Los skills de proyecto ganan cuando hay colisión de nombres, así que puedes sobreescribir un skill global en un único repo sin tocar la versión global. Regla práctica: si el skill codifica una decisión que solo este código ha tomado, ponlo en el proyecto. Si viaja contigo, ponlo en global.

Creo firmemente que los desarrolladores perfeccionarán su toolkit de skills. Yo ya he empezado.

#Meta-información de los skills

Los skills son invocados por el sistema agéntico dependiendo de la meta-información que incluyamos en el frontmatter:

• Name: identificador corto en kebab-case.
• Description: qué hace el skill y cuándo activarlo.

Por eso nombrar es extremadamente importante. Dependiendo del nombre y la descripción, el skill se activará o no.

Usando Claude Code, también puedes activar un skill directamente con un slash command:

/remember

#Instrucciones del skill

En el cuerpo del skill describes qué debe hacer el agente una vez se active.

También he descubierto que los skills funcionan genial como documentación viva de tu proyecto. Por eso suelo dedicar bastante tiempo a ajustarlos y mejorarlos.

#Añadir más contexto a los skills agénticos

Puedes referenciar contexto adicional que solo debe cargarse cuando se necesite. ¿Recuerdas la carpeta references en la estructura? Ahí vive la documentación condicional.

La forma de hacerlo es apuntar al agente a esos archivos desde el cuerpo de SKILL.md:

---
name: create-domain-model
description: Generate pure domain layer code. Creates entities, value objects, and domain services with no framework dependencies.
---

# Domain Model Generator

Generate pure TypeScript domain code following layer boundaries.

## Workflow

1. Read the task file under `tasks/`.
2. Decide whether you need an entity, a value object, or a domain service.
   - For entities, follow `references/entities.md`.
   - For value objects, follow `references/value-objects.md`.
   - For test data, follow `references/mother-pattern.md`.
3. Generate code under `src/features/<feature>/domain/`.
4. Run `npm run test -- domain` and verify GREEN.

El agente solo cargará references/value-objects.md si la tarea realmente requiere un value object. Eso es divulgación progresiva en acción. Es enorme para mantener limpia la ventana de contexto.

#Comportamientos de carga

#Buenas prácticas al crear skills robustos

#1. Sé conciso

Bien:

## Create a value object

Use a private constructor + static factory:

```ts
export class Email {
  private constructor(readonly value: string) {}

  static create(value: string): Email {
    if (!value.includes('@')) throw new Error('Invalid email')
    return new Email(value)
  }
}
```

Ser conciso pero preciso es esencial. Los skills interactúan con la ventana de contexto, que es la "memoria" del agente de IA. Cuanto más la llenemos, más degradación veremos.

“

La ventana de contextoSe abre en una nueva pestaña es un bien público.

”

Mal. Verboso y reformula hechos conocidos:

## Create a value object

Value objects are a concept that comes from Domain Driven Design. They are
immutable objects that represent a concept in your domain. There are many ways
to implement them in TypeScript, but the most common one is to use a class with
a private constructor and a static factory method. First, you'll need to make
sure your constructor is private so consumers cannot instantiate the class
directly. Then you'll need to add a static method that validates the input...

#2. Establece los grados de libertad adecuados

Podemos dejar a nuestros skills con más libertad o menos libertad ante la tarea. Piénsalo como un espectro:

Me gusta usar alta libertad cuando quiero que el agente decida qué importa y depende más del contexto:

## Review

Review the diff for clarity, naming, and SOLID violations. Suggest improvements
where they add value.

Baja libertad para tareas que tienen (y deberían tener) una única forma de hacerse, como subir la versión de un paquete.

## Bump version

1. Run `npm version <major|minor|patch>`.
2. Run `npm run build` and verify it passes.
3. Commit with message `chore: bump to vX.Y.Z`.
4. Run `git push --follow-tags`.

#3. Usa workflows para tareas complejas

Una checklist paso a paso mantiene al agente en raíles para tareas multi-paso:

## Workflow

- [ ] 1. Read all source documents under `tasks/`
- [ ] 2. Identify entities and value objects
- [ ] 3. Generate domain code under `src/features/<feature>/domain/`
- [ ] 4. Run `/architecture-guardrails`
- [ ] 5. Report the diff to the user before writing

#4. Bucles de feedback

Darle al agente una forma de validar su propio trabajo es esencial al crear skills robustos.

¿Puedes adivinar la forma de validación más efectiva para tareas de código? Los tests. Por eso si no tienes tests en tu aplicación y quieres usar IA, estás malgastando recursos.

## Validation

After generating code, run:

1. `npm run typecheck` — must pass.
2. `npm test -- <feature>` — must pass.
3. `/architecture-guardrails` — no cross-layer imports.

If any step fails, fix the cause and re-run before reporting back.

#5. Da ejemplos concretos

Las plantillas abstractas no son tan útiles como tener ejemplos concretos para enseñar. Muestra una entrada real mapeada a una salida real:

## Example

**Input** — user says: "Add an Email value object."

**Output** — generate `src/features/users/domain/email.ts`:

```ts
export class Email {
  private constructor(readonly value: string) {}

  static create(value: string): Email {
    if (!value.includes('@')) throw new Error('Invalid email')
    return new Email(value)
  }
}
```

And a matching Mother under `src/features/users/domain/email.mother.ts`:

```ts
export class EmailMother {
  static valid(): Email {
    return Email.create('jane@example.com')
  }
}
```

Cuando el agente ve esto, tiene un patrón a imitar en lugar de una descripción que adivinar.

#6. Usa un agente de IA para crear skills

Ahora que tenemos todo este conocimiento sobre crear skills... ¿y si creamos un skill para crear o actualizar skills? Eso es. No te preocupes, ya me he encargado y subí el mío a mi sitio para que puedas usarlo directamente.

#Checklist para skills efectivos

Antes de compartir un skill, verifica:

Calidad básica

• La descripción es específica e incluye frases clave de activación
• La descripción dice qué hace el skill y cuándo usarlo
• El cuerpo de SKILL.md tiene menos de 500 líneas
• Los detalles adicionales están en archivos separados cuando hace falta
• Terminología consistente en todo el documento
• Los ejemplos son concretos, no abstractos
• Se usa divulgación progresiva donde corresponde
• Los workflows tienen pasos claros y ordenados

#Conclusión

Estamos en una era donde saber — y expresar ese conocimiento de forma concisa y precisa — es clave para nuestro éxito como individuos y organizaciones. Los skills son un reflejo perfecto de eso. Gracias por leer, y como siempre, ¡siéntete libre de votar la próxima edición!

P.D: Próximamente abro agenda para nuevos proyectos como AI Frontend Architect. Si crees que puedo ayudarte con tu proyecto, responde a este email.

P.D 2: Escribí esta newsletter desde un pueblo de 300 habitantes en la Serranía de Málaga, en un coliving llamado RooralSe abre en una nueva pestaña, donde estoy pasando el mes entre otros nómadas digitales.