【Skills 系统从入门到精通】第 20 篇第一个实战 Skill——从需求分析到 SKILL.md 完整编写本篇你将学到什么样的任务适合做成技能判断标准从需求分析到技能创建的六步完整流程每一步的详细操作和注意事项完整实战编写一个日志分析技能创建后在新会话中验证技能的完整流程读完本篇你将独立完成第一个从零编写的实战技能。一、需求分析什么适合做成技能1.1 判断标准在动手编写之前先判断这个需求是否适合做成技能。适合的标准标准说明示例多步骤操作需要 5 步工具调用日志分析定位→提取→统计→分析反复执行你做过不止一次以后还会做每次部署前都要检查配置有固定流程步骤之间有顺序依赖先备份→再迁移→最后验证踩过坑有失败经验值得记录端口被占用导致启动失败需要领域知识不记录的话 Agent 不知道该怎么做团队特定的代码审查规范满足 2 项以上就值得做成技能。单步 一次性 查询 创意这个任务适合做成技能吗多步骤操作5步以上工具调用反复执行做过不止一次有固定流程步骤有顺序依赖踩过坑有失败经验需要领域知识不记录 Agent 不知道满足 2 项以上值得做成技能不适合做技能1.2 不适合做技能的场景单步操作一个命令就搞定的直接用 terminal一次性任务以后不会再做的不需要技能信息查询查一个事实用 Memory 或直接问创造性任务每次做法不同的创意工作二、六步编写流程2.1 流程总览步骤1确定名称与触发描述步骤2编写 When to Use步骤3编写 Procedure步骤4添加 Pitfalls 与 Verification步骤5创建技能文件步骤6新会话中验证2.2 步骤1确定名称与触发描述命名动词对象全拼不缩写小写连字符。技能名log-analysis触发描述description“Use when…” 句式核心关键词前置。description: Use when analyzing server logs. Error extraction, pattern matching, statistical analysis, root cause identification.前 57 字符检查Use when analyzing server logs. Error extraction,— 核心关键词analyzing、logs、Error都在前 57 字符内。2.3 步骤2编写 When to Use列出触发条件和反触发条件## 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 issues through log patterns - Need to extract specific error types from large log files Dont use for: - Real-time log monitoring (use monitoring tools like Grafana) - Log aggregation pipeline setup (thats infrastructure work)2.4 步骤3编写 Procedure核心部分。每个步骤必须有可执行的命令## Procedure ### Step 1: Identify the log file and format bash # Check common log locations ls -lh /var/log/ ls -lh /var/log/myapp/ # Check log rotation status ls -lh /var/log/myapp/*.log* # Count total lines (size assessment) wc -l /var/log/myapp/app.logStep 2: Extract error lines# Extract ERROR and FATAL level entriesgrep-E(ERROR|FATAL)/var/log/myapp/app.log/tmp/errors.txt# Count by error levelgrep-cERROR/tmp/errors.txtgrep-cFATAL/tmp/errors.txtStep 3: Filter by time range# Extract errors from a specific hourawk/2025-01-15 14:[0-5][0-9]//tmp/errors.txt/tmp/hourly_errors.txtStep 4: Statistical analysis# Top 10 most frequent error messagesgrepERROR/tmp/errors.txt|\seds/^\[.*\] ERROR: //|\sort|uniq-c|sort-rn|head-10# Error frequency per minute (for spike detection)grepERROR/tmp/errors.txt|\awk{print substr($2, 1, 5)}|\sort|uniq-cStep 5: Extract context around critical errors# Get 5 lines before and after each FATAL errorgrep-B5-A5FATAL/var/log/myapp/app.log### 2.5 步骤4添加 Pitfalls 和 Verification **Pitfalls来自实际踩坑经验** markdown ## Pitfalls 1. **Log rotation**: The active log may be app.log.1, not app.log. Always check ls -lh app.log* first. Fix: Check rotated/compressed logs with zcat app.log.1.gz. 2. **Timezone mismatch**: App logs often use UTC. Fix: Use date -u to check current UTC time before time filtering. 3. **Giant files**: Never cat a log file 100MB. Fix: Always use tail, head, grep for incremental processing. Check size first: ls -lh. 4. **Encoding issues**: Legacy systems may produce non-UTF8 entries. Fix: Use LANGC grep or pipe through iconv -f GBK -t UTF-8. 5. **Multi-line stack traces**: grep extracts one line at a time, breaking stack traces across multiple lines. Fix: Use grep -A 20 to capture following context lines.Verification## Verification - [ ] Error count check: total extracted errors sum of error type counts - [ ] Time range check: first/last timestamps in results match target window - [ ] No data loss: wc -l /tmp/errors.txt matches grep -c output - [ ] Cross-reference: error spike times align with known incidents2.6 步骤5创建技能文件有两种方式创建技能方式一Agent 自动创建推荐在会话中告诉 Agent 创建技能请把以下内容创建为一个名为 log-analysis 的技能 [粘贴完整的 SKILL.md 内容]Agent 使用skill_manage(actioncreate)工具创建技能。方式二手动创建文件mkdir-p~/.hermes/skills/devops/log-analysis然后使用编辑器写入 SKILL.mdvim~/.hermes/skills/devops/log-analysis/SKILL.md2.7 步骤6在新会话中验证重要当前会话的技能缓存不会更新。必须开新会话验证。/new验证一技能是否被发现/skills在技能列表中查找log-analysis。验证二斜杠命令是否可用/log-analysis 分析 /var/log/syslog 中的错误Agent 应该加载技能并按步骤执行。验证三自然语言触发是否工作/new 帮我分析系统日志里的错误模式Agent 应该自动匹配到log-analysis技能。验证四description 检查查看技能在索引中的显示hermes skills inspect log-analysis确认 description 显示正确没有被截断丢掉关键信息。Agent新会话用户Agent新会话用户new 开新会话当前会话缓存不更新skills 查看列表log-analysis 已出现斜杠命令调用加载技能按步骤执行自然语言触发测试自动匹配到技能skills inspect 检查 description显示完整无截断三、完整技能文件以下是本篇实战产出的完整 SKILL.mdlog-analysis 技能Frontmattername description versiontags category related_skillsBody 正文Overview两句话定位When to Use4 触发条件 2 反触发Procedure5 个步骤各带 bash 命令Pitfalls5 条踩坑经验Verification3 项量化验证--- name: log-analysis description: Use when analyzing server logs. Error extraction, pattern matching, statistical analysis, root cause identification. version: 1.0.0 metadata: hermes: tags: [devops, logging, troubleshooting, analysis] category: devops related_skills: [systematic-debugging] --- # Log Analysis ## Overview Systematic approach to server log analysis for production troubleshooting. Covers error extraction, pattern identification, statistical analysis, and root cause investigation. Designed for high-volume log environments where manual inspection is impractical. ## 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 issues through log patterns Dont use for: - Real-time log monitoring (use Grafana/Prometheus) - Log aggregation setup (thats infrastructure work) ## Procedure ### Step 1: Identify the log file bash ls -lh /var/log/myapp/app.log* wc -l /var/log/myapp/app.logStep 2: Extract error linesgrep-E(ERROR|FATAL)/var/log/myapp/app.log/tmp/errors.txtwc-l/tmp/errors.txtStep 3: Statistical analysisgrepERROR/tmp/errors.txt|\seds/^\[.*\] ERROR: //|\sort|uniq-c|sort-rn|head-20Step 4: Time-based analysisgrepERROR/tmp/errors.txt|\awk{print substr($2, 1, 5)}|\sort|uniq-cStep 5: Context extractiongrep-B5-A10FATAL/var/log/myapp/app.logPitfallsLog rotation: Checkapp.log.1.gzifapp.logis smallTimezone: Logs may use UTC; usedate -uto verifyLarge files: Usegrep/tail, nevercatfiles 100MBEncoding: UseLANGC grepfor non-UTF8 entriesMulti-line traces: Usegrep -A Nto capture full stack tracesVerificationError count: extracted count matches statistical sumTime range: results fall within target windowNo data loss: wc -l matches grep -c output--- ## 本篇小结 | 步骤 | 核心要点 | |------|---------| | 需求分析 | 多步骤(5)、反复执行、有固定流程、踩过坑 → 适合做技能 | | 步骤1 | name动词对象 descriptionUse when... 关键词前置 | | 步骤2 | When to Use 列出具体触发条件 可选反触发 | | 步骤3 | Procedure 每步必须有可执行命令 | | 步骤4 | Pitfalls 来自实际踩坑 Verification 可量化验证 | | 步骤5 | skill_manage(create) 或手动创建 SKILL.md 文件 | | 步骤6 | **必须开新会话验证**当前会话缓存不更新 | | 验证四步 | 技能列表→斜杠命令→自然语言→description 检查 | --- ## 下篇预告 下一篇将深入技能编写的质量标准——触发条件写作、步骤描述可执行性、陷阱列表的价值。一篇高质量的技能和低质量的技能之间差距巨大。 --- 如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。