用途与定位 该技能面向需要创建或改进 Agent Skills 的作者。技能是一个包含 SKILL.md 的文件夹，用于向 AI 智能体提供特定任务的专业知识、工作流或工具。该开放标准已被 30 多个智能体产品采用，包括 Claude Code、OpenAI Codex、Cursor、Gemini CLI、VS Code Copilot、GitHub Copilot、Junie、Goose、Roo Code 等；标准维护于 agentskills.io，源码位于 github.com/agentskills/agentskills。技能解决的问题是智能体缺乏程序性知识和领域上下文，技能以可移植、可版本控制的格式打包这些知识。
目录结构 最小可用技能仅需一个 SKILL.md。完整结构可包含：scripts/ 存放智能体可直接执行、无需载入上下文的确定性代码；references/ 存放按需阅读的文档，文件应聚焦且从 SKILL.md 只深一层；assets/ 存放输出中使用的模板、图片、字体等静态资源，不载入上下文；agents/openai.yaml 为展示技能列表的平台提供界面元数据。
SKILL.md 格式 SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。必填字段：name（最多 64 字符，仅小写字母、数字和连字符，不得有首尾或连续连字符，且必须与目录名一致）、description（最多 1024 字符，非空，说明做什么和何时使用）。可选字段：license、compatibility（最多 500 字符，描述环境要求）、metadata（任意键值映射）、allowed-tools（空格分隔的预批准工具列表，实验性）。正文无格式限制，建议包含分步工作流、输入输出示例、常见边界情况与错误处理、对捆绑文件的引用及阅读时机说明。
描述与渐进式披露 description 是触发机制：智能体启动时只加载所有已安装技能的 name 和 description，任务匹配时才激活完整 SKILL.md，因此描述不佳会导致技能从不触发。规则包括同时写明做什么和何时使用、包含有助于匹配的具体关键词、把所有触发信息放在描述而非正文中、控制在 1024 字符内。该仓库采用更严格的 250 字符上限，以适应 Codex 的共享发现上下文，应视为硬上限而非目标长度。技能采用三级加载：元数据约 100 tokens 在启动时加载；指令建议少于 5000 tokens，激活时加载；scripts/、references/、assets/ 中的资源按需加载。建议 SKILL.md 控制在 300 行和 24000 字符以内，超出会触发提示警告。大参考文件（100 行以上）顶部加目录，超大文件（1 万词以上）在 SKILL.md 中给出 grep 搜索模式，文件引用保持一层深度。
捆绑资源与界面元数据 当同一代码会被反复重写或需要确定性可靠性时使用 scripts/；当智能体工作中需要查阅 schema、API 文档、领域知识、政策或工作流指南时使用 references/，同一信息不应同时存在于 SKILL.md 和参考文件中；输出中出现的模板、图片、图标、字体、样板代码放入 assets/。agents/openai.yaml 提供界面元数据，最小示例包含 interface 下的 display_name、short_description、default_prompt；可选字段（如图标、brand_color）仅在明确提供时加入。
仓库约定与命名 本仓库技能另遵循一些模式：多技能定义编号工作流、结构化输出契约（如严重级别与必填章节）、质量标准和反模式章节、用 references/ 存放定义与命名护栏、检查可选仓库基础设施并跳过缺失步骤；遵循 docs/MARKDOWN_STYLE.md（句首大写标题、仅 ASCII、- 作为项目符号）和 docs/REPO_STYLE.md（references 中小写加下划线文件名、Markdown 文档用全大写下划线）。命名规则：仅小写字母、数字和连字符，最多 64 字符，无首尾或连续连字符，必须与父目录名完全一致；优先使用简短的动词开头短语，必要时按工具加命名空间。
不应包含的内容与检查清单 技能文件夹只应包含直接支持智能体任务的文件，不要创建 README.md、CHANGELOG.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、面向用户的文档或安装测试流程；例外是智能体按需阅读的 references/ 文件。发布前检查：SKILL.md 存在且 frontmatter 有效；name 与目录名一致并符合字符规则；description 非空、不超过 1024 字符且包含做什么和何时用；SKILL.md 在 300 行和 24000 字符以内或有记录理由的警告豁免；所有引用文件存在且路径为相对路径、引用一层深度；大参考文件有目录；SKILL.md 与参考文件无重复信息；无辅助文档；agents/openai.yaml 包含三个必需字段；内容仅 ASCII。进一步阅读包括 agentskills.io/specification、agentskills.io/what-are-skills 以及 references/SPEC_QUICK_REFERENCE.md。在 delegate-manager-to-subagents 下，该技能被分配给一个全新子智能体，配一个受控任务、相关仓库规则和一个验证步骤；不要跨无关后续工作复用同一子智能体，每个原子任务分派新子智能体。