附录 D：Agent Skill 模板

Skill 是可复用的任务方法包，不是普通 Prompt，也不是 Tool 集合。

目录结构

skills/<skill-name>/
  SKILL.md
  examples/
    example-1.md
  resources/
    checklist.md
  scripts/
    helper.sh

SKILL.md 模板

---
name: <skill-name>
description: Use when <clear trigger condition>. Produces <expected output>.
version: 0.1.0
requiredTools:
  - <tool-name>
optionalTools:
  - <tool-name>
riskLevel: low | medium | high
owner: <team-or-person>
---

# <Skill Name>

## When to use

Use this skill when:

- <condition 1>;
- <condition 2>;
- <condition 3>.

Do not use this skill when:

- <anti-condition 1>;
- <anti-condition 2>.

## Goal

This skill helps the Agent <task goal>.

## Procedure

1. <First step>.
2. <Second step>.
3. <Inspect evidence or tool result>.
4. <Generate output>.
5. <Verify result>.

## Rules

- <Rule 1>.
- <Rule 2>.
- Do not claim success without evidence.
- Do not perform write actions unless explicitly allowed.

## Required evidence

The final output must cite:

- <evidence type 1>;
- <evidence type 2>;
- <source reference>.

## Output format

```json
{
  "status": "ANALYZED",
  "summary": "...",
  "evidence": ["..."],
  "nextSteps": ["..."],
  "confidence": 0.0,
  "limitations": ["..."]
}
```

## Examples

See:

- `examples/example-1.md`

## Resources

See:

- `resources/checklist.md`

CI 失败分析 Skill 示例

name: ci-failure-analysis
description: Use when analyzing CI build failures from logs, Git diff, and project instructions. Produces root cause, evidence, suspected files, suggested fix, and confidence.
requiredTools:
  - summarize_ci_failure
  - get_git_diff
  - search_code
  - read_file_range
riskLevel: low

核心 Procedure：

1. Read CI failure summary first.
2. Classify failure type.
3. Extract failed test, exception, and key stack frame.
4. Compare with recent Git Diff.
5. Read only relevant files.
6. Produce evidence-backed report.
7. Do not claim code was fixed in read-only mode.