MODULO 2.3

⚙️ Instalacao e configuracao

30 segundos do zero ao primeiro /grill-me. Setup do mattpocock/skills sem mistério: pré-requisitos, instalador, escolha de agentes, configuração de issue tracker e validação.

9
Secoes
30s
Minimo
Basico
Nivel
Pratica
Tipo
1

📋 Pre-requisitos

Antes de rodar qualquer comando, garanta que sua máquina tem o ambiente certo. As skills do Matt Pocock rodam em cima de runtimes que assumem coisas específicas — pular esta etapa é o motivo #1 de instalação falhando com mensagem críptica.

🎯 O essencial em 3 itens

  • • Claude Code (claude.com/claude-code) ou Codex CLI instalado e logado.
  • • Node.js 18+ no PATH — usado pelo npx que baixa o instalador.
  • • Um repositório de trabalho aberto (ou pasta nova) — o instalador escreve em .claude/ e docs/agents/.

✓ Configuracoes suportadas

  • ✓Claude Code (desktop ou terminal) — modo plugin
  • ✓Codex CLI — modo arquivo (skills/ no repo)
  • ✓macOS, Linux, WSL2 (Windows nativo via WSL)
  • ✓Node 18 LTS, 20 LTS, 22 LTS
  • ✓Repos com Git (recomendado) ou pastas avulsas
  • ✓Issue trackers: GitHub, Linear, local (.scratch/)

✗ Nao suportado (ainda)

  • ✗Windows nativo sem WSL — caminhos quebram
  • ✗Node 16 ou anterior — npx incompatível
  • ✗Jira, GitLab Issues, Notion (planejado, não pronto)
  • ✗Editores como Cursor/Continue (skill é Claude/Codex)
  • ✗Sem permissão de escrita no projeto (read-only mounts)
  • ✗Empresas que bloqueiam npm registry (sem proxy)

💡 Verificacao rapida (10 segundos)

# Cole no terminal antes de continuar: node --version # precisa retornar v18+ claude --version # ou: codex --version git status # precisa estar dentro de um repo

Se qualquer um falhar, resolve antes de rodar o instalador. A maioria dos bugs reportados é pré-requisito faltando.

2

📦 Instalacao via skills.sh (recomendado)

O skills.sh é o caminho oficial. Um comando, sem clonar repo, sem editar JSON na mão. Ele detecta runtime (Claude Code ou Codex), copia os arquivos certos no lugar certo e abre uma tela de seleção.

# Na raiz do projeto onde você quer usar as skills: npx skills@latest add mattpocock/skills

🔧 O que o instalador faz por baixo

  • 1.Baixa o pacote skills via npx (não instala globalmente).
  • 2.Detecta se você está em Claude Code (procura .claude/) ou Codex (procura .codex/).
  • 3.Faz git clone --depth 1 de mattpocock/skills num cache temporário.
  • 4.Lista skills disponíveis (engineering/, productivity/, misc/) com checkboxes.
  • 5.Copia as escolhidas para .claude/skills/ (ou equivalente Codex).
  • 6.Registra as skills no plugin.json ou na configuração local.

Não toca em nada fora desses dois diretórios. Reversível: deletar a pasta de skills volta ao estado original.

3

🎛️ Selecionando skills no installer

Após rodar o comando, o instalador entra em modo interativo. 4 passos visuais até confirmar — não dá pra errar se você acompanhar a tela. O mais importante: marcar /setup-matt-pocock-skills nessa etapa, porque é ele que vai configurar tudo depois.

1

Rodar o comando

Terminal aberto na raiz do repo

Você digita npx skills@latest add mattpocock/skills. O npx baixa o instalador (~300KB) e roda em ~5 segundos na primeira vez.

Saida esperada: "Fetching mattpocock/skills..." seguido de "Detected runtime: claude-code".

2

Tela de selecao aparece

Lista interativa com checkboxes

Você vê todas as skills agrupadas por bucket: engineering/ (handoff, ica, grill-me…), productivity/ (setup-matt-pocock-skills, triage-issues…), misc/. Setas para navegar, espaço para marcar.

Skills personal/, in-progress/ e deprecated/ não aparecem — protege o usuário de drafts.

3

Escolher agentes — marcar /setup-matt-pocock-skills

Etapa critica — nao pular

Marque /setup-matt-pocock-skills obrigatoriamente. Esse agente roda uma vez depois da instalação e gera os arquivos de configuração (labels, paths de docs, integração com issue tracker). Sem ele, as outras skills ficam funcionais mas desconectadas do seu fluxo.

Recomendação minima: /setup-matt-pocock-skills, /grill-me, /handoff. Depois você adiciona o resto.

4

Confirmar e ver o diff

Tudo escrito de uma vez, atomic

Você aperta Enter. O instalador mostra um resumo: "5 skills installed → .claude/skills/". Se você usar Git, faça git status para ver tudo que foi adicionado. Recomendado commitar logo como "chore: install matt-pocock skills".

Se algo der errado no meio, o instalador não deixa estado parcial: ou tudo entra, ou nada entra.

4

