Lessons from building Claude Code: How we use skills
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).
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).
You should think of the entire file system as a form of context engineering and progressive disclosure.
— **Thariq Shihipar** , claude.com
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.
Puntos clave
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 ».
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.
Afirmaciones atribuidas
la sección Gotchas es el contenido con mayor señal de una skill
— Thariq Shihipar
El grafo de conocimiento extraído de esta ficha — 12 entidades, 15 relaciones.
En este grafo :Thariq Shihipar · Anthropic · Lessons from building Claude Code: How we use skills · Skill · taxonomie 9 catégories de skills · section Gotchas · progressive disclosure · champ description · CLAUDE_PLUGIN_DATA · hooks conditionnels · hook PreToolUse · marketplace interne Anthropic