AI Agent 技能能否精准触发、稳定执行、规模化复用，核心不在于复杂的 prompt 话术，而在于标准化的 SKILL.md 文件规范。
很多开发者遇到的技能不触发、误触发、执行混乱、输出不统一等问题，本质都是 SKILL.md 结构不规范、元数据配置错误、技能描述模糊导致的。
本文将系统性拆解 SKILL.md 完整文件架构、所有元数据字段规范、正文指令编写标准，同时深度解析 Description 核心编写逻辑与实战技巧，附带可直接复用的生产级模板，帮助开发者从零写出高触发、低误触、可落地、可复用的专业 AI 技能。
一、SKILL.md 核心架构：双段式标准结构
SKILL.md 是 AI Agent 技能的唯一核心载体，所有自定义技能、预制技能都遵循统一的双段式架构，分为YAML 元数据区（头部） 和Markdown 指令执行区（正文） ，两段各司其职、互不干扰。
- YAML 元数据区：定义技能身份、触发规则、基础属性，供 Agent 启动扫描、智能匹配使用
- Markdown 指令区：定义技能执行流程、场景边界、输入输出规范，供 Agent 实际任务执行使用
1.1 最简可用模板（入门必备）
满足基础技能开发需求，仅保留必填字段，轻量化、零冗余，适合简单单一场景技能：
---
name: your-skill-name
description: 功能说明 + 使用场景 + 触发关键词
---
# 技能名称
## 操作步骤
1. 步骤一
2. 步骤二
## 示例
输入：xxx
输出：xxx
1.2 全量字段详解（生产级规范）
完整支持所有拓展字段，适配企业级复杂技能开发，所有字段的填写规则、约束、用途如下：
| 字段名称 | 是否必填 | 长度与格式约束 | 核心作用 |
|---|---|---|---|
| name | 是 | 1–64 字符，仅小写字母、数字、连字符 | 技能唯一标识，用于系统识别与目录绑定 |
| description | 是 | 1–1024 字符，需包含功能、场景、关键词 | Agent 匹配触发的核心依据，决定技能准确率 |
| license | 否 | 自定义协议标识 | 定义技能开源协议与版权规范 |
| compatibility | 否 | ≤500 字符 | 标注运行环境、依赖版本、兼容性要求 |
| metadata | 否 | 自定义键值对格式 | 存储作者、版本、标签等拓展信息 |
| allowed-tools | 否 | 工具列表数组 | 限定技能可调用工具（实验性特性） |
二、YAML 元数据：精准编写规范（避坑核心）
元数据是技能的“身份证”，Agent 在发现阶段仅加载元数据，元数据不规范会直接导致技能不识别、不触发、误触发。
2.1 Name 字段：唯一标识规范
name 是技能的唯一身份 ID，核心遵循强绑定原则：
- 必须与技能文件夹名称完全一致，大小写、字符无差异
- 禁止大写字母、空格、特殊符号、首尾连字符、连续连字符
- 命名建议采用「动名词+场景」格式，见名知意，便于管理
✅ 规范示例：pdf-processing、data-analysis、code-review
❌ 错误示例：PDF-Handle、-excel-analysis、data--chart
2.2 Description 字段：技能触发的核心命脉
Description 是整个 SKILL.md 中最重要的字段，直接决定：技能是否被匹配、是否精准触发、是否与其他技能冲突。
在 Agent 三阶段加载机制中，发现阶段仅读取 name 和 description，所有触发逻辑完全依赖该字段。
高质量 Description 必备三要素
- 明确功能：清晰说明技能能实现什么具体能力，不写空泛话术
- 界定场景：明确适用的业务场景与使用时机
- 覆盖关键词：包含用户日常提问的高频触发词
实战标准示例
从 PDF 提取文本与表格、填写表单、合并多文档；用户提及 PDF、提取、表单、合并文档时使用
三、Markdown 指令区：标准化执行正文写法
当 Agent 匹配并激活技能后，会完整加载 Markdown 正文，严格按照定义流程执行任务。正文的清晰度、完整性、边界约束，直接决定技能执行稳定性。
3.1 通用标准正文结构
所有生产级技能统一遵循以下结构，保证逻辑统一、AI 执行无歧义：
# 技能名称
## 功能说明
简要说明技能核心用途、解决的问题与核心价值
## 适用场景
罗列所有典型使用场景，明确触发边界
## 执行步骤
1. 步骤清晰、可落地、无歧义
2. 有序分步执行，包含约束条件
3. 明确输入要求与输出规则
## 输入输出示例
输入：真实用户指令案例
输出：标准化结果格式
## 注意事项
功能限制、环境依赖、权限要求、禁忌场景
3.2 正文编写核心要点
- 执行步骤必须具体、可落地，杜绝模糊描述，避免 AI 自由发挥
- 明确场景边界，写明「能做什么、不能做什么」，减少执行错误
- 控制整体 Token 长度，单技能正文建议 ≤5000 tokens
- 复杂参考资料、超长配置禁止塞入正文，统一放入
references/目录解耦
四、Description 高级优化：告别误触、漏触、错触
大部分技能故障都源于 Description 编写不规范，掌握高级写法，可大幅提升技能触发精准度。
4.1 Description 四大核心价值
- 控制触发逻辑：精准匹配需求，避免漏触发、不触发
- 区分相似技能：解决同类技能抢占、错激活问题
- 优化资源消耗">精准匹配减少无效加载，节省 Token 资源
- 统一执行逻辑">让 Agent 对场景判断形成统一认知
4.2 四步快速写出高质量描述
- 写实功能：拒绝空话，精准描述核心能力
- 覆盖场景：罗列 2-5 个高频适用场景
- 补齐关键词：收录用户高频口语化指令
- 控制长度：简单技能 50-100 字符，复杂技能 100-400 字符
4.3 优劣写法直观对比
❌ 劣质写法（模糊、无边界、低触发）：处理各类文档文件
✅ 优质写法（精准、有场景、有关键词）：处理 PDF 文档，支持提取文本表格、填写表单、合并文件；用户提及 PDF、提取、表单、合并文档时触发
4.4 常见故障排查方案
| 常见问题 | 根因 | 解决方案 |
|---|---|---|
| 技能频繁误触发 | 描述范围过于宽泛，无场景限制 | 增加场景限定、明确排除非适用场景 |
| 技能始终不触发 | 缺失用户高频关键词 | 补充口语化、高频触发关键词 |
| 相似技能互相抢占 | 描述同质化，无差异化特征 | 强化技能专属场景与独有关键词 |
五、生产级完整实战模板（可直接复用）
以下为可直接复制使用的完整 SKILL.md 模板，规范齐全、边界清晰、触发精准，适配正式项目落地：
---
name: pdf-processing
description: 从 PDF 提取文本与表格、填写表单、合并多文档；用户提及 PDF、提取、表单、合并文档时使用
license: Apache-2.0
metadata:
author: ai-engineer
version: 1.0.0
---
# PDF 处理技能
## 功能说明
专注于 PDF 文档自动化处理，实现文本表格提取、表单填充、多文件合并，标准化输出文档处理结果
## 适用场景
- 提取 PDF 文本、表格数据
- 批量填写 PDF 表单字段
- 合并多个 PDF 文档文件
## 执行步骤
1. 优先使用 pdfplumber 提取常规 PDF 文本与表格数据
2. 识别扫描版 PDF，自动启用 OCR 文字识别
3. 根据用户需求精准填写 PDF 表单字段，生成新文档
4. 按文件顺序批量合并多份 PDF 文件
5. 整理处理结果，输出标准化文件并告知存储路径
## 输入输出示例
输入：提取 report.pdf 中的表格数据
输出：将 PDF 表格数据整理为标准 Markdown / CSV 格式并输出
## 注意事项
- 仅支持 PDF 文档处理，不解析图片、视频、压缩包等文件
- 运行依赖：pdfplumber、pytesseract 环境库
- 不处理加密、权限受限的受保护 PDF 文件
六、全文核心总结
SKILL.md 是 AI Agent 技能工程化的核心载体，告别随意写提示词的开发模式，标准化规范是技能稳定落地的关键：
- 结构固定：YAML 元数据负责匹配触发，Markdown 正文负责执行落地，分工清晰
- 字段从严：Name 保证唯一规范，Description 决定技能精准度，是重中之重
- 正文可控：步骤无歧义、场景有边界、示例标准化，杜绝 AI 随机输出
- 轻量化原则：核心逻辑留在主文件，冗余资源外置，保证技能高效加载运行
严格遵循这套开发规范，即可写出适配多平台、可复用、可维护、零故障的生产级 AI 技能。
参考链接
-
SKILL.md 文件结构规范：www.runoob.com/skills/skil…
-
技能 Description 编写规范：www.runoob.com/skills/skil…
