第14篇-Body正文结构规范-从When-to-Use到Verification

【Skills 系统从入门到精通】第 14 篇：Body 正文结构规范——从 When to Use 到 Verification

本篇你将学到

Body 正文的六层标准章节结构
每个章节的写作规范和质量标准
好的 Body vs 差的 Body 对比分析
正文中的代码块、命令和表格的写作规范

读完本篇，你将能够编写结构规范、质量过硬的技能正文内容。

一、六层标准结构

1.1 结构总览

Body 正文推荐遵循以下章节顺序：

# 技能标题

## Overview ← 概述（是什么、为什么）
## When to Use ← 触发条件（什么时候用）
## Procedure ← 操作步骤（怎么做）
## Pitfalls ← 已知陷阱（注意什么）
## Verification ← 验证步骤（怎么确认成功）
## References ← 辅助文件引用（去哪找更多）

不是每个章节都强制要求，但 Overview + When to Use + Procedure + Pitfalls 是高质量技能的最低标准。

#mermaid-svg-gRonYXiDWotKvyA6{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-gRonYXiDWotKvyA6 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-gRonYXiDWotKvyA6 .error-icon{fill:#552222;}#mermaid-svg-gRonYXiDWotKvyA6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-gRonYXiDWotKvyA6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-gRonYXiDWotKvyA6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-gRonYXiDWotKvyA6 .marker.cross{stroke:#333333;}#mermaid-svg-gRonYXiDWotKvyA6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-gRonYXiDWotKvyA6 p{margin:0;}#mermaid-svg-gRonYXiDWotKvyA6 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-gRonYXiDWotKvyA6 .cluster-label text{fill:#333;}#mermaid-svg-gRonYXiDWotKvyA6 .cluster-label span{color:#333;}#mermaid-svg-gRonYXiDWotKvyA6 .cluster-label span p{background-color:transparent;}#mermaid-svg-gRonYXiDWotKvyA6 .label text,#mermaid-svg-gRonYXiDWotKvyA6 span{fill:#333;color:#333;}#mermaid-svg-gRonYXiDWotKvyA6 .node rect,#mermaid-svg-gRonYXiDWotKvyA6 .node circle,#mermaid-svg-gRonYXiDWotKvyA6 .node ellipse,#mermaid-svg-gRonYXiDWotKvyA6 .node polygon,#mermaid-svg-gRonYXiDWotKvyA6 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-gRonYXiDWotKvyA6 .rough-node .label text,#mermaid-svg-gRonYXiDWotKvyA6 .node .label text,#mermaid-svg-gRonYXiDWotKvyA6 .image-shape .label,#mermaid-svg-gRonYXiDWotKvyA6 .icon-shape .label{text-anchor:middle;}#mermaid-svg-gRonYXiDWotKvyA6 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-gRonYXiDWotKvyA6 .rough-node .label,#mermaid-svg-gRonYXiDWotKvyA6 .node .label,#mermaid-svg-gRonYXiDWotKvyA6 .image-shape .label,#mermaid-svg-gRonYXiDWotKvyA6 .icon-shape .label{text-align:center;}#mermaid-svg-gRonYXiDWotKvyA6 .node.clickable{cursor:pointer;}#mermaid-svg-gRonYXiDWotKvyA6 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-gRonYXiDWotKvyA6 .arrowheadPath{fill:#333333;}#mermaid-svg-gRonYXiDWotKvyA6 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-gRonYXiDWotKvyA6 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-gRonYXiDWotKvyA6 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gRonYXiDWotKvyA6 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-gRonYXiDWotKvyA6 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gRonYXiDWotKvyA6 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-gRonYXiDWotKvyA6 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-gRonYXiDWotKvyA6 .cluster text{fill:#333;}#mermaid-svg-gRonYXiDWotKvyA6 .cluster span{color:#333;}#mermaid-svg-gRonYXiDWotKvyA6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-gRonYXiDWotKvyA6 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-gRonYXiDWotKvyA6 rect.text{fill:none;stroke-width:0;}#mermaid-svg-gRonYXiDWotKvyA6 .icon-shape,#mermaid-svg-gRonYXiDWotKvyA6 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gRonYXiDWotKvyA6 .icon-shape p,#mermaid-svg-gRonYXiDWotKvyA6 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-gRonYXiDWotKvyA6 .icon-shape .label rect,#mermaid-svg-gRonYXiDWotKvyA6 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gRonYXiDWotKvyA6 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-gRonYXiDWotKvyA6 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-gRonYXiDWotKvyA6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

技能标题

Overview是什么为什么

When to Use什么时候用

