📁 .claude/skills/ do projeto
O diretório .claude/skills/ fica na raiz do seu repositório. Skills ali têm escopo local — existem apenas para quem trabalha naquele projeto específico.
O diretório .claude/skills/ na raiz do repositório é o espaço de skills com escopo de projeto. Toda skill colocada ali está disponível apenas quando Claude Code estiver rodando dentro desse repo.
Cada skill é uma subpasta. O nome da pasta é exatamente o nome pelo qual Claude a reconhece — ex.: .claude/skills/video-explicativo/.
- ✓ A skill é específica para aquele produto ou cliente
- ✓ Você quer versionar a skill junto com o código
- ✓ Todo o time precisa usar a mesma versão da skill
- ✓ A skill muda a cada sprint junto com o projeto
- ✗ A skill serve para todos os seus projetos pessoais
- ✗ O repo é público e a skill contém dados sensíveis
- ✗ Você está testando um rascunho temporário
- ✗ A skill precisa funcionar fora de qualquer projeto
🌐 ~/.claude/skills/ global
O diretório global fica em ~/.claude/skills/ (home do usuário). Skills ali valem para absolutamente qualquer projeto que você abrir na máquina.
- • Dentro do repositório
- • Versionado no git
- • Compartilhado com o time via clone
- • Escopo: apenas este projeto
- • Na home do usuário
- • Fora de qualquer repo
- • Só na sua máquina (não é clonado)
- • Escopo: todos os projetos
Se existir uma skill com o mesmo nome nos dois lugares (local e global), a versão local (.claude/skills/) tem prioridade. Use isso a seu favor: coloque no projeto uma versão customizada de uma skill que normalmente usa globalmente.
📋 Instalar copiando a pasta
A forma mais simples de instalar uma skill é copiar a pasta — ou descompactar um .zip — no diretório correto. É exatamente assim que você recebeu o skill video-explicativo deste curso.
A skill pode vir como uma pasta comprimida (video-explicativo.zip), um repositório separado, ou simplesmente uma pasta enviada por alguém do time. O conteúdo mínimo é sempre: SKILL.md na raiz da pasta.
Se recebeu um zip: unzip video-explicativo.zip. O resultado deve ser uma pasta com o nome da skill como raiz — confirme antes de mover.
Para escopo local: mv video-explicativo/ .claude/skills/. Para escopo global: mv video-explicativo/ ~/.claude/skills/. Crie o diretório se não existir: mkdir -p .claude/skills/.
Abra o Claude Code na sessão do projeto. A skill já estará disponível — basta invocar pelo nome configurado no SKILL.md. Nenhum restart ou reload necessário.
Não há binários, não há build, não há dependências npm para instalar. Uma skill é 100% arquivos de texto: markdown, scripts shell, templates. Copiar a pasta É a instalação completa.
⌨️ Por comando
Além de copiar manualmente, você pode instalar skills via CLI — como npx skills add — que acessa um catálogo centralizado e faz o download automaticamente.
Ferramentas como npx skills add <nome> abstraem o processo de copiar manualmente: elas buscam o pacote no catálogo, fazem download e colocam no local correto automaticamente.
É o mesmo padrão de npm install mas para skills de Claude Code — sem package.json, sem node_modules, só a pasta da skill.
- ✓ Skills públicas do catálogo oficial
- ✓ Quer garantir a versão mais recente
- ✓ Time novo precisa configurar ambiente rápido
- ✓ Você quer explorar o catálogo de skills disponíveis
- ✗ Skills internas/privadas da empresa (não publicadas)
- ✗ Você precisa de uma versão customizada específica
- ✗ Ambiente sem acesso à internet
- ✗ A skill ainda está em desenvolvimento local
🔁 Versionar no git
Uma skill é texto puro — portanto entra naturalmente no git. Isso significa histórico, diff, revisão de PR, rollback e rastreabilidade completa de quem mudou o quê na skill.
Quando a skill e o código evoluem juntos no mesmo commit, você sempre sabe exatamente qual versão da skill produziu qual output. Nunca mais "a skill mudou e o vídeo ficou diferente" sem rastreamento.
Skills em ~/.claude/skills/ ficam fora de qualquer repositório e NÃO são versionadas automaticamente. Se quiser backup ou histórico da sua skill global, crie um repositório dedicado (ex.: meus-skills-pessoais/) e sincronize manualmente.
Escreve SKILL.md + referências → git add + commit
Corrige prompt, adiciona referência → novo commit — diff visível no PR
Time revisa mudanças na skill igual revisa código — comentários linha a linha
git tag v1.2-skill — freeze da skill em estado estável para produção
🤝 Compartilhar com o time
Skill no repositório significa que todo desenvolvedor que clonar o projeto recebe automaticamente as mesmas skills — sem manual de instalação, sem divergências entre máquinas.
Quando a skill mora em .claude/skills/ no repositório, qualquer git clone entrega o ambiente completo. Novo dev no time? Clone e já tem a skill. Máquina nova? Clone e já funciona.
Isso elimina a pergunta "qual versão da skill você está usando?" — todos usam exatamente o que está no commit atual do repo.
- ✓ Documente a skill no README: o que é, como invocar
- ✓ Inclua exemplos reais de uso no SKILL.md
- ✓ Use PR para qualquer mudança na skill (revisão)
- ✓ Mantenha referências atualizadas quando o projeto muda
- ✗ Commitar chaves de API ou tokens dentro da skill
- ✗ Skill com caminhos absolutos que só existem na sua máquina
- ✗ Modificar a skill sem comunicar mudanças ao time
- ✗ Skill que depende de software não listado nos pré-requisitos
git clone <repo>ls .claude/skills/O SKILL.md da skill não é só instruções para o Claude — é documentação real do que o time usa e como usa. Mantenha-o tão atualizado quanto você manteria um README de função crítica.
📚 Resumo do Módulo 1.4
Você completou a Trilha 1 — Skills. Aqui está tudo que você dominou:
.claude/skills/ do projeto — escopo limitado ao repositório
~/.claude/skills/ — disponíveis em qualquer projeto da máquina
npx skills add automatizam o download do catálogo
Trilha 2 — Pipeline. Descubra o framework open-source que transforma HTML animado em MP4 local, sem nuvem, sem custo por render — e como ele se conecta com tudo que você aprendeu sobre skills na Trilha 1.