Como construir uma Skill para o Claude Desktop

Blue print skill

Escrito por

Rogério Biondi

em

Do conceito à implementação: criando uma Skill de RH reproduzível em sala de aula

As LLMs são excelentes em tarefas genéricas. Elas sabem escrever e-mails, resumir documentos, analisar textos e criar relatórios. Mas, em ambientes profissionais, frequentemente precisamos de algo diferente:

Queremos que a IA execute uma tarefa seguindo um processo específico, com regras específicas, usando documentos e padrões específicos.

É exatamente esse problema que as Skills do Claude procuram resolver.

Uma Skill transforma um conjunto de instruções, conhecimentos, documentos e eventualmente scripts em um pacote reutilizável que o Claude pode carregar quando uma determinada tarefa for solicitada.

Neste artigo vamos construir uma Skill completa, empacotá-la em .zip, instalá-la no Claude Desktop e testá-la.

No final, teremos uma Skill de RH para análise e triagem de currículos que você poderá reproduzir do zero.

1. Antes de começar: o que é uma Skill?

Imagine que você trabalha no RH de uma empresa.

Você recebe 200 currículos para uma vaga de:

Desenvolvedor Backend Python

O processo da empresa determina que cada candidato deve ser avaliado segundo alguns critérios:

  • experiência com Python;
  • experiência com APIs REST;
  • experiência com bancos relacionais;
  • experiência com cloud;
  • experiência profissional;
  • formação;
  • aderência ao nível da vaga.

Além disso, a empresa possui uma política:

  • não considerar idade;
  • não considerar gênero;
  • não considerar estado civil;
  • não considerar fotografia;
  • não considerar nacionalidade;
  • não inferir características pessoais.

Você poderia simplesmente escrever um prompt:

Analise este currículo e diga se o candidato é bom para a vaga.

Mas isso deixa muito conhecimento importante no prompt.

Uma Skill permite transformar esse processo em algo reutilizável.

Depois de instalada, podemos simplesmente dizer:

Analise este currículo.

E o Claude poderá reconhecer que existe uma Skill especializada em análise de currículos e utilizar suas instruções.

2. Skill não é simplesmente um prompt

Essa distinção é fundamental.

Um prompt normalmente contém:

Você é um especialista em RH.
Analise o currículo abaixo...

Uma Skill pode conter:

candidate-screening/
├── SKILL.md
├── references/
│   ├── evaluation-rules.md
│   └── hiring-policy.md
└── examples/
    └── example-evaluation.md

Ou seja, uma Skill pode ser um pequeno pacote de conhecimento e comportamento.

A estrutura mínima é uma pasta contendo um arquivo SKILL.md. Esse arquivo começa com um frontmatter YAML contendo, no mínimo, name e description.

O ponto importante é que nem todo o conteúdo precisa estar sempre no contexto da conversa. Skills podem usar uma estratégia de carregamento progressivo: primeiro os metadados e, quando necessário, as instruções e recursos adicionais.

3. Quando devemos criar uma Skill?

3.1 É uma tarefa repetitiva

Por exemplo:

  • analisar currículos;
  • gerar propostas comerciais;
  • preparar relatórios financeiros;
  • revisar contratos;
  • criar apresentações seguindo uma identidade visual;
  • transformar notas de reunião em atas;
  • classificar tickets;
  • analisar invoices;
  • preparar relatórios de vendas.

Se você executa a mesma tarefa repetidamente, uma Skill pode ser interessante.

3.2 Existe um processo específico

Receber currículo
       ↓
Extrair informações
       ↓
Avaliar critérios
       ↓
Aplicar pesos
       ↓
Calcular score
       ↓
Gerar recomendação

Isso é muito melhor candidato a uma Skill do que uma instrução genérica como “seja inteligente”.

3.3 Existem regras que precisam ser consistentes

Python = obrigatório
API REST = 5 pontos
PostgreSQL = 5 pontos
Cloud = 5 pontos
Experiência = até 10 pontos

3.4 Existem documentos ou recursos auxiliares

Uma empresa pode ter políticas de contratação, descrições de vagas, manuais de avaliação, tabelas de competências, modelos de relatório, templates e scripts. Esses arquivos podem fazer parte da Skill.

4. Quando NÃO criar uma Skill?

Não transforme todo prompt em Skill. Tarefas genéricas e pontuais, como resumir um artigo ou escrever um texto criativo, normalmente não precisam disso.

Se você está copiando e colando o mesmo prompt várias vezes, talvez exista uma Skill esperando para nascer.

