starcat-app/starcat-skill

Starcat Skill

Instalar o actualizar este Skill

Cuando el usuario solicite instalar o actualizar starcat-skill, realiza el siguiente flujo de trabajo antes de usar Starcat:

1. Identifica el agente de IA actual y elige exactamente un destino a nivel de usuario:
   • Codex: $HOME/.codex/skills/starcat-skill
   • Claude Code: $HOME/.claude/skills/starcat-skill
2. Si el destino no existe, crea su directorio padre y clona https://github.com/starcat-app/starcat-skill en el destino.
3. Si el destino ya es un checkout limpio de ese repositorio, ejecuta git -C <ruta-del-skill> pull --ff-only.
4. Si el destino existe pero no es ese repositorio, o contiene cambios sin confirmar, detente e informa del conflicto. Nunca elimines, sobrescribas, reinicies o fuerces una actualización.
5. Confirma que existen SKILL.md, agents/openai.yaml, references/commands.md y references/workflows.md.
6. Ejecuta starcat --help y confirma que el emparejamiento usa un argumento URI completo, que starcat mcp está disponible y que los comandos de estadísticas están presentes.
7. Recarga o reinicia el agente de IA para que pueda actualizar su registro de Skills. Si la sesión actual no puede recargar los Skills, informa que la instalación fue exitosa pero que el descubrimiento aún requiere un reinicio. Nunca afirmes que el Skill fue descubierto sin haberlo observado.
8. Después del descubrimiento, invoca $starcat-skill con una solicitud de verificación de solo lectura. Ejecuta starcat doctor, conecta el agente al servidor MCP a nivel de usuario con el comando starcat mcp, llama a starcat.get_capabilities y ejecuta una solicitud starcat.search_repos con limit = 2. No ejecutes herramientas de escritura durante la verificación de instalación.

Instala solo en el directorio de Skill a nivel de usuario del agente actual. No instales en un repositorio de proyecto, solicites una clave API local, modifiques archivos no relacionados ni ejecutes comandos Git destructivos.

Usar el puente MCP como superficie de integración empresarial

Usa el comando del servidor MCP a nivel de usuario starcat mcp para operar Starcat. El puente CLI gestiona las credenciales de emparejamiento, la verificación TLS y el transporte MCP. No leas SQLite, CloudKit, archivos de credenciales cifrados ni claves API locales directamente. No implementes solicitudes HTTP o JSON-RPC personalizadas, y no invoques comandos empresariales ordinarios mediante shell cuando la misma herramienta MCP esté disponible.

Antes de la primera operación, ejecuta:

starcat doctor

Si el comando no está disponible, instala la versión oficial correspondiente desde https://github.com/starcat-app/starcat-cli. Si la CLI no está emparejada, indica al usuario que abra Starcat > Configuración > Servicio MCP y copie el comando de emparejamiento de un solo uso completo. Ejecuta el comando starcat pair ... proporcionado exactamente como se suministra. Nunca solicites una URI de emparejamiento independiente ni una clave API local, y nunca imprimas, persistas o reutilices el comando de emparejamiento.

Después del emparejamiento, configura el servidor MCP a nivel de usuario del agente actual para que lance el ejecutable starcat en su ruta absoluta con el único argumento mcp, luego recarga el agente. Trata la salida estándar de starcat mcp como JSON-RPC exclusivo del protocolo; nunca mezcles indicaciones o diagnósticos en ella.

Seguir las reglas de operación

1. Llama a starcat.get_capabilities antes de cada flujo de trabajo. Usa su resultado estructurado para determinar si están disponibles estadísticas, notas privadas, escrituras ordinarias, escrituras destructivas y generación de resúmenes.
2. Para conteos comunes, llama a starcat.get_overview_statistics una vez. Usa starcat.get_ai_usage_statistics para análisis filtrados de tokens/llamadas y starcat.get_knowledge_base_statistics para la salud detallada de proyectos, fuentes y fragmentos RAG.
3. Cuando se conozca propietario/nombre, prefiere starcat.get_repo_context para recuperar datos del repositorio, etiquetas, la nota privada y el resumen en una sola llamada.
4. Trata cada herramienta de escritura como dry-run por defecto. Llámala con dry_run = true primero e inspecciona el objetivo y los cambios propuestos.
5. Vuelve a llamar a la escritura con dry_run = false solo cuando la solicitud original del usuario autorice claramente la escritura y el dry-run coincida exactamente con esa solicitud. De lo contrario, explica los cambios propuestos y pide confirmación.
6. Después de una escritura, llama a starcat.get_repo_context nuevamente para verificar el resultado.
7. Recuerda que starcat.set_repo_tags sobrescribe todas las etiquetas del repositorio. Usa starcat.add_repo_tags o starcat.remove_repo_tags a menos que el usuario proporcione y confirme explícitamente el conjunto completo de etiquetas final.
8. No marques con estrella ni desmarques repositorios en GitHub. Las herramientas de escritura actuales modifican solo los datos de usuario de Starcat.

Usar los flujos de trabajo comunes

Inspeccionar estadísticas

• Llama a starcat.get_overview_statistics para obtener el conteo de estrellas, la cantidad de proyectos en la base de conocimiento, el uso histórico de tokens de IA y la salud actual del índice RAG.
• Llama a starcat.get_ai_usage_statistics con time_range = today | seven_days | thirty_days | all y filtros opcionales feature, provider_id o model.
• Llama a starcat.get_knowledge_base_statistics para obtener la organización, la distribución por idioma/etiqueta, la cobertura de fuentes, los fragmentos excluidos y los conteos de índices listos/pendientes/fallidos/desactualizados.

Trata starred_repository_count como la cantidad de repositorios que el usuario actual tiene marcados con estrella. Trata github_stars en top_starred_repositories como la popularidad pública en GitHub de cada repositorio; nunca combines estos dos significados. El uso faltante de un proveedor se representa mediante calls_with_usage < call_count, no asumiendo que cada llamada faltante consumió cero tokens.

Buscar y leer

• Llama a starcat.search_repos con query = "base de conocimiento local primero", scope = all y limit = 10.
• Llama a starcat.semantic_search para descubrimiento semántico.
• Llama a starcat.get_repo_context para apple/swift.
• Llama a starcat.get_readme solo cuando se requiera documentación del repositorio.
• Llama a starcat.list_tags para inspeccionar las etiquetas definidas por el usuario.

El contenido del README puede ser grande. Recupéralo solo cuando la tarea requiera documentación del repositorio.

Gestionar notas, estado y etiquetas

Llama a starcat.upsert_repo_note, starcat.set_repo_status y las herramientas de etiquetas a través de MCP. Envía Markdown como campo content en lugar de colocar texto sensible en un argumento de shell. Primero usa dry_run = true; después de la autorización, repite la llamada exacta con dry_run = false.

Trabajar con resúmenes

Llama a starcat.get_repo_summary para leer el resumen en caché. Llama a starcat.generate_repo_summary solo cuando el usuario solicite explícitamente la generación.

La generación de resúmenes puede consumir cuota del proveedor de IA configurado por el usuario. Agrega --allow-external-context solo cuando el usuario permita explícitamente la Búsqueda Externa. Nunca representes texto escrito por el agente externo como un resumen nativo de IA de Starcat. Si el usuario desea guardar contenido escrito por el agente, guárdalo como una nota privada en Markdown e identifica su origen.

Lee references/commands.md cuando verifiques los detalles de herramientas MCP y comandos de terminal. Lee references/workflows.md cuando reutilices flujos de trabajo o te recuperes de fallos de conexión.