pilot-shell (Claude Skill) — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Pipeline plan → spec → implement → verify como loop padrão
Quality gates: lint, type, test, presença de doc, todos obrigatórios
Arquivo de conhecimento do projeto mantido automaticamente
Critérios de aceitação primeiro; testes escritos antes do código
Integra ao fluxo do Claude Code sem forçar uma nova ferramenta

Demo ao vivo

Como fica na prática

pronto

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "pilot-shell-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "pilot-shell-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/maxritter/pilot-shell",
          "~/.claude/skills/pilot-shell"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add pilot-shell-skill -- git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: pilot-shell

Publicar uma feature com disciplina spec-first

👤 Devs cansados de features escritas por IA pela metade ⏱ ~90 min intermediate

Quando usar: Requisito vago do PM; você quer que seja publicado certo, não rápido.

Pré-requisitos

Skill instalada — git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

Fluxo

Planejar

Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ Copiado

→ Plano com desconhecidos explícitos; você preenche as lacunas antes do próximo passo
Especificar

From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ Copiado

→ Spec salva em /specs/<feature>.md
Implementar

Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ Copiado

→ Testes + implementação; testes com falha visíveis até que a implementação passe
Verificar os gates

Run all gates: lint, type, tests, docs. Block PR if any red.✓ Copiado

→ Relatório de gates; apenas verde = candidato a merge

Resultado: Features publicadas com spec completa, testes e documentação.

Armadilhas

Spec se arrasta numa maratona de planejamento — Limite a fase de spec a 30 min; publique a menor spec que trava os critérios de aceitação

Combine com: filesystem

Parar de abrir PRs que falham no CI na primeira execução

👤 Devs cujos PRs frequentemente falham em erros básicos de lint/type ⏱ ~30 min intermediate

Quando usar: Você abriu 3 PRs esta semana; todos falharam no CI no básico.

Fluxo

Configurar os gates

Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ Copiado

→ .pilot.config.json com os gates listados
Bloquear no vermelho

Set policy: don't open PR until all gates green locally.✓ Copiado

→ Política aplicada
Medir

After 2 weeks, compare CI first-run pass rate before/after.✓ Copiado

→ Taxa de aprovação aumentou

Resultado: PRs que passam no CI na primeira tentativa; menos retrabalho para revisores.

Armadilhas

Gates locais diferem sutilmente do CI (versão do Node) — Fixe a versão local do Node com .nvmrc; espelhe os comandos exatos do CI

Combine com: github

Preservar o conhecimento do projeto à medida que o time cresce

👤 Donos de projetos integrando novos colaboradores ⏱ ~30 min beginner

Quando usar: Você está passando o projeto ou compartilhando; quer decisões e invariantes capturados.

Fluxo

Semear o arquivo de conhecimento

Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ Copiado

→ /.pilot/knowledge.md criado com seções
Capturar enquanto avança

Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ Copiado

→ Decisões se acumulam; novos colaboradores podem ler o histórico
Usar no onboarding

When a new collaborator starts, point Claude Code to this file as primary context.✓ Copiado

→ Integração mais rápida; menos «por que é assim?»

Resultado: Conhecimento sobrevive a mudanças no time.

Armadilhas

Arquivo de conhecimento vira um diário de trivialidades — Mantenha conciso: invariantes, decisões, armadilhas. Não um log diário

Combinações

Combine com outros MCPs para 10× de alavancagem

pilot-shell-skill + github

Template de PR preenchido automaticamente a partir da spec; CI valida os gates

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ Copiado

pilot-shell-skill + filesystem

Specs e conhecimento commitados no repositório

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar
plan	feature_description	Passo 1 de qualquer nova feature
spec	plan_id	Após os desconhecidos do plano estarem resolvidos
implement	spec_id	Após a spec aprovada
run_gates	scope?	Pré-PR; espelho do CI
knowledge_update	decision_or_invariant	Capturar decisão no nível do projeto

Custo e limites

O que custa rodar

Cota de API: Nenhuma — local
Tokens por chamada: Docs de spec ~500–2000 tokens; arquivo de conhecimento limitado a ~3000 para ser gerenciável
Monetário: Gratuito
Dica: Limite knowledge.md a ~3000 tokens; consolide entradas mais antigas periodicamente

Segurança

Permissões, segredos, alcance

Escopos mínimos: filesystem-write

Armazenamento de credenciais: Nenhuma

Saída de dados: Nenhuma

Specs podem descrever detalhes sensíveis do produto — adicione /specs/ ao .gitignore se for privado

Solução de problemas

Erros comuns e correções

Gates passam localmente mas falham no CI

Fixe versão do Node, dependências específicas de SO; espelhe o comando exato do CI

Verificar: Compare a saída do comando local vs CI

Passo de implementação pula test-first

Defina strict_tdd=true no .pilot.config; a tool recusará escrever implementação antes dos testes

Fase de spec se arrasta

Use --time-box 30m; force decisões sobre desconhecidos em vez de specs perfeitas

Arquivo de conhecimento muito longo

Execute knowledge_consolidate; arquiva entradas antigas em /.pilot/archive/

Alternativas

pilot-shell vs. outros

Alternativa	Quando usar	Troca
spec-workflow-mcp	Você quer isso como servidor MCP com alcance cross-tool (não uma skill do Claude Code)	Mais configuração; deploy mais flexível
CLAUDE.md puro + TDD manual	Projeto solo, você não precisa de automação	Depende de disciplina; menos guardrails

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills