starcat-app/starcat-skill

Starcat Skill

安装或更新此 Skill

当用户要求安装或更新 starcat-skill 时，在使用 Starcat 之前执行以下工作流：

1. 识别当前 AI 智能体，并选择一个用户级别的目标目录：
   • Codex: $HOME/.codex/skills/starcat-skill
   • Claude Code: $HOME/.claude/skills/starcat-skill
2. 如果目标目录不存在，则创建其父目录并将 https://github.com/starcat-app/starcat-skill 克隆到该目标目录中。
3. 如果目标目录已经是该仓库的干净检出，则运行 git -C <skill-path> pull --ff-only。
4. 如果目标目录已存在但不是该仓库，或包含未提交的更改，则停止并报告冲突。切勿删除、覆盖、重置或强制更新它。
5. 确认 SKILL.md、agents/openai.yaml、references/commands.md 和 references/workflows.md 文件存在。
6. 运行 starcat --help 并确认配对使用完整的 URI 参数，starcat mcp 可用，且统计命令已存在。
7. 重新加载或重启 AI 智能体，以便它可以刷新其技能注册表。如果当前会话无法重新加载技能，则报告安装成功但发现仍需重启。切勿在未观察到的情况下声称技能已被发现。
8. 在发现之后，使用只读验证请求调用 $starcat-skill。运行 starcat doctor，将智能体连接到用户级别的 MCP 服务器命令 starcat mcp，调用 starcat.get_capabilities，并运行一次 starcat.search_repos 请求（limit = 2）。安装验证期间不要执行任何写工具。

仅安装到当前智能体的用户级别技能目录中。不要安装到项目仓库中，不要请求本地 API Key，不要修改无关文件，也不要运行破坏性的 Git 命令。

使用 MCP 桥作为业务集成界面

使用用户级别的 MCP 服务器命令 starcat mcp 来操作 Starcat。CLI 桥负责管理配对凭据、TLS 验证和 MCP 传输。不要直接读取 SQLite、CloudKit、加密凭据文件或本地 API Key。不要实现自定义的 HTTP 或 JSON-RPC 请求，如果存在相同的 MCP 工具，不要通过 shell 执行普通的业务命令。

在首次操作之前，运行：

starcat doctor

如果该命令不可用，请从 https://github.com/starcat-app/starcat-cli 安装相应的官方发行版。如果 CLI 未配对，请指示用户打开 Starcat > 设置 > MCP 服务 并复制完整的单次配对命令。完全按照用户提供的命令执行 starcat pair ...。切勿请求独立的配对 URI 或本地 API Key，并且切勿打印、持久化或重用该配对命令。

配对后，配置当前智能体的用户级别 MCP 服务器，使其启动绝对路径的 starcat 可执行文件，并附带参数 mcp，然后重新加载智能体。将 starcat mcp 的标准输出视为纯协议的 JSON-RPC；切勿将提示或诊断信息混入其中。

遵循操作规则

1. 在每个工作流之前调用 starcat.get_capabilities。使用其结构化结果来确定统计信息、私人笔记、普通写入、破坏性写入和摘要生成是否可用。
2. 对于常见计数，调用 starcat.get_overview_statistics 一次。使用 starcat.get_ai_usage_statistics 进行过滤后的令牌/调用分析，使用 starcat.get_knowledge_base_statistics 获取详细的项目、来源和 RAG 块健康状态。
3. 当已知 owner/name 时，优先使用 starcat.get_repo_context 在一次调用中检索仓库数据、标签、私人笔记和摘要。
4. 默认将每个写工具视为试运行。首先使用 dry_run = true 调用它，并检查目标和提议的更改。
5. 仅当用户的原始请求明确授权写入，并且试运行结果与该请求完全匹配时，才使用 dry_run = false 再次调用写工具。否则，解释提议的更改并要求确认。
6. 写入后，再次调用 starcat.get_repo_context 以验证结果。
7. 请记住，starcat.set_repo_tags 会覆盖仓库上的所有标签。除非用户明确提供并确认完整的最终标签集，否则请使用 starcat.add_repo_tags 或 starcat.remove_repo_tags。
8. 不要在 GitHub 上对仓库加星或取消星标。当前的写工具仅修改 Starcat 用户数据。

使用通用工作流

检查统计信息

• 调用 starcat.get_overview_statistics 获取星标数、知识库项目数、所有时间的 AI 令牌使用量以及当前 RAG 索引健康状态。
• 调用 starcat.get_ai_usage_statistics，可设置 time_range = today | seven_days | thirty_days | all，并可选的 feature、provider_id 或 model 过滤器。
• 调用 starcat.get_knowledge_base_statistics 获取组织、语言/标签分布、来源覆盖、排除的块以及就绪/待处理/失败/过期的索引计数。

将 starred_repository_count 视为用户当前加星的仓库数量。将 top_starred_repositories 中的 github_stars 视为每个仓库的公共 GitHub 流行度；切勿混淆这两种含义。缺失的提供者使用情况由 calls_with_usage < call_count 表示，而不是假设每个缺失的调用消耗了零个令牌。

搜索和读取

• 调用 starcat.search_repos，参数为 query = "local first knowledge base"、scope = all、limit = 10。
• 调用 starcat.semantic_search 进行语义发现。
• 调用 starcat.get_repo_context 获取 apple/swift 的上下文。
• 仅当需要仓库文档时才调用 starcat.get_readme。
• 调用 starcat.list_tags 检查用户定义的标签。

README 内容可能很大。仅在任务需要仓库文档时才检索它。

管理笔记、状态和标签

通过 MCP 调用 starcat.upsert_repo_note、starcat.set_repo_status 以及标签工具。将 Markdown 作为 content 字段发送，而不是将敏感文本放在 shell 参数中。首先使用 dry_run = true；授权后，使用 dry_run = false 重复完全相同的调用。

处理摘要

调用 starcat.get_repo_summary 读取缓存的摘要。仅在用户明确请求生成时调用 starcat.generate_repo_summary。

摘要生成可能会消耗用户配置的 AI 提供商的配额。仅当用户明确允许外部搜索时，才添加 --allow-external-context。切勿将外部智能体编写的文本表示为原生 Starcat AI 摘要。如果用户希望保存智能体编写的内容，请将其存储为 Markdown 私人笔记并注明其来源。

如需检查 MCP 工具和终端命令的详细信息，请阅读 references/commands.md。如需重用工作流或从连接失败中恢复，请阅读 references/workflows.md。