用途：本技能记录 Agent Skills 开放格式，用于创建、审查或编辑该格式的技能，或在智能体客户端中实现技能发现与加载。权威来源为 agentskills.io/specification，随附规范为工作快照，需最新信息时应查权威来源。
目录结构：技能是一个目录，至少含 SKILL.md；可选 scripts/、references/、assets/，本仓库新技能还要求 evals/。
SKILL.md 格式：YAML 前置元数据加 Markdown 正文。必填 name（最多 64 字符，仅小写字母、数字和连字符，不得以连字符开头或结尾，不得含连续连字符，须与父目录名一致）和 description（最多 1024 字符，说明做什么与何时使用）。可选 license、compatibility（最多 500 字符）、metadata（字符串键值映射）、allowed-tools（空格分隔的预批准工具，实验性）。正文建议含分步说明、输入输出示例、常见边界情况、gotchas；建议控制在 500 行和 5000 token 内，详细内容移至 references/。
渐进式披露：启动时加载全部技能的元数据（约 100 token），激活时加载完整 SKILL.md，资源按需加载。references/ 下每个文件不得超过 60000 字符，超出需拆分并更新 SKILL.md 中的按需加载说明。文件引用使用相对技能根目录的路径，保持一层深度。
工作流：创建或编辑前先读规范；基于真实领域知识、项目产物和观察到的失败模式编写；描述需明确适用与不适用场景，重叠时在“When not to use”中指明最近替代或前置条件；用至少三个应触发提示和两个不应触发近似提示测试边界；新技能需创建 evals/evals.json，至少五个代表性输出质量用例，含真实提示、预期结果和可观察断言。审查时校验前置元数据、字段约束、父目录与名称匹配、YAML 语法，检查描述的正负触发边界、工作流可执行性、资源引用可达性，脚本需记录依赖、安全非交互输入、清晰错误和结构化输出。本仓库还要求面向人的 README.md，含标题、Why Install This Skill、What You Get、Quick Start、Triggers、Requirements。
校验：使用 skills-ref validate ./my-skill 检查前置元数据与命名约定；本仓库另运行 ruby scripts/validate-skills.rb 检查顶层与 bundle 技能的前置元数据、支持字段、行数限制、本地链接和必需 README 章节。若 skills-ref 不可用，不得声称校验成功，应手动执行并报告等效结构检查。
限制：随附规范可能过时；客户端约定（如搜索路径）不应视为通用格式要求；第三方技能以智能体权限运行，使用前应审查来源、正文和脚本。