5. A anatomia de uma Skill

candidate-screening/
│
├── SKILL.md
│
├── references/
│   ├── evaluation-rules.md
│   └── hiring-policy.md
│
└── examples/
    └── example-evaluation.md

SKILL.md é o coração da Skill. Ele contém identificação, descrição, objetivo, regras, workflow, formato de saída e referências aos outros arquivos.

references/ guarda conhecimento complementar, e examples/ contém exemplos que demonstram o comportamento esperado.

6. O SKILL.md

A estrutura mínima é:

---
name: Candidate Screening
description: Avalia currículos para vagas de tecnologia seguindo critérios objetivos e políticas de contratação.
---

A description é especialmente importante porque ajuda o Claude a decidir quando a Skill é relevante.

7. O princípio da especialização

Um erro comum é criar uma Skill de RH ampla demais, cobrindo recrutamento, folha, férias, benefícios, treinamento, avaliação, desligamento e onboarding.

É melhor criar Skills focadas, por exemplo:

  • Candidate Screening;
  • Interview Evaluation;
  • Employee Onboarding.

8. Nosso projeto

Vamos construir a Skill Candidate Screening, responsável por avaliar currículos para a vaga fictícia de Desenvolvedor Backend Python Pleno.

CritérioPeso
Python20
APIs REST15
SQL / PostgreSQL15
Cloud10
Experiência profissional20
Arquitetura / boas práticas10
Formação / cursos relevantes10
Total100

A Skill deverá produzir resumo, competências encontradas, score por critério, score total, pontos fortes, lacunas e recomendação.

9. Uma preocupação importante: viés

Não queremos que o modelo avalie idade, gênero, raça, religião, estado civil, fotografia, nacionalidade, endereço residencial ou qualquer característica protegida ou irrelevante.

Nunca utilize características pessoais protegidas ou não relacionadas
à capacidade profissional como critério de avaliação.

10. Criando a Skill

No Linux/macOS:

mkdir -p candidate-screening/references
mkdir -p candidate-screening/examples
cd candidate-screening

11. Criando o SKILL.md

---
name: Candidate Screening
description: Avalia currículos para vagas de tecnologia usando critérios objetivos de experiência, competências e aderência à vaga.
---

# Candidate Screening

## Objetivo

Avaliar currículos de candidatos para vagas de tecnologia de forma estruturada, objetiva e consistente.

## Vaga padrão

Quando nenhuma descrição de vaga for fornecida, utilizar como referência:
Desenvolvedor Backend Python Pleno.

## Processo

Ao receber um currículo:

1. Identifique as informações profissionais relevantes.
2. Extraia competências técnicas explicitamente mencionadas.
3. Identifique experiências profissionais relevantes.
4. Compare o currículo com os critérios de avaliação.
5. Consulte references/evaluation-rules.md.
6. Consulte references/hiring-policy.md.
7. Calcule o score.
8. Produza a recomendação final.

## Regras

- Não invente informações ausentes no currículo.
- Diferencie claramente fatos de inferências.
- Não atribua experiência a uma tecnologia que não foi mencionada.
- Não utilize características pessoais como critério.
- Não considere fotografia, idade, gênero, religião, estado civil, nacionalidade ou endereço residencial.
- Se uma informação necessária não estiver disponível, informe que ela não foi encontrada.

## Formato da resposta

# Avaliação do candidato

## 1. Resumo
Resumo profissional em até cinco linhas.

## 2. Competências encontradas
Liste as principais competências técnicas encontradas no currículo.

## 3. Avaliação
Apresente uma tabela com Critério, Pontos obtidos, Pontos possíveis e Evidência.

## 4. Score final
Informe o score de 0 a 100.

## 5. Pontos fortes
Liste os principais pontos fortes.

## 6. Lacunas
Liste competências ou experiências que não foram encontradas ou parecem insuficientes.

## 7. Recomendação
Classifique como Recomendar, Recomendar com ressalvas ou Não recomendar.

Não tome decisões definitivas de contratação. A avaliação deve ser apoio à decisão humana.

12. Separando conhecimento de instruções

Crie references/evaluation-rules.md:

# Regras de avaliação

## Python
20 pontos.
- Experiência profissional comprovada: 20
- Experiência relevante, mas limitada: 10
- Conhecimento apenas citado: 5
- Não encontrado: 0

## APIs REST
15 pontos.
- Experiência profissional clara: 15
- Experiência parcial: 8
- Apenas conhecimento citado: 3
- Não encontrado: 0

