1. 项目概述SKILL.md标准化构建的意义在智能体开发领域我们正面临一个关键转折点。随着AI能力的快速演进单纯依靠模型本身的泛化能力已经难以满足复杂场景的需求。就像给新手程序员开放服务器root权限却不提供操作手册结果往往事与愿违。SKILL.md的标准化构建正是为了解决这个核心矛盾。它本质上是一种上下文工程实践通过结构化文档将领域知识、操作规范和最佳实践封装成智能体可理解、可执行的格式。这种标准化带来的价值体现在三个维度技术维度解决了传统智能体开发中的上下文爆炸问题。实测数据显示直接加载完整工具定义会消耗16k以上token而通过SKILL.md的渐进式披露机制初始加载仅需约500token效率提升达97%。工程维度实现了能力定义与工具调用的解耦。MCP负责能做什么工具连接SKILL.md定义该怎么做业务逻辑这种分层架构使系统更易维护和扩展。知识维度形成了可沉淀、可复用的知识资产。一个编写良好的SKILL.md文件相当于该领域的专家操作手册能让智能体快速获得专业级的问题解决能力。2. 核心架构解析SKILL.md的三层设计2.1 元数据层YAML Frontmatter这是智能体识别和匹配技能的身份证必须包含以下关键字段--- name: database-troubleshooting # 使用kebab-case命名 description: 诊断和修复常见数据库性能问题包括 - 慢查询分析 - 索引优化建议 - 连接池配置调整 当用户反映数据库响应慢或超时时使用此技能 version: 1.2.0 allowed_tools: [mysql-cli, explain-analyzer] # 工具白名单 tags: [database, performance, mysql] ---避坑指南description字段是匹配精度的关键应该包含3-5个典型场景关键词明确的触发条件区别于其他技能的独特价值避免使用模糊表述如处理数据库问题而要具体到分析慢查询的EXPLAIN结果2.2 指令主体层Markdown内容这部分采用模块化设计建议包含以下标准章节2.2.1 工作流程规范## 诊断流程 1. **收集证据** - 使用SHOW PROCESSLIST识别阻塞会话 - 通过SHOW STATUS LIKE Threads_connected检查连接数 2. **定位瓶颈** - 对慢查询执行EXPLAIN ANALYZE - 检查innodb_buffer_pool_hit_ratio指标 3. **优化方案** - 索引缺失建议添加复合索引遵循最左前缀原则 - 连接泄漏推荐设置连接池的max_lifetime参数经验技巧使用表格对比不同场景的解决方案问题类型诊断命令优化建议风险提示锁等待SHOW ENGINE INNODB STATUS添加索引或重写查询避免长时间持有锁内存不足SHOW GLOBAL STATUS LIKE Buffer%调整innodb_buffer_pool_size需要重启实例2.2.2 反模式警示## 常见错误 ❌ 盲目添加索引 - 每个额外索引会增加5-20%的写入开销 - 优先考虑查询频率/数据选择性 10%的字段 ❌ 过度分页查询 - LIMIT 10000, 10会导致全表扫描 - 改用基于游标的分页WHERE id last_seen_id2.3 扩展资源层附加文件通过引用外部文件实现知识无限扩展skills/db-optimization/ ├── SKILL.md ├── query_samples/ # 案例库 │ ├── ecommerce.sql # 电商场景特化查询 │ └── reporting.sql # 报表优化方案 └── scripts/ ├── index_advisor.py # 自动化索引推荐 └── query_rewriter.py # SQL重写工具最佳实践大文本资源如SQL模板应放在外部文件复杂逻辑用Python脚本实现避免依赖LLM生成通过版本控制管理技能迭代3. 实战开发从零构建MySQL优化SKILL.md3.1 环境准备创建标准化的技能目录结构mkdir -p mysql-optimizer/{examples,scripts} touch mysql-optimizer/SKILL.md3.2 YAML元数据设计--- name: mysql-query-optimizer description: 提供专业的MySQL查询优化方案包括 - EXPLAIN结果解读 - 索引策略设计 - 查询重写建议 适用于执行计划不理想、全表扫描等性能问题 version: 1.0.1 required_tools: [mysql-client, pt-index-usage] tags: [database, mysql, performance] ---3.3 指令内容开发3.3.1 诊断方法论## 性能分析框架 1. **执行计划解读** - 重点关注type列 - ALL全表扫描 → 需要索引 - index全索引扫描 → 考虑覆盖索引 - range理想范围扫描 2. **关键指标** sql SELECT ROUND(100 * SUM(IF(variable_nameInnodb_buffer_pool_reads, variable_value, 0)) / SUM(IF(variable_nameInnodb_buffer_pool_read_requests, variable_value, 0)), 2) AS hit_ratio FROM performance_schema.global_status;命中率95%需扩大缓冲池#### 3.3.2 优化案例库 markdown ## 典型场景解决方案 ### 案例1订单查询优化 **原始查询** sql SELECT * FROM orders WHERE user_id123 AND statuspaid ORDER BY create_time DESC LIMIT 10;优化方案添加复合索引(user_id, status, create_time)重写为覆盖索引查询SELECT id, user_id, status, create_time FROM orders USE INDEX(composite_idx) WHERE user_id123 AND statuspaid ORDER BY create_time DESC LIMIT 10;效果对比指标优化前优化后扫描行数10,00010执行时间1200ms8ms### 3.4 脚本集成示例 创建自动化分析脚本scripts/analyze_query.py python #!/usr/bin/env python3 import sys import subprocess def explain_query(db_conf, query): cmd fmysql -h{db_conf[host]} -u{db_conf[user]} -p{db_conf[pass]} -e EXPLAIN {query} {db_conf[db]} result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) return result.stdout if __name__ __main__: query sys.argv[1] db_config {...} # 从环境变量加载 print(explain_query(db_config, query))在SKILL.md中引用## 自动化工具 对于复杂查询可调用分析脚本 python # 智能体会自动转换为工具调用 analysis run_script(analyze_query.py, querySELECT...)4. 高级技巧与避坑指南4.1 上下文管理策略问题当技能需要加载大型参考数据时如完整的SQL模式如何避免上下文爆炸解决方案分块加载技术## 数据库模式按需展开 details summary点击查看表结构/summary sql CREATE TABLE employees ( id INT PRIMARY KEY, name VARCHAR(100) NOT NULL, -- 其余字段... );动态引用外部文件## 完整模式参考 参见外部文件schema/employees.sql仅当需要详细设计时加载4.2 多技能协作模式当任务需要跨技能协作时采用技能网关设计--- name:>## CHANGELOG ### 1.1.0 (2024-03-15) - 新增分区表优化策略 - 添加InnoDB状态诊断命令 ### 1.0.2 (2024-02-28) - 修复索引推荐算法的边界条件错误5. 效能验证与持续改进5.1 效果评估指标建立技能的质量评估体系维度测量指标目标值匹配精度技能触发准确率90%执行效率平均处理时间30s资源消耗峰值token使用5k问题解决率无需人工干预比例80%5.2 A/B测试方法通过分流测试验证技能改进效果# 在智能体路由层实现 if random() 0.5: use_skill(legacy/mysql-optimizer) else: use_skill(v2/mysql-optimizer) # 对比响应时间、解决率等指标5.3 迭代优化流程建立PDCA循环Plan通过用户反馈识别优化点Do修改SKILL.md并版本升级Check监控关键指标变化Act全量发布或回滚在开发过程中我发现最影响技能效能的三个关键因素是描述字段的精准度决定匹配准确率示例的质量和数量影响执行效果异常处理的完备性决定健壮性一个反直觉的发现是增加过多的注意事项反而会降低技能效能。最佳实践是将核心注意事项放在主体部分3-5条将边缘案例处理移到高级技巧章节把非常见问题放入外部文档链接