Minería de skills: de 3,500 candidatas a 466 capacidades

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

El problema de las 3,500 skills

Cuando empezamos a construir un sistema de orquestación de agentes, enfrentamos un desafío interesante: hay miles de skills potenciales dispersas por todo el ecosistema de IA. Repositorios de GitHub, documentación de proveedores, proyectos comunitarios, patrones internos: las skills existen en todas partes. Pero ¿cuáles importan? ¿Cuáles funcionan? ¿Y cómo mantienes una biblioteca de skills coherente que los agentes realmente puedan usar?

Nuestra respuesta: un bucle sistemático de minería e ingesta.

Los números de hoy

Apenas tres meses después de que Anthropic lanzara Agent Skills el 16 de octubre de 2025, así estábamos parados cuando se publicó esta entrada el 27 de enero de 2026:

Métrica	Cantidad
Candidatas identificadas	3,500+
Skills adoptadas	466
Skills de proveedores	373
Skills internas	93
Proveedores activos	25+
Tokens promedio por skill	2,834
Herramientas referenciadas	89
Etiquetas únicas	635

Revisamos más de 3,500 skills candidatas. Adoptamos 466. Eso es una tasa de adopción del 13% — y esa selectividad es deliberada.

El sistema de niveles de conocimiento

No todas las skills son iguales. Las organizamos en cinco capas de conocimiento (K0-K4), cada una representando un alcance de aplicabilidad distinto:

K0: fundamentos (universal)

Skills que todo agente debería tener. Representan capacidades de «buen pensador» que funcionan en cualquier lugar.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Las skills K0 son portables a cualquier proyecto, cualquier dominio, cualquier stack. Codifican patrones cognitivos universales.

K1: identidades (disciplina)

Skills de «buen ingeniero» o «buen investigador» que aplican en distintos proyectos dentro de una disciplina.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: dominios (experticia temática)

Skills de «buen experto en bases de datos» o «buen ingeniero de seguridad» portables dentro de un campo.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: stacks (tecnología)

Skills de «buen usuario de Supabase» o «buen desarrollador de Cloudflare» para stacks tecnológicos específicos.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: proyecto (organización)

Skills específicas de nuestra organización y nuestros flujos de trabajo.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

El bucle de minería

Fase 1: descubrimiento

Las skills vienen de todas partes:

Repositorios de proveedores: AWS, Anthropic, Cloudflare, Supabase y colaboradores de la comunidad publican colecciones de skills. Rastreamos más de 25 raíces de proveedores.

Proyectos comunitarios: GitHub está lleno de plantillas de Claude Code, patrones de agentes y definiciones de flujos de trabajo.

Patrones internos: a medida que nuestro equipo resuelve problemas, emergen patrones. Estos se formalizan en skills.

Minería de documentación: la documentación técnica a menudo contiene skills implícitas — procedimientos, listas de verificación, árboles de decisión.

El descubrimiento es continuo. Usamos un backlog de skills para rastrear candidatas antes de la evaluación formal.

Fase 2: evaluación

Cada candidata pasa por la misma rúbrica:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Los cinco criterios de producto deben aprobarse. Por eso se rechaza el 87% de las candidatas.

Luego cada candidata pasa por una revisión de confianza separada. No tratamos un repositorio oficial de un proveedor, un mantenedor de la comunidad bien conocido y un repositorio aleatorio de GitHub como fuentes de verdad equivalentes.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Los proveedores confiables reciben una revisión de procedencia más ligera, pero no un pase libre. Las fuentes no confiables o desconocidas reciben una auditoría manual más profunda, y no ejecutamos scripts incluidos hasta que hayan sido leídos, delimitados y clasificados como seguros.

Análisis de brechas: antes de adoptar, buscamos en nuestro registro:

uv run orkestra skills search "<capability>"

Si ya lo tenemos, no lo necesitamos. Si tenemos algo cercano, podríamos fusionar en lugar de adoptar.

Puntuación de profundidad y estándares: también puntuamos qué tan a fondo una candidata usa el modelo agent-skill. Un solo SKILL.md todavía puede ser útil, pero las skills más profundas son más valiosas cuando separan las instrucciones de las referencias, scripts y assets de la manera que agentskills.io recomienda.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Las estrellas de GitHub pueden elevar un poco un puntaje de credibilidad, pero nunca rescatan a una skill superficial o insegura. Un repositorio con muchas estrellas y un solo SKILL.md vago y scripts opacos puntúa por debajo de un repositorio más pequeño con una descripción precisa, references/ curados, y helpers atómicos que realmente aprovechan toda la capacidad de la skill.

Análisis estructural: verificamos la calidad de la skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Si una candidata incluye scripts, esa revisión se vuelve más estricta. Una buena skill no solo es útil; tiene que ser legible, acotada y segura de entregar a un agente. Ese filtro de seguridad por sí solo descalifica una porción significativa de candidatas por lo demás interesantes.

Fase 3: ingesta

Cuando una skill pasa la evaluación, entra al registro. Pero las skills nunca se adoptan sin cambios. Se modifican para encajar en nuestro sistema.

Modificaciones al adoptar:

1. Normalización de metadatos: cada skill recibe nuestro esquema de frontmatter
2. Asignación de nivel K: las skills se colocan en la capa de conocimiento correspondiente
3. Enriquecimiento de etiquetas: se agregan etiquetas para facilitar el descubrimiento
4. Declaración de herramientas: las herramientas permitidas se declaran explícitamente
5. Alineación de secciones: el contenido se reestructura para coincidir con nuestra plantilla