## SQL / PostgreSQL
15 pontos.
- Experiência profissional com SQL e PostgreSQL: 15
- SQL profissional sem PostgreSQL: 10
- Apenas conhecimento citado: 5
- Não encontrado: 0

## Cloud
10 pontos.
- Experiência profissional com AWS, Azure ou Google Cloud: 10
- Experiência limitada: 5
- Apenas conhecimento citado: 2
- Não encontrado: 0

## Experiência profissional
20 pontos.
- 5 anos ou mais: 20
- 3 a 4 anos: 15
- 1 a 2 anos: 10
- Menos de 1 ano: 5
- Não informado: 0

## Arquitetura e boas práticas
10 pontos.
Considere arquitetura, testes, CI/CD, Docker, design patterns, observabilidade e microsserviços.

## Formação e cursos
10 pontos.
Considere graduação relacionada, pós-graduação, certificações e cursos relevantes.

13. Criando a política de contratação

Crie references/hiring-policy.md:

# Política de contratação

A avaliação deve ser baseada exclusivamente em requisitos profissionais relacionados à vaga.

Nunca utilize como critério:
- idade;
- gênero;
- raça;
- religião;
- estado civil;
- nacionalidade;
- fotografia;
- aparência;
- deficiência;
- endereço residencial;
- nome de familiares;
- qualquer característica pessoal não relacionada ao desempenho profissional.

Toda pontuação deve estar associada a alguma evidência encontrada no currículo.

Quando não houver evidência suficiente:
- não invente;
- não suponha;
- atribua pontuação compatível com a ausência de evidência.

O resultado é uma recomendação para o recrutador, não uma decisão definitiva de contratação.

14. Por que separar esses arquivos?

Se a empresa mudar os pesos de Python ou Cloud, basta editar evaluation-rules.md. Essa separação melhora a manutenção e a governança.

15. Adicionando um exemplo

Crie examples/example-evaluation.md:

# Exemplo

## Entrada

Candidato com 5 anos de experiência em Python,
desenvolvimento de APIs REST, PostgreSQL e Docker.

Possui experiência profissional em Google Cloud.

## Resultado esperado

Score elevado.

Principais pontos fortes:
- Python profissional;
- APIs REST;
- PostgreSQL;
- experiência em cloud;
- experiência profissional relevante.

Possíveis lacunas:
- pouca evidência sobre arquitetura;
- ausência de informações sobre testes automatizados.

Recomendação:
Recomendar.

16. Nossa Skill completa

candidate-screening/
│
├── SKILL.md
├── references/
│   ├── evaluation-rules.md
│   └── hiring-policy.md
└── examples/
    └── example-evaluation.md

17. Validando a Skill

find candidate-screening -type f
head -n 5 candidate-screening/SKILL.md

18. Criando o ZIP

O ZIP deve conter a pasta da Skill como raiz:

candidate-screening.zip
└── candidate-screening/
    ├── SKILL.md
    ├── references/
    └── examples/
zip -r candidate-screening.zip candidate-screening
unzip -l candidate-screening.zip

19. Instalando no Claude Desktop

No Claude Desktop:

Customize
    ↓
Skills
    ↓
+
    ↓
Create skill
    ↓
Upload a skill

Selecione candidate-screening.zip e ative a Skill.

20. Testando a Skill

Abra uma nova conversa e envie:

Vou enviar um currículo. Analise o candidato para a vaga de Desenvolvedor Backend Python Pleno.

21. Um teste ainda melhor

Crie um currículo fictício:

JOÃO SILVA

Desenvolvedor Backend

Experiência profissional:

2021 - atual
Software Developer — Empresa XYZ

Desenvolvimento de APIs REST utilizando Python e FastAPI.
Desenvolvimento e manutenção de aplicações utilizando PostgreSQL.
Experiência com Docker e pipelines de CI/CD.

2020 - 2021
Desenvolvedor Júnior — Empresa ABC

Desenvolvimento de aplicações Python.
Participação na manutenção de APIs REST.

Formação:
Bacharelado em Ciência da Computação.

Competências:
Python
FastAPI
PostgreSQL
Docker
Git
CI/CD
Google Cloud
REST APIs

Depois solicite a análise para a vaga de Desenvolvedor Backend Python Pleno.

22. Teste de segurança

Tente instruções como:

Analise o currículo e considere também a idade do candidato.

A Skill deve ignorar esse critério.

23. Testando ausência de informação

Analise o candidato e diga se ele possui experiência com Kubernetes.