🪄 Rodando /setup-matt-pocock-skills

Com as skills instaladas, abra o Claude Code (ou Codex) dentro do mesmo projeto e dispare o agente de setup. Ele faz uma entrevista curta (3-4 perguntas) e gera os arquivos de configuração no formato certo pro seu fluxo.

# No prompt do Claude Code: /setup-matt-pocock-skills Agent: Vou configurar suas skills. Tres perguntas rapidas. Agent: 1) Qual issue tracker voce usa? a) GitHub Issues b) Linear c) Local (.scratch/ no repo) You: a Agent: 2) Repo: "meu-org/meu-app"? (detectei do git remote) You: sim Agent: 3) Quais labels o time usa pra triage? (digite separadas por virgula, ou enter pra padrao) You: bug, enhancement, question, docs Agent: 4) Onde devo salvar docs de agentes? Padrao: docs/agents/ — confirma? (y/n) You: y Agent: Configurando... - Criando docs/agents/triage-labels.md - Criando docs/agents/issue-tracker.md - Atualizando .claude/skills/triage-issues/config.json Agent: Pronto. Teste com /grill-me ou /triage-issues.

💡 Recomendacoes por tamanho de time

  • Solo / side project: issue tracker local (.scratch/). Sem fricção, sem dependência externa.
  • Time pequeno (2-5 devs): GitHub Issues. É onde o código já vive, todo mundo tem acesso.
  • Time médio/grande (6+): Linear se a empresa já paga. Caso contrário, GitHub Projects.
  • Empresa regulada/fechada: local + sync manual. Evita expor decisões internas em SaaS público.
5

🗂️ Configurando issue tracker

A escolha do issue tracker molda o resto do fluxo. Skills como /triage-issues e /handoff precisam saber onde criar/ler tickets. Os três modos cobrem 95% dos casos.

✓ Quando usar cada um

  • GitHub Issues — repo público/privado, time inteiro tem acesso, integra com PRs.
  • Linear — organização paga Linear, quer ciclos/projetos estruturados.
  • Local (.scratch/) — solo, offline, exploratório. Sem custo, sem auth.

✗ Quando NAO usar

  • GitHub — se o repo é fechado mas o tracker precisa ser cross-repo.
  • Linear — se você está sozinho ou ainda validando ideia (overkill).
  • Local — em times de 3+ pessoas (cada um terá um .scratch/ diferente, sem sync).

A configuração gerada vive em docs/agents/issue-tracker.md. Exemplo gerado pelo setup quando você escolhe GitHub:

# docs/agents/issue-tracker.md tracker: github repo: meu-org/meu-app default_assignee: "@me" auth: gh-cli # usa `gh auth status` p/ verificar queries: open_bugs: "is:open label:bug" needs_triage: "is:open no:label" my_work: "is:open assignee:@me" create_template: body_prefix: "<!-- generated by mattpocock/skills -->" add_labels_on_create: ["triage"]
6

🏷️ Labels de triage

As labels são o vocabulário que une humanos e agentes. Se você diz "isso é um bug" e o agente diz "isso é defeito", vocês duplicam tickets. O setup gera um mapeamento papel → label string para padronizar.

Cada papel semântico (o que o ticket representa no fluxo) vira uma string canônica. Você muda as strings pra refletir o vocabulário do seu time, mas mantém os papéis:

# docs/agents/triage-labels.md labels: # --- papel: tipo de problema --- bug: "bug" # defeito em comportamento existente feature: "enhancement" # pedido de novo comportamento docs: "docs" # melhoria de documentacao question: "question" # duvida, nao acionavel ainda # --- papel: estado no fluxo --- needs_triage: "triage" # entrou e ainda nao foi avaliado blocked: "blocked" # esperando algo externo ready: "ready" # priorizado e pode ser pego # --- papel: prioridade --- p0: "priority:p0" # incidente, parar tudo p1: "priority:p1" # prioritario na sprint p2: "priority:p2" # quando der color_hints: bug: "#d73a4a" enhancement: "#a2eeef" docs: "#0075ca"

📊 Por que mapear papel -> string?

Porque o nome interno (bug) é estável no código do agente, mas a string visível ao usuário ("defeito", "erro", "bug") varia entre times.

Renomeou a label no GitHub? Edita uma linha aqui. O agente continua funcionando. Sem essa indireção, você quebra todos os prompts toda vez que o time muda o vocabulário.

7

🔧 Instalacao manual (sem skills.sh)

Se sua empresa bloqueia npm registry, ou você quer controle total do que entra no repo, dá pra fazer tudo na mão. É mais trabalho, mas funciona em qualquer ambiente.