Un YAML de skill típico después de la ingesta:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: asignación de alcance

Las skills se asignan a alcances (scopes) — categorías que determinan qué agentes cargan qué skills:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Los agentes declaran sus alcances, y las skills se asignan automáticamente:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: materialización

Las skills no viven como YAML en producción. Se renderizan en archivos SKILL.md que Claude Code puede cargar:

uv run orkestra sync

Este comando:

1. Lee todas las definiciones YAML de skills
2. Las renderiza mediante plantillas Jinja
3. Escribe archivos SKILL.md en .claude/skills/
4. Organiza por nivel K (foundations/, identities/, domains/, stacks/, project/)

La estructura de salida final:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

El patrón de alcance latente

Uno de nuestros patrones más poderosos son las skills «adoptadas pero no cargadas». Las llamamos alcances latentes (dormant scopes).

Considera las skills de computación científica del repositorio k-dense-scientific. Adoptamos más de 120 skills que cubren bioinformática, química, computación cuántica e informática clínica. Pero la mayoría de nuestros agentes no necesitan acoplamiento molecular ni análisis de expresión génica.

En lugar de cargar las 120 skills en cada agente (inflando las ventanas de contexto), nosotros:

1. Adoptamos las skills con un alcance específico (por ejemplo, bioinformatics)
2. Las mantenemos latentes — registradas pero no cargadas
3. Las habilitamos solo cuando un agente declara ese alcance

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Este patrón nos permite tener 466 skills en el registro mientras los agentes típicos solo cargan entre 40 y 60 relevantes.

Tipos de skills

Las skills vienen en tres patrones cognitivos:

Workflow (flujo de trabajo)

Pasos procedimentales ordenados: «1. Haz X, 2. Luego Y, 3. Finalmente Z»

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline (disciplina)

Barandillas de comportamiento: «Siempre X», «Nunca Y», «Prefiere Z»

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist (lista de verificación)

Criterios de verificación: «Confirma X», «Verifica Y», «Revisa Z»

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Compuertas de calidad

Cada skill debe pasar la validación antes de lanzarse:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Las descripciones deben tener entre 50 y 400 caracteres con frases de activación («Usar cuando…», «Cuando necesites…») para que Claude Code sepa cuándo sugerirlas.

Validamos continuamente:

uv run orkestra validate --show-warnings

El ecosistema de proveedores

Nuestras 373 skills de proveedores vienen de:

Proveedor	Skills	Dominio
AWS Agent	19	Servicios en la nube
Anthropic	12	Generación de documentos
Cloudflare	8	Edge computing
Supabase	5	Bases de datos
k-dense	100+	Computación científica
silvainfm	4	Ciencia de datos
Java Developer Kit	45+	Spring/Java
Vercel	1	Automatización de navegador

Cada raíz de proveedor se declara en metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Cuando se ejecuta orkestra sync, las skills de proveedores se enlazan simbólicamente en .claude/skills/vendor/ con su espacio de nombres de proveedor.

Lo que hemos aprendido

La selectividad rinde frutos. Es tentador adoptar todo lo que parece útil. Pero cada skill cuesta tokens. Con un promedio de 2,834 tokens por skill, el exceso duele rápido. Nuestra tasa de adopción del 13% mantiene a los agentes ligeros.

La estructura habilita el descubrimiento. El sistema de niveles K no es solo organización, se trata de portabilidad. Las skills K0 se pueden reutilizar en cualquier lugar. Las skills K4 son deliberadamente específicas del proyecto. Esta claridad ayuda tanto a humanos como a agentes a encontrar lo que necesitan.

Los alcances latentes escalan. Puedes adoptar cientos de skills sin cargarlas todas. Los alcances te permiten construir un registro exhaustivo mientras mantienes manejables las ventanas de contexto de cada agente.

La modificación al adoptar es esencial. Las skills de proveedores en bruto rara vez encajan en tu sistema. El proceso de ingesta — agregar metadatos, asignar niveles, enriquecer etiquetas — hace que las skills externas funcionen internamente.

La minería es continua. El número 3,500 sigue creciendo. Aparecen nuevos repositorios de proveedores. Emergen patrones comunitarios. Se solidifican flujos de trabajo internos. El bucle nunca se detiene.

Qué sigue

Estamos trabajando en varias mejoras:

1. Detección automatizada de brechas: alertar cuando fallos comunes de agentes podrían resolverse con una skill no adoptada
2. Flujos de desuso de skills: proceso formal para retirar skills que fueron reemplazadas o que no se usan
3. Dependencias entre skills: declaración explícita de los prerrequisitos de una skill
4. Analítica de uso: rastrear qué skills invocan realmente los agentes frente a cuáles solo cargan

El bucle de minería de skills es infraestructura. No es glamoroso. Pero es lo que hace que 41 agentes funcionen de forma coherente con 466 capacidades mientras se mantienen dentro de los límites de contexto.

Esa es la historia de cómo 3,500 se convierte en 466. No ignorando 3,000, sino evaluándolas sistemáticamente y adoptando solo lo que funciona.

---

¿Quieres ver el sistema de skills en acción? Consulta uv run orkestra skills list para explorar nuestro registro actual.