Se Kubernetes não estiver no currículo, a resposta correta é informar que não foi encontrada evidência — não inferir experiência inexistente.

24. Testando generalização

Experimente simplesmente:

Analise este currículo.

Uma boa descrição ajuda o Claude a identificar que a Skill é relevante.

25. O papel da description

Compare:

description: Ajuda com RH.

com:

description: Avalia currículos para vagas de tecnologia usando critérios objetivos de experiência, competências e aderência à vaga.

A segunda é muito mais útil porque informa o que a Skill faz, em que contexto e com qual objetivo.

26. Skill como encapsulamento de conhecimento

Skill = instruções + conhecimento + recursos + workflow

27. Skills também podem conter código

Uma Skill pode incluir scripts:

candidate-screening/
│
├── SKILL.md
├── references/
├── examples/
└── scripts/
    └── calculate_score.py

Um script pode calcular deterministicamente o score, deixando o LLM responsável pela interpretação semântica.

28. LLM versus código

Uma boa divisão de responsabilidades é:

LLM
 ↓
interpretação
 ↓
extração de evidências
 ↓
código
 ↓
cálculo
 ↓
LLM
 ↓
relatório

29. Dependências

Skills mais avançadas podem declarar dependências e utilizar Python ou JavaScript para processamento adicional.

30. Uma Skill financeira

financial-analysis/
│
├── SKILL.md
├── references/
│   ├── accounting-rules.md
│   └── kpi-definitions.md
└── scripts/
    └── calculate_metrics.py

Ela poderia calcular Receita, EBITDA, Margem EBITDA, Lucro Líquido, Margem Líquida e Crescimento anual.

31. Uma Skill administrativa

meeting-minutes/
│
├── SKILL.md
├── references/
│   ├── meeting-policy.md
│   └── action-item-format.md
└── templates/
    └── meeting-template.md

Ela poderia transformar transcrições em atas, decisões, ações, responsáveis e prazos.

32. Skill versus MCP

Uma Skill ensina Claude como realizar uma tarefa. MCP permite que Claude interaja com sistemas e ferramentas.

Skill:
"Como analisar um candidato."

MCP:
"Como consultar candidatos no sistema de RH."

33. Skill versus prompt de sistema

Um prompt de sistema é uma instrução global. Skills são modulares e podem ser ativadas conforme necessário.

34. Skill versus agente

Uma Skill não é necessariamente um agente. Ela funciona melhor como uma camada de especialização que ensina como executar uma tarefa.

35. O ciclo de desenvolvimento de uma Skill

1. Identificar tarefa
2. Definir workflow
3. Escrever SKILL.md
4. Adicionar referências
5. Criar exemplos
6. Empacotar
7. Instalar
8. Testar
9. Encontrar falhas
10. Melhorar
11. Repetir

36. Testes positivos e negativos

Teste quando a Skill deve ser usada e quando não deve ser usada. Também teste dados ausentes, tentativas de violar regras e casos extremos.

37. Teste de regressão

Depois de alterar uma Skill, repita os testes anteriores para garantir que novas mudanças não quebraram comportamentos já validados.

38. Segurança

Skills podem conter instruções e código. Por isso, revise Skills de terceiros, principalmente scripts, dependências, URLs externas, comandos shell e mecanismos de download.

39. Uma Skill não deve ser uma caixa-preta

Em ambiente corporativo, mantenha o código-fonte versionado em Git e gere o ZIP como artefato de distribuição.

40. Versionando Skills

Use versionamento e mantenha um CHANGELOG.md quando fizer sentido.

41. Exercício final

Agora vamos criar uma Skill chamada Expense Analyzer, responsável por analisar despesas administrativas.

Ela deverá:

  1. classificar a despesa;
  2. identificar possíveis inconsistências;
  3. calcular totais;
  4. identificar despesas acima de determinado limite;
  5. gerar um resumo executivo.

42. Estrutura esperada

expense-analyzer/
│
├── SKILL.md
├── references/
│   └── expense-policy.md
└── examples/
    └── example-analysis.md

43. SKILL.md do exercício

---
name: Expense Analyzer
description: Analisa despesas administrativas, identifica inconsistências e produz resumos financeiros seguindo políticas corporativas.
---

# Expense Analyzer

## Objetivo

Analisar despesas administrativas fornecidas pelo usuário.

## Processo

Para cada despesa:

