Mineração de Skills: De 3.500 Candidatas a 466 Capacidades

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

O Problema das 3.500 Skills

Quando começamos a construir um sistema de orquestração de agentes, enfrentamos um desafio interessante: existem milhares de skills potenciais espalhadas pelo ecossistema de IA. Repositórios no GitHub, documentação de fornecedores, projetos de comunidade, padrões internos — skills existem em todo lugar. Mas quais realmente importam? Quais funcionam? E como você mantém uma biblioteca de skills coerente que os agentes conseguem realmente usar?

Nossa resposta: um loop sistemático de mineração e ingestão.

Os Números de Hoje

Pouco mais de três meses depois de a Anthropic lançar os Agent Skills em 16 de outubro de 2025, aqui está onde estávamos quando este post foi publicado, em 27 de janeiro de 2026:

Métrica	Quantidade
Candidatas identificadas	3.500+
Skills adotadas	466
Skills de fornecedores	373
Skills internas	93
Fornecedores ativos	25+
Tokens médios por skill	2.834
Ferramentas referenciadas	89
Tags únicas	635

Revisamos mais de 3.500 skills candidatas. Adotamos 466. Isso é uma taxa de adoção de 13% — e essa seletividade é proposital.

O Sistema de Camadas de Conhecimento

Nem todas as skills são criadas iguais. Nós as organizamos em cinco camadas de conhecimento (K0-K4), cada uma representando um escopo diferente de aplicabilidade:

K0: Fundamentos (Universal)

Skills que todo agente deveria ter. Elas representam capacidades de “bom pensador” que funcionam em qualquer 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

As skills K0 são portáteis para qualquer projeto, qualquer domínio, qualquer stack. Elas codificam padrões cognitivos universais.

K1: Identidades (Disciplina)

Skills de “bom engenheiro” ou “bom pesquisador” que se aplicam entre projetos dentro de uma disciplina.

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

K2: Domínios (Expertise no Assunto)

Skills de “bom especialista em banco de dados” ou “bom engenheiro de segurança” portáteis dentro de um 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 (Tecnologia)

Skills de “bom usuário do Supabase” ou “bom desenvolvedor Cloudflare” para stacks de tecnologia específicas.

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

K4: Projeto (Organização)

Skills específicas da nossa organização e dos nossos workflows.

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

O Loop de Mineração

Fase 1: Descoberta

As skills vêm de todo lugar:

Repositórios de fornecedores: AWS, Anthropic, Cloudflare, Supabase e colaboradores da comunidade publicam coleções de skills. Rastreamos mais de 25 raízes de fornecedores.

Projetos de comunidade: o GitHub está cheio de templates para Claude Code, padrões de agente e definições de workflow.

Padrões internos: à medida que a nossa equipe resolve problemas, padrões emergem. Eles são formalizados em skills.

Mineração de documentação: a documentação técnica frequentemente contém skills implícitas — procedimentos, checklists, árvores de decisão.

A descoberta é contínua. Usamos um backlog de skills para rastrear candidatas antes da avaliação formal.

Fase 2: Avaliação

Toda candidata passa pela mesma rubrica:

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

Os cinco critérios de produto precisam passar. É por isso que 87% das candidatas são rejeitadas.

Depois, toda candidata passa por uma revisão de confiança separada. Não tratamos um repositório oficial de fornecedor, um mantenedor de comunidade bem conhecido e um repositório aleatório do GitHub como fontes de verdade 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

Fornecedores confiáveis recebem uma revisão de proveniência mais leve, mas não um passe livre. Fontes não confiáveis ou desconhecidas recebem uma auditoria manual mais profunda, e não executamos scripts empacotados até que eles tenham sido lidos, delimitados em escopo e classificados como seguros.

Análise de lacunas: antes de adotar, buscamos no nosso registro:

uv run orkestra skills search "<capability>"

Se já temos, não precisamos dela. Se temos algo próximo, podemos mesclar em vez de adotar.

Pontuação de profundidade e padrões: também pontuamos o quão plenamente uma candidata usa o modelo agent-skill. Um único SKILL.md isolado ainda pode ser útil, mas skills mais profundas são mais valiosas quando separam instruções de referências, scripts e assets da forma que agentskills.io incentiva.

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

Estrelas no GitHub podem elevar um pouco a pontuação de credibilidade, mas nunca resgatam uma skill rasa ou insegura. Um repositório com muitas estrelas e um único SKILL.md vago com scripts opacos pontua abaixo de um repositório menor com uma descrição precisa, references/ curados, e helpers atômicos que realmente aproveitam a capacidade completa do modelo de skill.

Análise estrutural: verificamos a qualidade da skill:

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

Se uma candidata inclui scripts, essa revisão fica mais rigorosa. Uma boa skill não é apenas útil; ela precisa ser legível, delimitada e segura para entregar a um agente. Só esse filtro de segurança já desqualifica uma fatia significativa de candidatas que, de outra forma, seriam interessantes.

Fase 3: Ingestão

Quando uma skill passa na avaliação, ela entra no registro. Mas skills nunca são adotadas sem alterações. Elas são modificadas para se encaixar no nosso sistema.

Modificações na adoção:

