# shihipar-claude-code-lessons-building-skills-2026-06-03

## Veille

Entrada de blog de **Anthropic / claude.com** por **Thariq Shihipar** (Member of Technical Staff, equipo Claude Code), publicada el **3 de junio de 2026**, que destila la **experiencia interna** de Anthropic sobre el diseño y uso de las **Skills**. **Tesis de encuadre**: una Skill no es un simple archivo markdown sino una **carpeta** (instrucciones + scripts + recursos + configuración + hooks) que el agente **descubre y manipula**; *« You should think of the entire file system as a form of context engineering and progressive disclosure. »* El artículo aporta dos contribuciones estructurantes. **(A) Una taxonomía de 9 categorías de skills** observadas en Anthropic: (1) **Library/API Reference** (documentación de libs/CLIs internas con *gotchas* — p. ej. `billing-lib`, `internal-platform-cli`, `sandbox-proxy`); (2) **Product Verification** (pruebas/verificación mediante Playwright o tmux — `signup-flow-driver`, `checkout-verifier`, `tmux-cli-driver`); (3) **Data Fetching & Analysis** (acceso a stacks de datos/monitorización — `funnel-query`, `cohort-compare`, `grafana`, `datadog`); (4) **Business Process Automation** (flujos de trabajo repetitivos — `standup-post`, `weekly-recap`, `create-<ticket>-ticket`); (5) **Code Scaffolding** (boilerplate de frameworks — `new-migration`, `create-app`); (6) **Code Quality & Review** (`adversarial-review`, `code-style`, `testing-practices`); (7) **CI/CD & Deployment** (`babysit-pr`, `deploy-<service>`, `cherry-pick-prod`); (8) **Runbooks** (diagnósticos multi-herramienta — `<service>-debugging`, `oncall-runner`, `log-correlator`); (9) **Infrastructure Operations** (mantenimiento con salvaguardas — `<resource>-orphans`, `cost-investigation`). **(B) Un conjunto de buenas prácticas**: no repetir lo obvio (*« Claude already knows how to code and can read your codebase »* → apuntar a lo que **contradice el comportamiento por defecto**); pulir la **sección Gotchas** (*« the highest-signal content in any skill »*); **divulgación progresiva** a través del árbol de archivos (dirigir hacia archivos de referencia según la situación en lugar de cargar todo por adelantado); **descripciones escritas para el modelo** (*« the description field is not a summary, it's a description of when to trigger this skill »*); **flujos de configuración** (config en `config.json`, o en su defecto preguntar vía `AskUserQuestion`); **memoria persistente** (logs append-only / JSON mediante la variable `${CLAUDE_PLUGIN_DATA}`); **scripts auxiliares** (*« lets Claude spend its turns on composition… rather than reconstructing boilerplate »*); **hooks conditionnels** (habilitados solo durante la skill — p. ej. un hook de seguridad que bloquea comandos destructivos). **Distribución en Anthropic**: las skills se almacenan en `./.claude/skills`, se comparten de forma informal vía Slack en una carpeta sandbox, y luego se promueven mediante **PR** al **marketplace** interno una vez que ganan tracción; **medición de uso** mediante un **hook PreToolUse** que registra las invocaciones (revelando las skills populares frente a las infrautilizadas). Continuación directa de la fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]] (mismo autor) y complemento concreto a las fiches sobre Skills de Anthropic/Willison/Vincent y al *harness engineering*.

## Titre Article

Lessons from building Claude Code: How we use skills

## Date

2026-06-03

## URL

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

## Keywords

skills, Claude Code, Anthropic, informe de experiencia interna, carpeta de skill, context engineering, divulgación progresiva, nueve categorías de skills, library API reference, product verification, data fetching analysis, business process automation, code scaffolding, code quality review, CI/CD deployment, runbooks, infrastructure operations, gotchas, sección gotchas, Claude already knows how to code, descripción como disparador, description field is not a summary, flujo de setup, config.json, AskUserQuestion, memoria persistente, logs append-only, CLAUDE_PLUGIN_DATA, scripts auxiliares, composición vs boilerplate, hooks conditionnels, hook de seguridad, hook PreToolUse, medición de uso de skills, marketplace interno, .claude/skills, distribución vía PR, sandbox de Slack, Playwright, tmux, grafana, datadog, adversarial-review, babysit-pr, oncall-runner, Thariq Shihipar, trq212

## Authors

**Thariq Shihipar** (Member of Technical Staff chez Anthropic, équipe **Claude Code** ; @trq212 / @trq sur X, thariqs.github.io), pour le blog **claude.com**. Même auteur que la fiche *Using Claude Code: The Unreasonable Effectiveness of HTML* (2026-05-10). Publié le **3 juin 2026**.

## Ton

**Perfil**: Testimonio de práctica de ingeniero (*builder-to-builder*), primera persona del plural (*« how we use skills »*, *« we use a PreToolUse hook »*), dirigido a una audiencia técnica experimentada — ingenieros y usuarios avanzados que construyen sus propias skills. Registro **didáctico-prescriptivo, denso y operativo**, nivel técnico **alto** (variables de entorno, hooks, árboles de archivos, convenciones de nombrado).

**Estilo**: Prosa de ingeniería estructurada en dos bloques — una **taxonomía** (9 categorías con nombres reales de skills de Anthropic como ejemplos) seguida de una **lista** accionable de buenas prácticas. La autoridad proviene de una posición de **insider**: lo que observa *desde dentro* el equipo que construyó Claude Code. Cada consejo se ancla en un hallazgo concreto (*« common failure points that Claude runs into »*) en lugar de una generalidad. Honestidad sobre el propósito real de los objetos (el `description` sirve al enrutamiento del modelo, no al humano).

**Aforismos clave**:
- ***« Claude already knows how to code and can read your codebase. »*** (anti-redundancia: solo documentar lo que contradice el comportamiento por defecto).
- ***« The highest-signal content in any skill is the Gotchas section. »***
- ***« You should think of the entire file system as a form of context engineering and progressive disclosure. »***
- ***« The description field is not a summary, it's a description of when to trigger this skill. »***
- ***« Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate. »***

**Metáforas / marcos en juego**:
- ***El sistema de archivos como context engineering*** — el árbol de archivos de una skill = un mecanismo de divulgación progresiva, no una simple bolsa de instrucciones.
- ***La descripción como disparador, no como resumen*** — reorienta la escritura hacia el enrutamiento del modelo.
- ***Los turns del modelo como recurso escaso*** — los scripts auxiliares reservan el razonamiento para la composición de alto nivel.
- ***El ciclo de vida orgánico de las skills*** — desde una carpeta sandbox compartida en Slack hasta la promoción vía PR al marketplace, medido por hooks de uso.

**Posición epistémica**: testimonio de autoridad interna (Anthropic / equipo Claude Code), rico en ejemplos nombrados; prescriptivo pero fundamentado en la observación empírica del uso a escala de empresa. Debe ponderarse como el informe de experiencia de un proveedor (no un estudio independiente), pero con fuerte credibilidad sobre el «cómo» operativo.

**Autoridad**: (a) **insider de Anthropic** sobre la herramienta de referencia; (b) **taxonomía inmediatamente reutilizable** (9 categorías que cubren todo el SDLC + ops); (c) **ejemplos concretos** de nombres reales de skills; (d) consejos **probados a escala** (marketplace + medición de uso interna).

## Pense-betes

- **Fecha / fuente**: **3 de junio de 2026**, blog **claude.com** (Anthropic). Autor: **Thariq Shihipar** (equipo Claude Code, @trq212). Continuación directa de su fiche [[shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10]].
- **Encuadre clave**: una Skill = **una carpeta** (instrucciones + scripts + recursos + configuración + hooks), no un único archivo .md. *« The entire file system as a form of context engineering and progressive disclosure. »* ### Las 9 categorías de skills (taxonomía de Anthropic) | # | Categoría | Propósito | Ejemplos citados | |---|-----------|----------|----------------| | 1 | **Library/API Reference** | Documentación de libs/CLIs internas + gotchas | `billing-lib`, `internal-platform-cli`, `sandbox-proxy` | | 2 | **Product Verification** | Pruebas/verificación (Playwright, tmux) | `signup-flow-driver`, `checkout-verifier`, `tmux-cli-driver` | | 3 | **Data Fetching & Analysis** | Acceso a datos/monitorización + patrones de consulta | `funnel-query`, `cohort-compare`, `grafana`, `datadog` | | 4 | **Business Process Automation** | Flujos de trabajo repetitivos | `standup-post`, `weekly-recap`, `create-<ticket>-ticket` | | 5 | **Code Scaffolding** | Boilerplate de frameworks | `new-migration`, `create-app`, `new-<framework>-workflow` | | 6 | **Code Quality & Review** | Estilo + revisión | `adversarial-review`, `code-style`, `testing-practices` | | 7 | **CI/CD & Deployment** | Build / push / deploy | `babysit-pr`, `deploy-<service>`, `cherry-pick-prod` | | 8 | **Runbooks** | Diagnósticos multi-herramienta por síntoma | `<service>-debugging`, `oncall-runner`, `log-correlator` | | 9 | **Infrastructure Operations** | Mantenimiento + salvaguardas | `<resource>-orphans`, `dependency-management`, `cost-investigation` | ### Buenas prácticas (checklist)
- **Anti-redundancia**: *« Claude already knows how to code »* → documentar únicamente lo que **contradice el enfoque por defecto del modelo**.
- **Sección Gotchas** = contenido de **mayor señal**; construirla a partir de puntos de fallo reales (p. ej. incoherencias en el nombrado de campos, tablas append-only).
- **Divulgación progresiva**: dirigir a Claude hacia archivos de referencia según la situación, en lugar de cargar todo por adelantado.
- **Flexibilidad**: dar la información necesaria sin sobre-restringir — dejar que el agente se adapte.
- **Flujo de setup**: almacenar la configuración (`config.json`); si falta, preguntar al usuario vía **`AskUserQuestion`**.
- **Descripción = disparador**: escribir para el **enrutamiento del modelo**, con frases de activación — *« not a summary, it's a description of when to trigger this skill »*.
- **Memoria**: logs append-only / JSON, directorio estable vía **`${CLAUDE_PLUGIN_DATA}`** → el agente recuerda ejecuciones pasadas.
- **Scripts auxiliares**: proporcionar libs/funciones → el agente dedica sus *turns* a la **composición**, no a reconstruir boilerplate.
- **Hooks conditionnels**: habilitados **solo** durante la invocación de la skill y por la duración de la sesión (p. ej. un hook que bloquea comandos destructivos) — útiles en contexto, indeseables de forma *always-on*. ### Distribución y medición (en Anthropic)
- Skills almacenadas en **`./.claude/skills`** (repo) o vía un **marketplace** interno de plugins.
- **Ciclo orgánico**: carpeta sandbox → compartición informal en Slack → tracción → **PR** al marketplace.
- **Medición de uso**: **hook PreToolUse** que registra las invocaciones → identifica skills populares frente a infrautilizadas. ### A aprovechar en misiones / presentaciones
- **Rejilla de mapeo lista para usar**: auditar las skills de un equipo frente a las **9 categorías** (cubre dev + datos + ops + proceso), detectar las carencias.
- El tríptico **Gotchas / divulgación progresiva / descripción-como-disparador** = reglas de oro para escribir skills, dignas de integrarse en una *guideline* de escritura de skills a nivel de firma.
- Converge con *harness engineering* (Böckeler, nivel 5 de la escala Every [[taylor-entis-every-eight-levels-ai-adoption-2026-06-02]]) y con las fiches sobre Skills (Anthropic *Agent Skills*, Willison, Vincent *Superpowers*, Lattice). Contribución específica: **retroalimentación de uso a escala empresarial** + la **mecánica de distribución/medición**.

## RésuméDe400mots

Publicado el **3 de junio de 2026** en el blog de Anthropic por **Thariq Shihipar** (equipo Claude Code), este artículo destila la experiencia interna de la empresa sobre el uso de las **Skills**. El encuadre inicial corrige una visión reductora: una Skill no es un archivo markdown aislado sino una **carpeta** que reúne instrucciones, scripts, recursos, configuración y hooks, que el agente **explora y manipula**. La máxima estructurante: *« You should think of the entire file system as a form of context engineering and progressive disclosure. »*

El artículo ofrece primero una **taxonomía de nueve categorías** de skills observadas en Anthropic, ilustradas con nombres reales: **(1) Library/API Reference** (documentación de libs/CLIs internas con gotchas); **(2) Product Verification** (pruebas vía Playwright/tmux); **(3) Data Fetching & Analysis** (grafana, datadog, patrones de consulta estándar); **(4) Business Process Automation** (standups, recaps, tickets); **(5) Code Scaffolding** (boilerplate, migraciones); **(6) Code Quality & Review** (`adversarial-review`, code-style); **(7) CI/CD & Deployment** (`babysit-pr`, deploy); **(8) Runbooks** (diagnósticos multi-herramienta por síntoma); **(9) Infrastructure Operations** (mantenimiento con salvaguardas).

A continuación viene un cuerpo de **buenas prácticas**. La primera es la **anti-redundancia**: *« Claude already knows how to code and can read your codebase »* — hay que documentar lo que **contradice el comportamiento por defecto**, no lo obvio. El contenido más valioso es la **sección Gotchas** (*« the highest-signal content in any skill »*), alimentada por puntos de fallo realmente encontrados. La **divulgación progresiva** opera a través del árbol de archivos: se dirige a Claude hacia el archivo de referencia correcto según la situación. Las **descripciones** deben escribirse para el **modelo**, no para el humano: *« the description field is not a summary, it's a description of when to trigger this skill. »* Para la configuración, un **flujo de setup** almacena los parámetros (`config.json`) o pregunta al usuario vía `AskUserQuestion`. La **memoria persistente** pasa por logs append-only/JSON en el directorio estable `${CLAUDE_PLUGIN_DATA}`. Los **scripts auxiliares** liberan el razonamiento del modelo: *« lets Claude spend its turns on composition… rather than reconstructing boilerplate. »* Por último, los **hooks conditionnels** (p. ej. el bloqueo de comandos destructivos) solo se habilitan durante la skill.

En cuanto a la **distribución**, Anthropic almacena sus skills en `./.claude/skills`; emergen en una carpeta sandbox compartida vía Slack, ganan tracción, y luego se promueven mediante **PR** a un marketplace interno. El **uso se mide** mediante un hook PreToolUse que registra las invocaciones, revelando las skills populares y las que necesitan revisión. Una guía operativa directamente reutilizable para escribir, distribuir y medir skills a escala organizacional.

## GrapheDeConnaissance

- Thariq Shihipar —publie→ Lessons from building Claude Code: How we use skills (DOCUMENT, 0.97)
- Anthropic —publie→ Lessons from building Claude Code: How we use skills (DOCUMENT, 0.97)
- Thariq Shihipar —fait_partie_de→ équipe Claude Code (ORGANISATION, 0.95)
- Skill —est_instance_de→ dossier d'instructions scripts et ressources (CONCEPT, 0.95)
- Skill —est_instance_de→ progressive disclosure (METHODOLOGIE, 0.93)
- Anthropic —utilise→ taxonomie 9 catégories de skills (CONCEPT, 0.92)
- Thariq Shihipar —affirme_que→ la section Gotchas est le contenu à plus fort signal d'une skill (AFFIRMATION, 0.93)
- champ description —permet→ Skill (CONCEPT, 0.94)
- helper scripts —permet→ de consacrer les turns du modèle à la composition (CONCEPT, 0.9)
- CLAUDE_PLUGIN_DATA —permet→ un répertoire stable de mémoire persistante (CONCEPT, 0.9)
- hooks conditionnels —s_applique_à→ Skill (CONCEPT, 0.9)
- Anthropic —utilise→ un marketplace interne par PR pour distribuer les skills (METHODOLOGIE, 0.88)
- hook PreToolUse —mesure→ l'usage des skills (CONCEPT, 0.9)
- Thariq Shihipar —recommande→ ne pas documenter ce que Claude sait déjà (AFFIRMATION, 0.92)
- AskUserQuestion —permet→ Skill (CONCEPT, 0.85)

---
Canonical: https://www.thekb.eu/es/fiches/shihipar-claude-code-lessons-building-skills-2026-06-03/