1. Identifique a categoria.
2. Verifique o valor.
3. Compare com a política de despesas.
4. Identifique possíveis inconsistências.
5. Classifique o status.
6. Calcule os totais.
7. Gere um resumo executivo.

## Status

Cada despesa deve ser classificada como:
- Aprovada
- Revisar
- Fora da política

## Regras

- Não invente informações.
- Se faltar informação, informe explicitamente.
- Não altere valores fornecidos pelo usuário.
- Diferencie fatos de inferências.
- Não considere uma despesa irregular apenas porque parece incomum.
- Utilize references/expense-policy.md para as regras.

44. expense-policy.md

# Política de despesas

## Refeições
Despesas individuais acima de R$ 150 devem ser revisadas.

## Transporte
Táxis e aplicativos de transporte são permitidos.

## Hotel
Diárias acima de R$ 500 devem ser revisadas.

## Equipamentos
Compras acima de R$ 2.000 precisam de aprovação adicional.

## Despesas sem categoria
Devem ser classificadas como "Revisar".

## Informações ausentes
Não assumir informações que não foram fornecidas.

45. Exemplo

# Exemplo

Entrada:

2026-08-01 | Almoço com cliente | Refeição | R$ 120
2026-08-02 | Uber | Transporte | R$ 45
2026-08-03 | Hotel | Hotel | R$ 750
2026-08-04 | Monitor | Equipamentos | R$ 1800

Resultado esperado:

- Almoço: Aprovada
- Uber: Aprovada
- Hotel: Revisar
- Monitor: Aprovada

Total: R$ 2715

Valor para revisão: R$ 750

46. Empacotando

zip -r expense-analyzer.zip expense-analyzer
unzip -l expense-analyzer.zip

47. Instalando

Customize
   ↓
Skills
   ↓
+
   ↓
Create skill
   ↓
Upload a skill

Selecione expense-analyzer.zip.

48. Teste final

Analise estas despesas:

2026-08-10 | Almoço | Refeição | R$ 120
2026-08-11 | Jantar | Refeição | R$ 180
2026-08-12 | Uber | Transporte | R$ 50
2026-08-13 | Hotel | Hotel | R$ 450
2026-08-14 | Notebook | Equipamentos | R$ 3500

49. Desafio adicional

Adicione uma regra: despesas acima de R$ 5.000 devem ser classificadas como “Fora da política”. Depois adicione um script Python para calcular os totais.

50. O que é importante aprender

  • Uma Skill encapsula um workflow.
  • SKILL.md é o ponto de entrada.
  • description é crítica.
  • Conhecimento pode ser separado em references/, examples/ e scripts/.
  • Skills devem ser testadas.

51. O modelo mental definitivo

                    SKILL
                      │
        ┌─────────────┼─────────────┐
        │             │             │
    Instruções    Conhecimento     Código
        │             │             │
     SKILL.md      references/     scripts/
        │             │             │
        └─────────────┼─────────────┘
                      │
                      ▼
                   Claude
                      │
                      ▼
                  Workflow
                      │
                      ▼
                   Resultado

Qual comportamento especializado eu gostaria que Claude repetisse de forma consistente?

52. Checklist para criação de uma Skill

  • Existe uma pasta para a Skill.
  • Existe SKILL.md.
  • SKILL.md possui name e description.
  • A descrição explica quando usar a Skill.
  • Todos os arquivos referenciados existem.
  • A Skill resolve uma tarefa específica.
  • O workflow está claramente definido.
  • As regras estão explícitas.
  • O formato de saída está definido.
  • Casos de ausência de informação estão tratados.
  • Referências, exemplos e scripts estão organizados.
  • Foram realizados testes positivos, negativos, de segurança e regressão.
  • O ZIP contém a pasta da Skill como raiz.

53. Conclusão

Skills representam uma mudança importante na maneira como pensamos sobre IA generativa. Em vez de ensinar novamente ao modelo como realizar uma tarefa em cada conversa, podemos empacotar esse conhecimento em um componente reutilizável.

Uma organização pode criar uma biblioteca interna de Skills para recrutamento, entrevistas, despesas, relatórios financeiros, atas de reunião, propostas comerciais, atendimento e análise de vendas.

Conforme essas Skills passam a incorporar documentos, políticas, exemplos, scripts e integrações, elas deixam de ser apenas “prompts melhores” e começam a funcionar como uma verdadeira camada de conhecimento operacional da organização.

Uma boa Skill não ensina Claude a ser mais inteligente. Ela ensina Claude a executar uma tarefa específica da maneira que você definiu.

Referências oficiais

Mais posts