SKILL.md 是什么？文件结构和作用详解

直接答案

PromptHub 将 SKILL.md 作为 Agent Skill 的主要说明文件来识别和展示，它用于描述 Skill 的名称、用途、触发场景和执行方法。Agent 通常先依据它判断是否应该使用该 Skill，再读取引用的脚本、模板或参考资料；能力库会在可用时展示原始来源，帮助用户核对真实内容。

SKILL.md 中应该写什么

文件首先要说清“什么任务应该使用它”，其次才是具体步骤。常见内容包括名称与描述、输入要求、工作流程、输出要求、限制、安全注意事项，以及对相对路径资源的引用。

一个用于生成发布说明的 Skill，可以规定先读取 Git 变更、按功能和修复分类、排除内部信息，最后生成指定格式的 Markdown。这里的价值不是篇幅，而是任务边界和步骤足够明确。

SKILL.md 和普通 README 的区别

README 面向阅读仓库的人，通常介绍项目安装、开发和贡献方式；SKILL.md 面向执行任务的 Agent，需要使用更直接的操作说明。两者可以引用相同背景资料，但不能默认 README 自动等于可执行 Skill。

查看社区资源时，应确认链接指向具体 SKILL.md 或包含它的目录，而不是只看到仓库名称就认为其中一定有完整 Skill。

如何查看真实示例

打开 PromptHub Skill 能力库，进入某个 Skill 详情页，检查来源仓库、Skill 路径和原始文件链接。可以对比多个同类 Skill，观察它们如何描述触发条件、依赖和失败处理，但不要直接复制未理解的脚本。

常见格式错误与解决办法

Agent 无法识别时，常见原因包括文件被命名成 skill.md 或其他名称、放错目录、元数据缺失、描述没有明确任务词，以及引用了不存在的相对路径。修复时应先根据宿主文档核对命名和目录，再逐个验证引用文件。

另一个失败表现是 Agent 读取了 Skill 却执行偏题。这通常说明规则混入多个不相关任务，应拆分 Skill 或收紧适用条件。

使用限制

不同 Agent 对 frontmatter、目录结构和附加文件的约定可能不同，不能假设一份 SKILL.md 在所有平台直接通用。文件还可能包含要求执行命令或读取敏感内容的指令，使用前必须检查权限边界和来源可信度。