duck-adapt

技能适配器 🦆。将外部技能转化为扎根于橡皮鸭哲学的版本。

目的

将外部技能或工作流转化为扎根于橡皮鸭理念的版本，在保留原意的同时，加入：

• 苏格拉底式提问流程
• 证据优先原则
• Duck Ladder 最小变更思维
• 执行审批关卡
• 提示词顺序标准合规性

还会验证现有的 duck-* 技能，并检测不必要的重复。

哲学护栏（技能本地）

继承 references/GUARDRAILS.md 中的共享护栏。

• 上下文不完整时，提出 1-3 个有针对性的澄清问题
• 缺少证据时，明确说明假设

技能特定差异：

• 元技能：作用于技能定义，而非直接作用于代码库
• 输出是技能草案，而非实现
• 检测到重叠或重复时，建议拒绝新增技能

激活条件

适用于以下情况：

• 用户提供外部技能，要求适配
• 用户描述要转化为技能的工作流或流程
• 用户要求审核现有技能是否符合哲学要求
• 用户询问“我们是否应该添加这项技能”或“这是否与现有技能重叠”

方法

1. 收集信息并分类

提出澄清问题（最多 3 个），以确定：

对于外部技能适配：

• 输入格式：完整的技能 Markdown、工作流文档，还是概念描述？
• 意图：这项技能要解决什么问题？
• 范围：修改操作（编辑/命令）还是非修改操作（分析/建议）？
• 目标受众：用户预期的使用场景是什么？

对于技能审核：

• 要审核哪项技能？（名称或路径）
• 审核深度：快速合规性检查，还是全面的重叠分析？

对于重叠检测：

• 技能概念摘要
• 预期工作流步骤
• 是否需要与现有技能进行比较？

2. 收集证据

对于外部技能：

• 解析输入：提取步骤、约束、输出和示例
• 识别决策点（需要用户选择的环节）
• 识别修改操作（需要设置审批关卡）
• 识别证据缺口（需要读取代码/差异/日志的环节）

对于技能审核：

• 从 .agents/skills/<name>/SKILL.md 读取技能源文件
• 检查是否符合哲学护栏
• 检查是否符合提示词顺序标准（04-prompt-order-standard.md）
• 检查修改操作是否设置了执行审批关卡
• 检查是否符合资源规范（07-skill-asset-convention.md）

对于重叠检测：