1. Normalização de metadados: toda skill recebe o nosso schema de frontmatter
2. Atribuição de camada K: as skills são colocadas na camada de conhecimento apropriada
3. Enriquecimento de tags: tags são adicionadas para descoberta
4. Declaração de ferramentas: as ferramentas permitidas são declaradas explicitamente
5. Alinhamento de seções: o conteúdo é reestruturado para corresponder ao nosso template

Um YAML de skill típico após a ingestão:

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: Atribuição de Escopo

As skills são atribuídas a escopos — categorias que determinam quais agentes carregam quais 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

Os agentes declaram seus escopos, e as skills são atribuídas automaticamente:

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

Fase 5: Materialização

As skills não vivem como YAML em produção. Elas são renderizadas em arquivos SKILL.md que o Claude Code consegue carregar:

uv run orkestra sync

Esse comando:

1. Lê todas as definições YAML de skill
2. Renderiza-as através de templates Jinja
3. Escreve arquivos SKILL.md em .claude/skills/
4. Organiza por camada K (foundations/, identities/, domains/, stacks/, project/)

A estrutura de saída final:

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

O Padrão de Escopo Dormente

Um dos nossos padrões mais poderosos são as skills “adotadas mas não carregadas”. Chamamos isso de escopos dormentes.

Considere as skills de computação científica do repositório k-dense-scientific. Adotamos mais de 120 skills cobrindo bioinformática, química, computação quântica e informática clínica. Mas a maioria dos nossos agentes não precisa de docking molecular ou análise de expressão gênica.

Em vez de carregar todas as 120 skills em cada agente (inchando as janelas de contexto), nós:

1. Adotamos as skills com um escopo específico (por exemplo, bioinformatics)
2. Mantemos-nas dormentes — registradas, mas não carregadas
3. Habilitamos apenas quando um agente declara aquele escopo

# 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

Esse padrão nos permite ter 466 skills no registro, enquanto agentes típicos carregam apenas de 40 a 60 relevantes.

Tipos de Skill

As skills vêm em três padrões cognitivos:

Workflow

Passos procedurais ordenados: “1. Faça X, 2. Depois Y, 3. Por fim Z”

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

Disciplina

Barreiras comportamentais: “Sempre X”, “Nunca Y”, “Prefira Z”

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

Checklist

Critérios de verificação: “Confirme X”, “Verifique Y”, “Cheque Z”

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

Gates de Qualidade

Toda skill precisa passar por validação antes de ir para produção:

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

As descrições precisam ter de 50 a 400 caracteres com frases de acionamento (“Use quando…”, “Quando você precisar de…”) para que o Claude Code saiba quando sugeri-las.

Validamos continuamente:

uv run orkestra validate --show-warnings

O Ecossistema de Fornecedores

Nossas 373 skills de fornecedores vêm de:

Fornecedor	Skills	Domínio
AWS Agent	19	Serviços de nuvem
Anthropic	12	Geração de documentos
Cloudflare	8	Edge computing
Supabase	5	Banco de dados
k-dense	100+	Computação científica
silvainfm	4	Ciência de dados
Java Developer Kit	45+	Spring/Java
Vercel	1	Automação de navegador

Cada raiz de fornecedor é declarada em 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

Quando orkestra sync roda, as skills de fornecedores são simlinkadas em .claude/skills/vendor/ com o namespace do respectivo fornecedor.

O Que Aprendemos

Seletividade compensa. É tentador adotar tudo que parece útil. Mas cada skill custa tokens. Com uma média de 2.834 tokens por skill, o inchaço dói rápido. Nossa taxa de adoção de 13% mantém os agentes enxutos.

Estrutura viabiliza a descoberta. O sistema de camadas K não é só organização — é sobre portabilidade. Skills K0 podem ser reutilizadas em qualquer lugar. Skills K4 são intencionalmente específicas de projeto. Essa clareza ajuda tanto humanos quanto agentes a encontrar o que precisam.

Escopos dormentes escalam. Você pode adotar centenas de skills sem carregá-las todas. Escopos permitem construir um registro abrangente mantendo as janelas de contexto de cada agente gerenciáveis.

A modificação na adoção é essencial. Skills brutas de fornecedores raramente se encaixam no seu sistema. O processo de ingestão — adicionar metadados, atribuir camadas, enriquecer tags — faz skills externas funcionarem internamente.

A mineração é contínua. O número de 3.500 continua crescendo. Novos repositórios de fornecedores aparecem. Padrões de comunidade emergem. Workflows internos se solidificam. O loop nunca para.

O Que Vem a Seguir

Estamos trabalhando em várias melhorias:

1. Detecção automatizada de lacunas: alertar quando falhas comuns de agente poderiam ser resolvidas por uma skill ainda não adotada
2. Workflows de descontinuação de skill: processo formal para aposentar skills que foram substituídas ou não são usadas
3. Dependências entre skills: declaração explícita de pré-requisitos de skill
4. Analytics de uso: rastrear quais skills os agentes realmente invocam versus apenas carregam

O loop de mineração de skills é infraestrutura. Não é glamouroso. Mas é o que faz 41 agentes funcionarem de forma coerente com 466 capacidades, permanecendo dentro dos limites de contexto.

Essa é a história de como 3.500 se tornam 466. Não ignorando 3.000 — avaliando-as sistematicamente e adotando apenas o que funciona.

---

Quer ver o sistema de skills em ação? Confira uv run orkestra skills list para explorar o nosso registro atual.