用途：当需要创建或新增一个 skill，或重写、更新某个 skill 的 SKILL.md（结构、约定、模板）时使用本约定。
主要能力与结构约定：每个 skill 一个目录，目录名与 frontmatter 的 name 完全一致；name 仅允许小写字母、数字、连字符，不能以 - 开头或结尾，不能包含连续 --。推荐结构为 skills/<skill-name>/ 下含 SKILL.md，以及可选的 scripts/、references/、assets/。
SKILL.md：必需，frontmatter 至少包含 name 与 description。description 非空，需同时覆盖“做什么”和“何时使用”，并尽量包含用户会说出口的关键词以提升触发命中率。正文只写最短可用流程，推荐顺序为：一句话说明、Quick start、常用场景/命令（3-7 条）、输出约定、冷门参数怎么查、资源。大段背景放 references/，模板/静态文件放 assets/。
scripts/：可选。需要确定性执行或经常重复的流程优先写成可执行脚本，并在 SKILL.md 给出可复制命令。Python 脚本须使用 uv script 模式，shebang 为 #!/usr/bin/env -S uv run --script；新建用 uv init --script scripts/foo.py；依赖只在脚本头部 /// script 元数据块声明，禁止手工编辑，增删用 uv add --script ... / uv remove --script ...。CLI 参数优先用 Typer，离散可选值优先用 Enum 或 Literal；输出提示/表格优先用 rich；数据模型与校验优先用 pydantic；Typer 应用实例变量名用小写 app；仅一个 command 时优先 typer.run(main)。模块、函数与类型应含简短中文 docstring。完成后建议执行 uv run ruff check <path> 与 uv run ruff format <path>。
references/ 与 assets/：可选。references/ 放按需阅读的长资料，assets/ 放模板/静态文件；引用使用相对路径，尽量一跳可达，链接文本尽量只写文件名。
长度与自检：SKILL.md 正文推荐 < 5000 tokens，可用 token_count.py 统计。提交前自检包括目录名等于 name、frontmatter 完整、有可复制 Quick start、脚本用 ./scripts/... 直接执行、依赖只在 /// script 声明、引用清晰、token 数在建议范围内。
限制：以上为仓库约定，未提供其他平台支持、收费或效果信息。