Claude-Code-Workflow/.claude/skills/skill-tuning/specs/skill-authoring-principles.md

# Skill Authoring Principles

Skill 撰写首要准则。所有诊断和优化以此为纲。

---

## 核心原则

```
简洁高效 → 去除无关存储 → 去除中间存储 → 上下文流转
```

---

## 1. 简洁高效

**原则**：最小化实现，只做必要的事

| DO | DON'T |
|----|-------|
| 单一职责阶段 | 臃肿的多功能阶段 |
| 直接的数据路径 | 迂回的处理流程 |
| 必要的字段 | 冗余的 schema 定义 |
| 精准的 prompt | 过度详细的指令 |

**检测模式**：
- Phase 文件 > 200 行 → 需拆分
- State schema 字段 > 20 个 → 需精简
- 同一数据多处定义 → 需去重

---

## 2. 去除无关存储

**原则**：不存储不需要的数据

| DO | DON'T |
|----|-------|
| 只存最终结果 | 存储调试信息 |
| 存路径引用 | 存完整内容副本 |
| 存必要索引 | 存全量历史 |

**检测模式**：
```javascript
// BAD: 存储完整内容
state.full_analysis_result = longAnalysisOutput;

// GOOD: 存路径 + 摘要
state.analysis = {
  path: `${workDir}/analysis.json`,
  summary: extractSummary(output),
  key_findings: extractFindings(output)
};
```

**反模式清单**：
- `state.debug_*` → 删除
- `state.*_history` (无限增长) → 限制或删除
- `state.*_cache` (会话内) → 改用内存变量
- 重复字段 → 合并

---

## 3. 去除中间存储

**原则**：避免临时文件和中间状态文件

| DO | DON'T |
|----|-------|
| 直接传递结果 | 写文件再读文件 |
| 函数返回值 | 中间 JSON 文件 |
| 管道处理 | 阶段性存储 |

**检测模式**：
```javascript
// BAD: 中间文件
Write(`${workDir}/temp-step1.json`, step1Result);
const step1 = Read(`${workDir}/temp-step1.json`);
const step2Result = process(step1);
Write(`${workDir}/temp-step2.json`, step2Result);

// GOOD: 直接流转
const step1Result = await executeStep1();
const step2Result = process(step1Result);
const finalResult = finalize(step2Result);
Write(`${workDir}/final-output.json`, finalResult);  // 只存最终结果
```

**允许的存储**：
- 最终输出（用户需要的结果）
- 检查点（长流程恢复用，可选）
- 备份（修改前的原始文件）

**禁止的存储**：
- `temp-*.json`
- `intermediate-*.json`
- `step[N]-output.json`
- `*-draft.md`

---

## 4. 上下文流转

**原则**：通过上下文传递而非文件

| DO | DON'T |
|----|-------|
| 函数参数传递 | 全局状态读写 |
| 返回值链式处理 | 文件中转 |
| prompt 内嵌数据 | 指向外部文件 |

**模式**：
```javascript
// 上下文流转模式
async function executePhase(context) {
  const { previousResult, constraints, config } = context;

  const result = await Agent({
    subagent_type: 'universal-executor',
    description: 'Execute phase with context passing',
    run_in_background: false,
    prompt: `
      [CONTEXT]
      Previous: ${JSON.stringify(previousResult)}
      Constraints: ${constraints.join(', ')}

      [TASK]
      Process and return result directly.
    `
  });

  return {
    ...context,
    currentResult: result,
    completed: ['phase-name']
  };
}

// 链式执行
let ctx = initialContext;
ctx = await executePhase1(ctx);
ctx = await executePhase2(ctx);
ctx = await executePhase3(ctx);
// ctx 包含完整上下文，无中间文件
```

**State 最小化**：
```typescript
// 只存必要状态
interface MinimalState {
  status: 'pending' | 'running' | 'completed';
  target: { name: string; path: string };
  result_path: string;  // 最终结果路径
  error?: string;
}
```

---

## 应用场景

### 诊断时检查

| 检查项 | 违反时标记 |
|--------|-----------|
| Phase 内写入 temp 文件 | `unnecessary_storage` |
| State 包含 *_history 无限数组 | `unbounded_state` |
| 文件写入后立即读取 | `redundant_io` |
| 多阶段传递完整内容 | `context_bloat` |

### 优化策略

| 问题 | 策略 |
|------|------|
| 中间文件过多 | `eliminate_intermediate_files` |
| State 膨胀 | `minimize_state_schema` |
| 重复存储 | `deduplicate_storage` |
| 文件中转 | `context_passing` |

---

## 合规检查清单

```
□ 无 temp/intermediate 文件写入
□ State schema < 15 个字段
□ 无重复数据存储
□ Phase 间通过上下文/返回值传递
□ 只存最终结果文件
□ 无无限增长的数组
□ 无调试字段残留
```