Procedure怎么做

Pitfalls注意什么

Verification怎么确认成功

References去哪找更多

1.2 章节的 Progressive Disclosure 映射

Body 的章节结构也体现了 Progressive Disclosure 的思想：

#mermaid-svg-HNgC5sLmskGSz4Qu{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-HNgC5sLmskGSz4Qu .error-icon{fill:#552222;}#mermaid-svg-HNgC5sLmskGSz4Qu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-HNgC5sLmskGSz4Qu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-HNgC5sLmskGSz4Qu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-HNgC5sLmskGSz4Qu .marker.cross{stroke:#333333;}#mermaid-svg-HNgC5sLmskGSz4Qu svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-HNgC5sLmskGSz4Qu p{margin:0;}#mermaid-svg-HNgC5sLmskGSz4Qu .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster-label text{fill:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster-label span{color:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster-label span p{background-color:transparent;}#mermaid-svg-HNgC5sLmskGSz4Qu .label text,#mermaid-svg-HNgC5sLmskGSz4Qu span{fill:#333;color:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu .node rect,#mermaid-svg-HNgC5sLmskGSz4Qu .node circle,#mermaid-svg-HNgC5sLmskGSz4Qu .node ellipse,#mermaid-svg-HNgC5sLmskGSz4Qu .node polygon,#mermaid-svg-HNgC5sLmskGSz4Qu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-HNgC5sLmskGSz4Qu .rough-node .label text,#mermaid-svg-HNgC5sLmskGSz4Qu .node .label text,#mermaid-svg-HNgC5sLmskGSz4Qu .image-shape .label,#mermaid-svg-HNgC5sLmskGSz4Qu .icon-shape .label{text-anchor:middle;}#mermaid-svg-HNgC5sLmskGSz4Qu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-HNgC5sLmskGSz4Qu .rough-node .label,#mermaid-svg-HNgC5sLmskGSz4Qu .node .label,#mermaid-svg-HNgC5sLmskGSz4Qu .image-shape .label,#mermaid-svg-HNgC5sLmskGSz4Qu .icon-shape .label{text-align:center;}#mermaid-svg-HNgC5sLmskGSz4Qu .node.clickable{cursor:pointer;}#mermaid-svg-HNgC5sLmskGSz4Qu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-HNgC5sLmskGSz4Qu .arrowheadPath{fill:#333333;}#mermaid-svg-HNgC5sLmskGSz4Qu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-HNgC5sLmskGSz4Qu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-HNgC5sLmskGSz4Qu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HNgC5sLmskGSz4Qu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-HNgC5sLmskGSz4Qu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HNgC5sLmskGSz4Qu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster text{fill:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu .cluster span{color:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-HNgC5sLmskGSz4Qu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-HNgC5sLmskGSz4Qu rect.text{fill:none;stroke-width:0;}#mermaid-svg-HNgC5sLmskGSz4Qu .icon-shape,#mermaid-svg-HNgC5sLmskGSz4Qu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HNgC5sLmskGSz4Qu .icon-shape p,#mermaid-svg-HNgC5sLmskGSz4Qu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-HNgC5sLmskGSz4Qu .icon-shape .label rect,#mermaid-svg-HNgC5sLmskGSz4Qu .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HNgC5sLmskGSz4Qu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-HNgC5sLmskGSz4Qu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-HNgC5sLmskGSz4Qu :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Level 0description

Level 1 前两节Overview When to Use判断是否匹配

Level 1 核心Procedure Pitfalls Verification

Level 2References 触发加载

Agent 在加载 Level 1 后，先读 Overview 和 When to Use 确认技能与任务匹配，然后深入 Procedure 执行操作。References 只在需要更多细节时才触发 Level 2 加载。

二、各章节写作规范

2.1 Overview（概述）

目的：1-2 段话说清"这个技能是什么、解决什么问题"。

写作要点：

不要重复 description 中已经说过的话
聚焦于"价值"——为什么需要这个技能
控制在 100-200 字

好的写法：

## Overview
This skill provides a systematic approach to analyzing server logs.
It covers error extraction, pattern identification, statistical analysis,
and root cause investigation. Designed for production troubleshooting
scenarios where log volume is large and manual inspection is impractical.

差的写法：

## Overview
This is a log analysis skill. ← 重复 description
It has many features and is very powerful. ← 空话，无信息量

2.2 When to Use（触发条件）

目的：明确列出什么场景下应该使用这个技能。

写作要点：

用 bullet list 列出具体触发条件
可以加 “Don’t use for:” 反触发条件
条件要具体，不要泛泛而谈

