SKILL.md文件：智能体开发中的核心文档规范

1. SKILL.md 文件的核心价值与定位

在Aster智能体开发体系中，SKILL.md文件扮演着至关重要的角色。这份看似简单的文档实际上是连接人类意图与机器执行能力的桥梁，其重要性不亚于软件开发中的API文档。与常规技术文档不同，SKILL.md的核心读者不是人类开发者，而是Agent智能体本身。

一份精心设计的SKILL.md能够实现三个关键目标：首先是精准的任务理解，通过结构化的元数据描述，帮助Agent快速判断何时应该触发该技能；其次是规范的操作流程，提供step-by-step的执行指南，避免Agent在复杂任务中迷失方向；最后是安全边界定义，明确哪些操作是被允许的，哪些是严格禁止的，防止意外行为发生。

在实际开发中，我们经常遇到这样的场景：一个功能完备的Agent，由于SKILL.md编写不规范，导致其要么无法正确识别使用场景，要么在执行过程中产生不可预期的行为。这就像给一个经验丰富的厨师一本模糊的菜谱，即使他厨艺高超，也难以做出符合预期的菜品。

2. 文件结构与目录规范

2.1 标准目录布局

Aster框架对技能文件的存放位置有明确的规范要求。每个技能都应该是一个独立的模块，放置在workspace/skills/目录下。建议采用以下目录结构：

code复制workspace/
  skills/
    your-skill-name/      # 技能目录，建议使用kebab-case命名
      SKILL.md            # 核心技能说明书（必需）
      scripts/            # 配套脚本目录（可选）
        your_script.py    # 执行脚本
      assets/             # 资源文件目录（可选）
        config.json       # 配置文件

这种结构设计有几点优势：首先是隔离性，每个技能的所有相关文件都封装在自己的目录中，避免交叉污染；其次是可维护性，当需要更新或删除某个技能时，只需操作对应的目录即可；最后是可扩展性，scripts和assets目录为技能提供了存放辅助文件的标准位置。

2.2 文件组成要素

SKILL.md文件由两个关键部分组成，各自承担不同的功能：

1. YAML Frontmatter（元数据区）：位于文件开头，用三个连字符（---）包裹。这部分内容会被Agent在初始扫描阶段快速读取，用于判断当前技能是否匹配用户请求。元数据区相当于技能的"身份证"，包含了最基本的识别信息。

2. Markdown正文（说明书区）：当Agent确定要使用该技能时，会详细阅读这部分内容。这里需要提供完整的操作指南，包括执行步骤、错误处理、安全规范等。说明书区就像是技能的"大脑"，指导Agent如何一步步完成任务。

这两部分的分工明确：元数据区帮助Agent快速筛选合适的技能，而正文区则确保技能被正确执行。这种分离设计既保证了效率，又确保了准确性。

3. 元数据区(YAML)编写规范

3.1 必填字段详解

元数据区包含三个核心字段，每个都有严格的格式要求：

yaml复制---
name: markdown-translator
description: 将长Markdown文档按段落切分并翻译，保持格式和术语一致性。适用于"翻译这篇Markdown文档"等请求。
allowed-tools: ["Bash", "Read", "Write"]
---

name字段是技能的唯一标识符，必须满足以下要求：

• 长度限制在1-64个字符之间
• 只能包含小写字母、数字和连字符(-)
• 强烈建议与技能目录名保持一致
• 禁止包含特定保留字如"anthropic"或"claude"

description字段是技能匹配的关键，编写时需要注意：

• 必须同时说明"做什么"和"何时用"
• 使用最