企业官网建设流程全解析

【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 是高质量技能的最低标准。

1.2 章节的 Progressive Disclosure 映射

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

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 logsgrep-E'(ERROR|FATAL)'/var/log/myapp/app.log# With timestamps for time-based analysisgrep-E'(ERROR|FATAL)'/var/log/myapp/app.log|awk'{print $1, $2, $0}'

Step 3: Statistical analysis

Count errors by type to identify patterns:

grep'ERROR'/var/log/myapp/app.log|\grep-oP'ERROR\[\w+\]'|\sort|uniq-c|sort-rn|head-20

**差的写法：** ```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 辅助文件获取更多细节。

写作要点：

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

## 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

importre 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

❌ 伪代码

<rungrepcommandtofinderrors><count the results>

--- ## 四、好 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。

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

1. Log rotation: checkapp.log.1ifapp.logis small
2. Timezone: logs may use UTC, not local time
3. Large files: usewc -lbefore opening

Verification

• Error count matches statistical summary
• Time range filter is correct

--- ## 本篇小结 | 章节 | 目的 | 质量标准 | |------|------|---------| | Overview | 概述价值 | 100-200字，不重复 description | | When to Use | 触发条件 | 具体 bullet list + 可选反触发 | | Procedure | 操作步骤 | 编号步骤 + 可执行命令 | | Pitfalls | 已知陷阱 | 问题+原因+解决方案，来自实际经验 | | Verification | 验证方法 | 具体检查命令 + 预期结果 | | References | 辅助文件 | 说明用途 + 相对路径 | | 代码块 | 必须标注语言 | 可运行，无伪代码 | --- ## 下篇预告 下一篇将讲解技能的辅助文件体系——references / templates / scripts / assets 四大目录的用途和管理方式。这是 Progressive Disclosure Level 2 的物理载体。 --- > 如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。