第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 是高质量技能的最低标准。技能标题Overview是什么 为什么When to Use什么时候用Procedure怎么做Pitfalls注意什么Verification怎么确认成功References去哪找更多1.2 章节的 Progressive Disclosure 映射Body 的章节结构也体现了 Progressive Disclosure 的思想Level 0descriptionLevel 1 前两节Overview When to Use判断是否匹配Level 1 核心Procedure Pitfalls VerificationLevel 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 Dont use for: - Real-time log streaming (use monitoring tools instead) - Log aggregation setup (thats 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 linesExtract 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 analysisCount errors by type to identify patterns:grepERROR/var/log/myapp/app.log|\grep-oPERROR\[\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 LANGC 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 timestamps2.6 References辅助文件引用目的引导 Agent 到 Level 2 辅助文件获取更多细节。写作要点说明每个文件的内容和用途使用相对路径只在当前任务需要时才加载辅助文件SKILL.md 正文Agent辅助文件SKILL.md 正文AgentLevel 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.logimportre patternr\[(\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❌ 伪代码rungrepcommandtofinderrorscount 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。质量差距差 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 linesgrep-E(ERROR|FATAL)/var/log/myapp/app.logPitfallsLog rotation: checkapp.log.1ifapp.logis smallTimezone: logs may use UTC, not local timeLarge files: usewc -lbefore openingVerificationError count matches statistical summaryTime 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 的物理载体。 --- 如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。