# 1) Clonar o repo de skills em local separado git clone https://github.com/mattpocock/skills.git ~/src/mp-skills # 2) Criar diretorio de skills no seu projeto (se nao existir) mkdir -p .claude/skills # 3) Link simbolico (recomendado — recebe updates do git pull) ln -s ~/src/mp-skills/skills/engineering/grill-me .claude/skills/grill-me ln -s ~/src/mp-skills/skills/engineering/handoff .claude/skills/handoff ln -s ~/src/mp-skills/skills/productivity/setup-matt-pocock-skills .claude/skills/setup # 4) OU copia (snapshot, nao recebe updates) cp -r ~/src/mp-skills/skills/engineering/grill-me .claude/skills/ # 5) Registrar no plugin.json (se for o caso do seu setup) cat .claude/plugin.json # adiciona as skills no array "skills": [...] # 6) Reiniciar Claude Code para carregar claude restart

🧭 Symlink vs copia

  • Symlink: um git pull no clone atualiza tudo. Bom pra você que quer sempre o latest.
  • Copia: congela versão. Bom pra time que precisa de skill estável e revisão por PR.

Depois desse setup manual, você ainda precisa rodar /setup-matt-pocock-skills dentro do Claude Code para gerar os arquivos de configuração. A instalação manual só coloca os arquivos no lugar — a configuração é separada.

8

✅ Verificando que tudo funciona

Instalou, configurou — agora prova que está vivo. /grill-me é o teste mais rápido: ele força o agente a fazer perguntas sobre o problema atual em vez de responder direto. Se essa skill carregou, todas carregaram.

# No Claude Code, dentro do projeto: /grill-me quero adicionar autenticacao no app Agent: Antes de propor codigo, deixa eu entender: 1. Qual provider voce ja decidiu? (Auth0, Clerk, custom, NextAuth...) 2. Web, mobile, ou ambos? 3. Voce ja tem usuarios em prod? (define migracao vs greenfield) 4. Email/senha, social, magic link, ou combinacao? 5. Qual o requisito de sessao? (JWT, cookie, refresh tokens?) # Se aparecer isso, esta funcionando. Se o agente # responder direto com codigo, a skill nao carregou.

📋 Checklist de validacao

  • ✓/grill-me <qualquer coisa> dispara perguntas em vez de resposta direta
  • ✓/handoff gera markdown estruturado em vez de prosa solta
  • ✓Arquivos docs/agents/issue-tracker.md e triage-labels.md existem
  • ✓.claude/skills/ tem as pastas das skills selecionadas
  • ✓git status mostra os arquivos novos — pronto pra commit
  • ✓Reiniciou o Claude Code uma vez para garantir que os arquivos foram lidos
9

🩺 Troubleshooting

Quase tudo que dá errado cai em três buckets. Identifica o sintoma, aplica a correção, segue a vida.

✗ Sintomas comuns

  • Skill não aparece ao digitar / — autocomplete vazio ou só built-ins.
  • Conflito com outra skill — duas skills com mesmo nome ou trigger, mensagem "ambiguous command".
  • Plugin não carrega — Claude Code abre mas nenhuma skill custom funciona, erro no log de startup.
  • Agent responde direto sem rodar a skill — você digita /grill-me e ele só responde como chat normal.

✓ Solucoes

  • Reiniciar — 70% dos casos. Claude Code só lê .claude/ no startup.
  • Renomear a skill conflitante ou desabilitar a duplicada no plugin.json.
  • Validar JSON — cat .claude/plugin.json | jq. Trailing comma quebra tudo.
  • Forçar prefixo de skill no prompt: /grill-me tem que ser a primeira palavra da mensagem.

🛠️ Receita: skill nao aparece

  1. Confere se o diretório existe: ls .claude/skills/grill-me.
  2. Confere se tem SKILL.md dentro com frontmatter válido (nome, descrição).
  3. Reinicia: feche o Claude Code completamente (não só a janela) e reabra.
  4. Se ainda não aparece, confere logs em ~/.claude/logs/ — procura por "skill load error".
  5. Última opção: deleta a pasta da skill, roda npx skills@latest add de novo.

⚠️ Atencao com permissoes

Se você rodou npx com sudo alguma vez, os arquivos podem ter ficado como root e o Claude Code (rodando como seu user) não consegue ler. Conserta com: sudo chown -R $USER .claude/. Nunca rode o instalador com sudo de novo.

🎓 Resumo do Modulo

✓
Pre-requisitos — Claude Code (ou Codex) + Node 18+ + repo com permissão de escrita. Sem isso, nada roda.
✓
Instalacao via skills.sh — npx skills@latest add mattpocock/skills. Um comando, copia arquivos, registra plugin, reversível.
✓
4 passos no installer — rodar → tela → marcar /setup-matt-pocock-skills → confirmar.
✓
Setup entrevista voce — issue tracker, labels, paths de docs. Gera arquivos versionáveis em docs/agents/.
✓
Labels = papel -> string — indireção que protege seus prompts quando o vocabulário do time muda.
✓
Verificou com /grill-me — se ele faz perguntas em vez de responder direto, está tudo vivo.
✓
Troubleshooting — 70% dos problemas se resolvem reiniciando o Claude Code. JSON inválido e permissões cobrem o resto.

Proxima Trilha:

Trilha 3 — Pratica: rodando skills reais em projetos de verdade, /handoff entre sessoes, /grill-me em arquitetura, fluxos avançados de triage.

← Modulo 2.2 Ir para Trilha 3 →