starcat-app/starcat-skill

Starcat Skill

Instalar ou atualizar este Skill

Quando o usuário solicitar instalar ou atualizar starcat-skill, execute o fluxo a seguir antes de usar o Starcat:

1. Identifique o agente de IA atual e escolha exatamente um destino a nível de usuário:
   • Codex: $HOME/.codex/skills/starcat-skill
   • Claude Code: $HOME/.claude/skills/starcat-skill
2. Se o destino não existir, crie seu diretório pai e clone https://github.com/starcat-app/starcat-skill no destino.
3. Se o destino já for um checkout limpo desse repositório, execute git -C <caminho-do-skill> pull --ff-only.
4. Se o destino existir mas não for esse repositório, ou contiver alterações não commitadas, pare e reporte o conflito. Nunca delete, sobrescreva, faça reset ou force update.
5. Confirme que SKILL.md, agents/openai.yaml, references/commands.md e references/workflows.md existem.
6. Execute starcat --help e confirme que o emparelhamento usa um argumento URI completo, starcat mcp está disponível e os comandos de estatísticas estão presentes.
7. Recarregue ou reinicie o agente de IA para que ele possa atualizar seu registro de Skills. Se a sessão atual não puder recarregar Skills, reporte que a instalação foi bem-sucedida, mas a descoberta ainda requer uma reinicialização. Nunca afirme que o Skill foi descoberto sem observá-lo.
8. Após a descoberta, invoque $starcat-skill com uma solicitação de verificação somente leitura. Execute starcat doctor, conecte o agente ao servidor MCP a nível de usuário com o comando starcat mcp, chame starcat.get_capabilities e execute uma requisição starcat.search_repos com limit = 2. Não execute ferramentas de escrita durante a verificação da instalação.

Instale apenas no diretório de Skills a nível de usuário do agente atual. Não instale em um repositório de projeto, solicite uma Chave de API Local, modifique arquivos não relacionados ou execute comandos Git destrutivos.

Usar a ponte MCP como superfície de integração de negócios

Use o comando do servidor MCP a nível de usuário starcat mcp para operar o Starcat. A ponte CLI gerencia credenciais de emparelhamento, verificação TLS e transporte MCP. Não leia SQLite, CloudKit, arquivos de credenciais criptografadas ou Chaves de API Local diretamente. Não implemente requisições HTTP ou JSON-RPC personalizadas, e não invoque comandos de negócios comuns via shell quando a mesma ferramenta MCP estiver disponível.

Antes da primeira operação, execute:

starcat doctor

Se o comando não estiver disponível, instale o release oficial apropriado de https://github.com/starcat-app/starcat-cli. Se a CLI não estiver emparelhada, instrua o usuário a abrir Starcat > Configurações > Serviço MCP e copiar o comando de emparelhamento completo de uso único. Execute o comando starcat pair ... fornecido exatamente como foi passado. Nunca solicite um URI de emparelhamento independente ou Chave de API Local, e nunca imprima, persista ou reutilize o comando de emparelhamento.

Após o emparelhamento, configure o servidor MCP a nível de usuário do agente atual para iniciar o executável starcat absoluto com o único argumento mcp, então recarregue o agente. Trate a saída padrão de starcat mcp como JSON-RPC exclusivamente de protocolo; nunca misture prompts ou diagnósticos nela.

Seguir as regras operacionais

1. Chame starcat.get_capabilities antes de cada fluxo de trabalho. Use seu resultado estruturado para determinar se estatísticas, notas privadas, escritas comuns, escritas destrutivas e geração de resumos estão disponíveis.
2. Para contagens comuns, chame starcat.get_overview_statistics uma vez. Use starcat.get_ai_usage_statistics para análise filtrada de tokens/chamadas e starcat.get_knowledge_base_statistics para saúde detalhada de projetos, fontes e chunks RAG.
3. Quando owner/name for conhecido, prefira starcat.get_repo_context para recuperar dados do repositório, tags, nota privada e resumo em uma única chamada.
4. Trate toda ferramenta de escrita como dry-run por padrão. Chame-a com dry_run = true primeiro e inspecione o alvo e as alterações propostas.
5. Chame a escrita novamente com dry_run = false apenas quando a solicitação original do usuário autorizar claramente a escrita e o dry-run corresponder exatamente a essa solicitação. Caso contrário, explique as alterações propostas e peça confirmação.
6. Após uma escrita, chame starcat.get_repo_context novamente para verificar o resultado.
7. Lembre-se de que starcat.set_repo_tags sobrescreve todas as tags do repositório. Use starcat.add_repo_tags ou starcat.remove_repo_tags, a menos que o usuário forneça e confirme explicitamente o conjunto final completo de tags.
8. Não marque ou desmarque repositórios com estrela no GitHub. As ferramentas de escrita atuais modificam apenas dados do usuário no Starcat.

Usar os fluxos de trabalho comuns

Inspecionar estatísticas

• Chame starcat.get_overview_statistics para contagem de Estrelas, contagem de projetos na base de conhecimento, uso total de tokens de IA e saúde atual do índice RAG.
• Chame starcat.get_ai_usage_statistics com time_range = today | seven_days | thirty_days | all e filtros opcionais feature, provider_id ou model.
• Chame starcat.get_knowledge_base_statistics para organização, distribuição de linguagem/tag, cobertura de fontes, chunks excluídos e contagens de índices prontos/pendentes/falhos/desatualizados.

Trate starred_repository_count como o número de repositórios que o usuário atualmente tem como estrela. Trate github_stars em top_starred_repositories como a popularidade pública no GitHub de cada repositório; nunca combine esses dois significados. A ausência de uso de provedor é representada por calls_with_usage < call_count, não assumindo que toda chamada ausente consumiu zero tokens.

Pesquisar e ler

• Chame starcat.search_repos com query = "local first knowledge base", scope = all e limit = 10.
• Chame starcat.semantic_search para descoberta semântica.
• Chame starcat.get_repo_context para apple/swift.
• Chame starcat.get_readme apenas quando a documentação do repositório for necessária.
• Chame starcat.list_tags para inspecionar tags definidas pelo usuário.

O conteúdo do README pode ser grande. Recupere-o apenas quando a tarefa exigir documentação do repositório.

Gerenciar notas, status e tags

Chame starcat.upsert_repo_note, starcat.set_repo_status e ferramentas de tag via MCP. Envie Markdown como o campo content em vez de colocar texto sensível em um argumento de shell. Primeiro use dry_run = true; após autorização, repita a chamada exata com dry_run = false.

Trabalhar com resumos

Chame starcat.get_repo_summary para ler o resumo em cache. Chame starcat.generate_repo_summary apenas quando o usuário solicitar explicitamente a geração.

A geração de resumo pode consumir cota do provedor de IA configurado pelo usuário. Adicione --allow-external-context apenas quando o usuário permitir explicitamente a Busca Externa. Nunca represente texto escrito pelo agente externo como um resumo de IA nativo do Starcat. Se o usuário quiser salvar conteúdo escrito pelo agente, armazene-o como uma nota privada em Markdown e identifique sua fonte.

Leia references/commands.md ao verificar detalhes de ferramentas MCP e comandos de terminal. Leia references/workflows.md ao reutilizar fluxos de trabalho ou se recuperar de falhas de conexão.