好的写法：

## When to Use
– Server logs show repeated errors or exceptions
– Need to identify root cause of a production incident
– Log volume suddenly increases abnormally
– Investigating performance degradation patterns in logs
– Need to extract specific error patterns across multiple log files

Don't use for:
– Real-time log streaming (use monitoring tools instead)
– Log aggregation setup (that's infrastructure, not analysis)

差的写法：

## When to Use
– When you have log problems ← 太模糊
– When you need help with logs ← 没有具体场景

2.3 Procedure（操作步骤）

目的：核心部分。提供具体的、可执行的操作步骤。

写作要点：

按逻辑顺序编号
每个步骤对应可执行的工具调用
包含实际的命令和代码
步骤之间标注依赖关系

好的写法：

## Procedure

### Step 1: Identify the log file
Determine the log file path and format:
```bash
# Check common log locations
ls -lh /var/log/
ls -lh /var/log/myapp/

# Check if log rotation is active
ls -lh /var/log/myapp/app.log*

Step 2: Extract error lines

Extract lines containing errors using grep:

# Extract ERROR and FATAL level logs
grep -E '(ERROR|FATAL)' /var/log/myapp/app.log

# With timestamps for time-based analysis
grep -E '(ERROR|FATAL)' /var/log/myapp/app.log | awk '{print $1, $2, $0}'

Step 3: Statistical analysis

Count errors by type to identify patterns:

**差的写法：**

```markdown
## Procedure
1. 找到日志文件 ← 怎么找？没有命令
2. 提取错误 ← 用什么工具？什么模式？
3. 分析问题 ← 分析什么？怎么分析？

每个步骤的可执行性是关键——Agent 应该能直接照着步骤中的命令执行，而不需要自己猜测"用什么命令"。

2.4 Pitfalls（陷阱）

目的：记录已知的失败模式和修复方法，防止 Agent 重蹈覆辙。

写作要点：

每个陷阱包含：问题 + 原因 + 解决方案
来源于实际经验（踩过的坑）
这是技能最有价值的部分之一

好的写法：

## Pitfalls

1. **Log rotation**: The current active log might be `app.log.1.gz`,
not `app.log`. Check both before assuming you have the latest logs.
Fix: `ls -lh /var/log/myapp/app.log*` to see all rotated files.

2. **Timezone mismatch**: Application logs often use UTC, not local time.
Cross-referencing with local-time monitoring data without conversion
leads to wrong conclusions.
Fix: Use `date -u` to check UTC time, convert explicitly.

3. **Encoding issues**: Some legacy systems produce non-UTF8 log entries.
grep may silently skip these lines.
Fix: Use `iconv -f GBK -t UTF-8` before processing, or use `LANG=C grep`.

4. **Giant log files**: Opening a 10GB log file directly will hang.
Always use `wc -l` first to check size, then use `tail`/`grep` to
process incrementally.

差的写法：

## Pitfalls
– Be careful with logs ← 注意什么？
– Logs can be tricky ← 没有信息量

2.5 Verification（验证步骤）

目的：提供确认任务正确完成的方法。

写作要点：

具体的检查命令或验证逻辑
预期结果说明
使用 checkbox 格式便于逐项检查

好的写法：

## Verification

– [ ] Error count matches: `grep -c 'ERROR' app.log` should equal
the sum of all error type counts
– [ ] Time range correct: first and last timestamps in extracted results
fall within the target window
– [ ] No encoding artifacts: check for mojibake in extracted lines
– [ ] Cross-reference with monitoring: error spike times match
dashboard alert timestamps

2.6 References（辅助文件引用）

目的：引导 Agent 到 Level 2 辅助文件获取更多细节。

写作要点：

说明每个文件的内容和用途
使用相对路径
只在当前任务需要时才加载

辅助文件SKILL.md 正文Agent辅助文件SKILL.md 正文Agent#mermaid-svg-uWZnROL2QLe7bphM{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-uWZnROL2QLe7bphM .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-uWZnROL2QLe7bphM .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-uWZnROL2QLe7bphM .error-icon{fill:#552222;}#mermaid-svg-uWZnROL2QLe7bphM .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-uWZnROL2QLe7bphM .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-uWZnROL2QLe7bphM .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-uWZnROL2QLe7bphM .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-uWZnROL2QLe7bphM .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-uWZnROL2QLe7bphM .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-uWZnROL2QLe7bphM .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-uWZnROL2QLe7bphM .marker{fill:#333333;stroke:#333333;}#mermaid-svg-uWZnROL2QLe7bphM .marker.cross{stroke:#333333;}#mermaid-svg-uWZnROL2QLe7bphM svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-uWZnROL2QLe7bphM p{margin:0;}#mermaid-svg-uWZnROL2QLe7bphM .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWZnROL2QLe7bphM text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-uWZnROL2QLe7bphM .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uWZnROL2QLe7bphM .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-uWZnROL2QLe7bphM .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-uWZnROL2QLe7bphM .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-uWZnROL2QLe7bphM #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-uWZnROL2QLe7bphM .sequenceNumber{fill:white;}#mermaid-svg-uWZnROL2QLe7bphM #sequencenumber{fill:#333;}#mermaid-svg-uWZnROL2QLe7bphM #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-uWZnROL2QLe7bphM .messageText{fill:#333;stroke:none;}#mermaid-svg-uWZnROL2QLe7bphM .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWZnROL2QLe7bphM .labelText,#mermaid-svg-uWZnROL2QLe7bphM .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-uWZnROL2QLe7bphM .loopText,#mermaid-svg-uWZnROL2QLe7bphM .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-uWZnROL2QLe7bphM .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uWZnROL2QLe7bphM .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-uWZnROL2QLe7bphM .noteText,#mermaid-svg-uWZnROL2QLe7bphM .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-uWZnROL2QLe7bphM .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWZnROL2QLe7bphM .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWZnROL2QLe7bphM .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uWZnROL2QLe7bphM .actorPopupMenu{position:absolute;}#mermaid-svg-uWZnROL2QLe7bphM .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-uWZnROL2QLe7bphM .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uWZnROL2QLe7bphM .actor-man circle,#mermaid-svg-uWZnROL2QLe7bphM line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-uWZnROL2QLe7bphM :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}Level 1 加载Overview When to Use判断与任务匹配继续 Procedure Pitfalls步骤引用文件清单需要细节时 Level 2 加载具体参考内容
## References
– Log format field catalog: `references/log-format-catalog.md`
(consult this when you need to understand specific log fields)
– Custom log parser: `scripts/log_parser.py`
(use this for complex multi-line log formats)
– Sample analysis output: `examples/analysis-report.md`

三、代码块规范

3.1 必须标注语言

# ✅ 正确
```bash
grep 'ERROR' /var/log/app.log

import re
pattern = r'\\[(\\w+)\\] ERROR: (.+)'

❌ 错误——没有语言标签

grep 'ERROR' /var/log/app.log

语言标签帮助 CSDN 质量评分，也让 Agent 更准确地理解代码类型。

### 3.2 代码必须可运行

每个代码块都应该是可以直接复制执行的完整命令或代码，不要使用占位符或伪代码。

```markdown
# ✅ 可执行
```bash
grep -E '(ERROR|FATAL)' /var/log/myapp/app.log | wc -l

❌ 伪代码

—

## 四、好 Body vs 差 Body 完整对比

### 4.1 差的 Body

```markdown
# Log Analysis

This skill analyzes logs.

## How to use
Just analyze the logs and find errors.

## Steps
1. Look at the log
2. Find errors
3. Report them

问题：无 Overview 价值、When to Use 缺失、步骤不可执行、无 Pitfalls、无 Verification。

#mermaid-svg-TlaeuXZZCdGgEY0C{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-TlaeuXZZCdGgEY0C .error-icon{fill:#552222;}#mermaid-svg-TlaeuXZZCdGgEY0C .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TlaeuXZZCdGgEY0C .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TlaeuXZZCdGgEY0C .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TlaeuXZZCdGgEY0C .marker.cross{stroke:#333333;}#mermaid-svg-TlaeuXZZCdGgEY0C svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TlaeuXZZCdGgEY0C p{margin:0;}#mermaid-svg-TlaeuXZZCdGgEY0C .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster-label text{fill:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster-label span{color:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster-label span p{background-color:transparent;}#mermaid-svg-TlaeuXZZCdGgEY0C .label text,#mermaid-svg-TlaeuXZZCdGgEY0C span{fill:#333;color:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C .node rect,#mermaid-svg-TlaeuXZZCdGgEY0C .node circle,#mermaid-svg-TlaeuXZZCdGgEY0C .node ellipse,#mermaid-svg-TlaeuXZZCdGgEY0C .node polygon,#mermaid-svg-TlaeuXZZCdGgEY0C .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TlaeuXZZCdGgEY0C .rough-node .label text,#mermaid-svg-TlaeuXZZCdGgEY0C .node .label text,#mermaid-svg-TlaeuXZZCdGgEY0C .image-shape .label,#mermaid-svg-TlaeuXZZCdGgEY0C .icon-shape .label{text-anchor:middle;}#mermaid-svg-TlaeuXZZCdGgEY0C .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-TlaeuXZZCdGgEY0C .rough-node .label,#mermaid-svg-TlaeuXZZCdGgEY0C .node .label,#mermaid-svg-TlaeuXZZCdGgEY0C .image-shape .label,#mermaid-svg-TlaeuXZZCdGgEY0C .icon-shape .label{text-align:center;}#mermaid-svg-TlaeuXZZCdGgEY0C .node.clickable{cursor:pointer;}#mermaid-svg-TlaeuXZZCdGgEY0C .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-TlaeuXZZCdGgEY0C .arrowheadPath{fill:#333333;}#mermaid-svg-TlaeuXZZCdGgEY0C .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-TlaeuXZZCdGgEY0C .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-TlaeuXZZCdGgEY0C .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-TlaeuXZZCdGgEY0C .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-TlaeuXZZCdGgEY0C .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-TlaeuXZZCdGgEY0C .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster text{fill:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C .cluster span{color:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-TlaeuXZZCdGgEY0C .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-TlaeuXZZCdGgEY0C rect.text{fill:none;stroke-width:0;}#mermaid-svg-TlaeuXZZCdGgEY0C .icon-shape,#mermaid-svg-TlaeuXZZCdGgEY0C .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-TlaeuXZZCdGgEY0C .icon-shape p,#mermaid-svg-TlaeuXZZCdGgEY0C .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-TlaeuXZZCdGgEY0C .icon-shape .label rect,#mermaid-svg-TlaeuXZZCdGgEY0C .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-TlaeuXZZCdGgEY0C .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-TlaeuXZZCdGgEY0C .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-TlaeuXZZCdGgEY0C :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

质量差距

差 Body 三步曲看日志找错误报告

Agent 无所适从不知道用什么命令

好 Body 六层结构触发步骤陷阱验证

Agent 照步骤执行避坑且可验证

4.2 好的 Body

# Log Analysis

## Overview
Systematic approach to server log analysis for production troubleshooting.
Covers error extraction, pattern identification, statistical analysis,
and root cause investigation for high-volume log environments.

## When to Use
– Server logs show repeated errors or exceptions
– Need to identify root cause of a production incident
– Log volume suddenly increases abnormally

## Procedure
### Step 1: Identify the log file
```bash
ls -lh /var/log/myapp/app.log*

Step 2: Extract error lines

grep -E '(ERROR|FATAL)' /var/log/myapp/app.log

Pitfalls

Log rotation: check app.log.1 if app.log is small

Timezone: logs may use UTC, not local time

Large files: use wc -l before opening

Verification

Error count matches statistical summary
Time range filter is correct

—

## 本篇小结

—

## 下篇预告

下一篇将讲解技能的辅助文件体系——references / templates / scripts / assets 四大目录的用途和管理方式。这是 Progressive Disclosure Level 2 的物理载体。

—

> 如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。

第14篇-Body正文结构规范-从When-to-Use到Verification

【Skills 系统从入门到精通】第 14 篇：Body 正文结构规范——从 When to Use 到 Verification

本篇你将学到

一、六层标准结构

1.1 结构总览

1.2 章节的 Progressive Disclosure 映射

二、各章节写作规范

2.1 Overview（概述）

2.2 When to Use（触发条件）

2.3 Procedure（操作步骤）

Step 2: Extract error lines

Step 3: Statistical analysis

2.4 Pitfalls（陷阱）

2.5 Verification（验证步骤）

2.6 References（辅助文件引用）

三、代码块规范

3.1 必须标注语言

❌ 错误——没有语言标签

❌ 伪代码

4.2 好的 Body

Step 2: Extract error lines

Pitfalls

Verification

相关推荐

评论抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

【Skills 系统从入门到精通】第 14 篇：Body 正文结构规范——从 When to Use 到 Verification

本篇你将学到

一、六层标准结构

1.1 结构总览

1.2 章节的 Progressive Disclosure 映射

二、各章节写作规范

2.1 Overview（概述）

2.2 When to Use（触发条件）

2.3 Procedure（操作步骤）

Step 2: Extract error lines

Step 3: Statistical analysis

2.4 Pitfalls（陷阱）

2.5 Verification（验证步骤）

2.6 References（辅助文件引用）

三、代码块规范

3.1 必须标注语言

❌ 错误——没有语言标签

❌ 伪代码

4.2 好的 Body

Step 2: Extract error lines

Pitfalls

Verification

相关推荐

评论 抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

评论抢沙发