• 从 .agents/skills/*/SKILL.md 的 frontmatter 加载现有技能摘要
• 比较意图、范围和工作流模式
• 识别语义重叠与互补组合

3. 理念映射

加载理念资源：

• assets/philosophy-core.md — 完整的橡皮鸭理念参考
• assets/socratic-patterns.md — 10 种转换模式（命令式 -> 提问式、自动执行 -> 需审批，等等）
• assets/approval-gate-spec.md — 6 步执行审批规范
• assets/adaptation-checklist.md — 全面的转换检查清单

使用已加载的模式应用橡皮鸭理念转换：

决策归属：

• 在决策点插入澄清问题
• 明确呈现用户的选择（“选哪个选项？”而不是“我会选 X”）
• 在提出建议前展示权衡
• 模式：命令式 -> 提问式（socratic-patterns.md #1）

证据优先：

• 在得出结论前添加收集证据的步骤
• 对应到代码库阅读模式（定义/引用/调用方/测试）
• 让主张以具体产物为依据
• 模式：黑盒 -> 证据优先（socratic-patterns.md #3）

橡皮鸭阶梯：

• 在实现步骤中加入最小改动原则
• 在“添加新代码”步骤之前插入 6 阶检查
• 优先修复根因，而不是修补症状
• 模式：复杂 -> 橡皮鸭阶梯（socratic-patterns.md #6）

执行审批：

• 识别所有会产生变更的操作（编辑、命令、任务委派）
• 插入 6 步审批关卡（approval-gate-spec.md）
• 添加预检（文件、行为和验证）
• 添加范围变更检测
• 模式：自动执行 -> 审批关卡（socratic-patterns.md #2）

苏格拉底式流程：

• 适当将命令式步骤改为提问式步骤
• 提出隐含假设
• 提供质疑约束条件的机会
• 模式：单一路径 -> 多种选项（socratic-patterns.md #4），告知 -> 展示选项（#8）

4. 结构转换

应用提示词顺序标准：

技能章节（按顺序）：

1. ## Purpose — 用一句话说明意图和关键转换
2. ## Philosophy Guardrails — 包含标准和技能特定的差异
3. ## Activation — 使用时机、用户信号
4. ## Method — 带有内联输出格式的编号步骤
5. ## Boundaries — 约束、交接、范围限制

资源识别：

• assets/ 候选内容：始终加载的数据（检查清单、模板、矩阵）
• references/ 候选内容：按需加载的文档（示例、模式、边缘情况）

Frontmatter：

---
name: duck-<name>
description: >
  One-line purpose. Key capabilities. Use when: "signal phrases".
---

5. 重叠分析

加载重叠检测资源：

• assets/overlap-patterns.md — 所有 12 个技能的意图映射和评分规则

使用已加载的模式与现有技能进行比较：

重叠评分（来自 overlap-patterns.md）：

• 高重叠（意图匹配度 >70%）： 建议拒绝或合并
• 中等重叠（40-70%）： 建议扩展现有技能
• 低重叠（<40%）： 若差异化价值明确，可创建新技能
• 互补： 采用组合模式，而不是创建新技能

警示信号（来自 overlap-patterns.md）：

• 自动执行（没有用户决策点）
• 静默实现（没有审批关卡）
• 黑盒建议（没有证据依据）
• 绕过安全措施（削弱信任边界/安全性）
• 高度重复（重叠度 >90%）

组合模式（来自 overlap-patterns.md）：

• 调试 -> 修补、审查 -> 风险 -> 简化、设计 -> 分类、教学 -> 调试

6. 生成输出

技能适配：

输出完整目录结构：

.agents/skills/duck-<name>/
├── SKILL.md (full skill definition)
├── assets/ (if always-loaded data needed)
│   └── <template/checklist>.md
├── references/ (if conditional docs needed)
│   └── EXAMPLES.md
└── evals/ (skeleton)
    └── evals.json

输出格式：

## 🦆 Skill Adaptation: duck-<name>

### Adaptation Overlap Analysis
- **Semantic overlap:** [None | Low | Medium | High] with [existing skills]
- **Recommendation:** [Add as new skill | Extend existing | Reject (use X instead) | Composition pattern]
- **Rationale:** [one-line justification]

### Philosophy Transformations Applied
- ✅ Decision ownership: [what changed]
- ✅ Evidence-first: [what changed]
- ✅ Duck Ladder: [what changed]
- ✅ Execution approval: [what changed]
- ✅ Socratic flow: [what changed]

### Skill Definition
[Full SKILL.md content]

### Assets (if any)
[Asset file contents with metadata headers]

### Next Steps
1. Review adaptation for intent preservation
2. Confirm overlap assessment
3. If approved: run `make build-skills` to generate artifacts

技能审计：

## 🦆 Skill Audit: <skill-name>

### Compliance Check
- ✅/❌ Philosophy guardrails present
- ✅/❌ Prompt order standard followed
- ✅/❌ Execution approval gates on mutating actions
- ✅/❌ Asset convention compliance
- ✅/❌ Duck Ladder discipline included

### Findings
**High priority:**
- [H1] [issue description + fix suggestion]

**Medium priority:**
- [M1] [issue description + fix suggestion]

**Low priority:**
- [L1] [issue description + fix suggestion]

### Overlap Analysis
- Semantic overlap with: [other skills]
- Composition opportunities: [patterns]
- Redundancy risk: [None | Low | Medium | High]

### Audit Recommendations
[Prioritized list of changes or "No changes needed"]

重叠检测：

## 🦆 Overlap Analysis: <concept>

### Existing Coverage
- **Primary match:** [skill name] — [overlap %] — [why]
- **Secondary match:** [skill name] — [overlap %] — [why]

### Gap Analysis
- **Unique value:** [what this concept adds that existing skills don't cover]
- **Composition alternative:** [how existing skills could be chained instead]

### Recommendation
[Add new skill | Extend existing | Use composition | Not needed]

**Rationale:** [2-3 sentence justification]

边界

• 不要生成会削弱安全例外（信任边界、安全、数据保护、无障碍）的技能
• 不要改编会在未经明确批准的情况下自动替用户做出决策的技能
• 如果外部技能理念与 duck 原则存在无法调和的冲突，应说明理由并建议拒绝
• 重叠分析仅供参考；是否添加技能由用户最终决定
• 生成的技能均为草稿；用户应在提交前进行审核
• 不要自动执行 make build-skills；用户批准后自行运行

交接：

• 如果用户批准新技能 -> “运行 make build-skills 以生成构件”
• 如果审核发现问题 -> 对于小型修复，建议使用 duck-patch；对于重构，建议使用 duck-refactor
• 如果重叠度较高 -> 建议通过明确的工作流使用现有技能