pythia-skill-author

编写新技能

开始时宣告：“正在使用 pythia-skill-author——一起来记录你实际的工作方式吧。”

**阶段：**了解 → 询问 → 执行 — 访谈、挖掘架构、验证触发条件

技能是记录下来、无需反复争论的决策。记录团队实际的做法——以数据库中的证据为依据，而不是凭任何人的记忆。

第 1 步 — 逐个提问

按顺序提问，每次只问一个，等待对方回答：

1. 这是用来处理什么任务的？» 一个技能只针对一个关注点——“我们的报告流程”是一项技能；“关于我们团队的一切”则不是。
2. 什么情况下应该触发？ 收集开发者自己的说法——他们会输入的短语（“làm báo cáo”、“clone the export proc”、错误代码、文件模式）。这些内容要原样写入描述；触发与否就取决于它们。
3. 哪些部分是硬性规定，哪些只是偏好？ 硬性规则写入 Iron Law，并用红旗表格列出；偏好则写成“除非另有说明，否则默认如此”。
4. 什么情况算是错误？ 过往事故最适合用作红旗表格中的条目。

第 2 步 — 挖掘证据

记忆会骗人；架构不会。动笔前：

• pythia similar <TYPICAL_NAME> → 找出体现此工作流的程序类别；用 pythia src 打开最相关的结果，提取实际的命名、参数和结构惯例。
• 使用 pythia args / pythia cols 查看技能会建议大家使用的签名和类型。
• 保存两三个简短的原文片段作为示例——真实代码胜过编造的代码。

第 3 步 — 按团队格式起草

• Frontmatter：使用与文件夹名称一致的 kebab-case name；description 以触发条件开头（Use when ...），并包含第 1 步中开发者使用的短语。
• 正文控制在约 150 行以内。较长的材料（模板、检查清单、片段库）放入 reference/ 并添加链接，不要直接粘贴。
• 结构选项 — 根据回答选择所需部分，其余略过： Iron Law（一行，全大写）· 编号工作流 · 红旗表格（“想法 → 实际情况”）· “何时不要使用”· 开始时宣告行。
• 使用团队的工作语言撰写；此工具包使用英语，私人团队技能也可以使用越南语——由开发者决定。

不是所有内容都需要技能。 纯粹的命名和风格规则更适合放在 .pythia/conventions.json（每次应用预览时由机器检查）和 .pythia/conventions.md（供 Agent 阅读的说明性文字）中。技能应留给工作流——包含步骤、关卡和判断的事项。

第 4 步 — 放置文件并运行 lint

pythia skill new <name> --trigger <the developer's words> 会按此工具包的格式生成 .claude/skills/<name>/SKILL.md；根据第 1–3 步的内容填写。pythia skill lint 会根据工具包自身遵循的同一套规范检查项目中的每项技能——frontmatter 可解析、包含 Use when 触发条件、名称与文件夹一致、行数符合限制、包含 Phase 行、引用的文件存在——遇到问题时以 2 退出。

用户技能应放在开发者的项目中，例如 Claude Code 的 .claude/skills/<name>/SKILL.md（其他 Agent 可使用 skills/<name>/SKILL.md 布局，并通过 npx skills add 添加）。切勿写入已安装的 pythia 工具包——更新会覆盖这些内容，而且工具包的 lint 会强制执行其固定的技能列表。

第 5 步 — 验证触发效果

在一个全新会话中，用开发者实际会提出的说法（第 2 步中的短语）给出一个任务。技能必须在没有提示的情况下自动激活。如果没有触发，问题就在描述中：加入触发失败时的确切短语，让描述更精确，然后重新测试。

持续维护

当开发者因同一件事纠正 Agent 两次时，建议将这条纠正纳入技能——这说明技能发挥了作用。删除已不再成立的规则；过时的技能比没有技能更糟。

分享到团队之外之前

运行此工具包自身采用的卫生检查：技能及其参考资料中不能包含主机、架构名称、凭据或内部标识符。在私有代码仓库中没问题的内容，放到公开代码仓库中就是信息泄露。

危险信号 — 如果发现自己有以下想法，请立即停止

想法	事实
“我会凭这次聊天的记忆来写”	先检查 similar/src——代码库才是权威来源。
“写一个涵盖所有内容的大型技能”	每个技能只关注一个方面，否则就无法可靠触发。
“把整份风格指南都贴进去”	预算约为 150 行；较长的材料放到 reference/。
“描述写得笼统一点也行”	笼统的描述永远不会触发。使用开发者自己的措辞。
“能用就行，不必测试触发效果”	未经测试的触发效果 = 再也没人会看到的技能。