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

Canonical source: https://maguyva.ai/pt-br/blog/skill-mining-3500-and-counting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-27 · Author: Maguyva Team

> Avaliamos 3.500 skills candidatas e adotamos 466. Um loop sistemático de mineração e ingestão para construir uma biblioteca coerente de skills para agentes de IA em escala.

> *Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa [página da equipe](/pt-br/team) 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 fluxos de trabalho.

```
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 fluxos de trabalho.

**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:

```yaml
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 ser atendidos. É 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.

```yaml
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:

```bash
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.

```yaml
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, referências selecionadas em `references/`, e helpers atômicos que realmente aproveitam a capacidade completa do modelo de skill.

**Análise estrutural**: verificamos a qualidade da skill:

```bash
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:

```yaml
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:

```yaml
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:

```yaml
# 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:

```bash
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

```yaml
# 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:

### Fluxo de trabalho

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

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

### Disciplina

Barreiras comportamentais: "Sempre X", "Nunca Y", "Prefira Z"

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

### Checklist

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

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

## Controles de Qualidade

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

```yaml
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:

```bash
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:

```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 vinculadas por links simbólicos 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. Fluxos de trabalho 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. **Fluxos de trabalho de descontinuação de skills**: 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.*