zs-skills: Instructions file for Claude Code

zs-skills 使用说明

本仓库包含 Kakarot 维护的 Agent Skills。Claude Code、Codex 和其他兼容工具应从实际安装目录解析每项 Skill 的 scripts/、references/、assets/ 和 tools/，不要假定它一定安装在某个固定的隐藏目录。

安装与发现

安装全部 Skills：

npx skills add Zhangs-11/zs-skills

只安装一项时使用 --skill <name>。安装后可通过下面的命令核对仓库中的可发现名称：

npx skills add Zhangs-11/zs-skills --list

全局双向钢人入口

任务目标或方案存在实质歧义、竞争解释或重要取舍时，使用 steelman-before-answer。明确的简单任务直接核对相关事实并执行；需要用户决定时每次只问一个关键问题，回答后继续原任务。

这项 Skill 是交互入口，不代替领域 Skill。需要机制推导与反证时使用 first-principles-adversarial-review；需求澄清、问题诊断、代码 Review 和实现分别交给对应 Skill。

默认推理与核验

需求设计、根因诊断、复杂实现或关键事实争议需要机制推导与反证时，使用 first-principles-adversarial-review；简单查询、忠实摘要和不改变行为的局部修订只核对直接相关材料。它先区分真实目标、事实、约束和未经验证的假设，再追踪生产者、消费者、上下游与替代方案，并主动寻找能推翻初步结论的证据。

这项 Skill 可以与仓库内其他领域 Skill 叠加：例如 peer-pr-review 负责 CodeUp PR 的具体审查流程，first-principles-adversarial-review 负责避免顺着 PR 描述接受未经验证的根因。纯翻译、忠实转写、机械格式转换和无判断的一步操作不需要加载。

需求澄清与问题诊断

用户要求实现需求、修改功能、设计方案或完成复杂任务，且背景、范围、约束或验收标准仍有实质性歧义时，使用 clarify-before-action。先只读调查可自行确认的事实，再以苏格拉底方式一次只问一个关键问题；整理背景、需求、痛点、拟执行范围和明确不做事项，经用户确认后才能进入实现。事实清楚、低风险且可逆的一步操作无需强行追问。

用户要求分析报错、排查异常、寻找根因或解释“为什么会发生”时，使用 diagnose-and-explain。它覆盖技术、数据、业务、产品和流程问题：优先读取代码、日志、配置、数据和规则，建立安全的反馈或证据闭环，通过多个可证伪假设寻找反证，并用小白能理解的语言、例子或必要图示解释。只在缺少关键事实时一次问一个问题。

两项 Skill 都使用 first-principles-adversarial-review 作为推理底盘。只读调查无需确认；修改代码、配置、测试、文档或数据，以及提交、推送、部署、发消息和其他外部写操作，必须先说明拟执行范围并获得明确确认。需求确认和诊断结论都不能自动扩张成删除或发布授权。

深度研究

用户要求系统研究产品、公司、人物、技术、行业、制度或事件，并需要历史演化、横向比较、未来路径和可追溯来源时，使用 deep-research。它优先查一手来源，把关键主张拆成事实、推断和价值判断，并用历史形成的能力与约束解释当前差异。简单事实查询、当天资讯简报、单篇摘要和只核查一句话不使用完整研究流程。

长文写作工作流

用户说“帮我写篇文章”“按我的风格写”或提供链接、PDF、brief、采访和笔记要求出稿时，使用 kakarot-writer。

kakarot-writer 是个人长文总调度：它先确定 Kakarot 的作者位置、真实材料、核心判断和文章原型，再调用 human-writing 生成正文，最后完成个人风格复核、标题、截图与来源、正文配图、21:9 主封面和 1:1 分享封面。

“帮我写篇文章”默认表示完整交付，不需要另问用户是否需要标题和封面。公众号长文是首发载体，也是知乎、博客、掘金、小红书、抖音和B站共同使用的唯一内容母稿。长文平台可以原样同步正文和标题；小红书、抖音和B站视频交给 kakarot-repurposer 调整长度、节奏与画面，但不能改变母稿中的事实、核心判断、作者态度和来源。

封面和正文叙事配图的工具顺序以 kakarot-writer/references/delivery.md 的「封面」一节为准：baoyu-cover-image → guizang-social-card-skill → handraw-style 产出提示词再交给当前可用的图像生成工具 → HTML/SVG 代码绘制。回退时向用户说明实际用了哪一项。handraw-style 只给提示词，封面用它的 article-cover-designer，正文配图用 article-illustration-planner，出图仍由图像模型或作者自己的工具完成。