创建、改写、优化或审计 AgentSkills 技能目录。Use when: 从零创建新技能、重写现有 SKILL.md、整理 skill 目录结构、补充 references/scripts/assets、清理陈旧内容、按 AgentSkills 规范做快速校验或打包。触发词：osc、osc触发词、创建技能、编写技能、优化技能、整理技能、审计技能、重构技能目录。
equipped with procedural knowledge that no model can fully possess.
用于创建高质量技能，并在已有技能需要中文化、结构整理、规范修复或可分发打包时提供统一流程。
技能是可复用、可分发、可渐进加载的能力包。它通过工作流、领域知识、脚本和参考资料，让通用代理在特定任务上具备稳定执行能力。
本技能的目标不是“随便写一个 SKILL.md”，而是产出一个：
可以把 Skill 理解为“给另一个代理准备的上岗手册 + 工具包”。
它通常提供以下价值：
上下文窗口是共享资源。Skill 要和系统提示、对话历史、其他技能元数据以及当前用户请求共同占用上下文。
默认假设：模型本身已经足够聪明。只补它“不知道但任务需要”的内容。
写每一段前都先判断：
优先使用：
避免：
不同技能对“约束强度”的要求不同：
判断标准很简单：
每个技能至少包含一个 SKILL.md，可按需附加配套资源：
skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md 由两部分构成：
name 和 description，这是技能触发的主入口因此：
description适合放确定性要求高、会反复复写、适合直接执行的代码。
典型场景：
适合放需要按需加载的说明性资料，例如：
原则：
适合放不会直接读入上下文、但会被最终产物使用的文件，例如模板、图片、图标、字体、样板项目。
除非任务明确要求，否则不要给技能目录额外增加以下噪音文件：
技能目录只保留对代理执行任务真正有帮助的内容。
技能的理想加载层级是：
name + description正文尽量控制在 500 行以内。接近上限时，把变体细节拆到 references/ 中，并在正文明确写出：
init_skill.pyquick_validate.py 做快速校验package_skill.py 打包成 .skill如果只是修已有技能，可以跳过初始化，直接进入编辑与验证。
Plan Mode -> plan-mode除非你对目标技能已经非常明确，否则不要跳过这一步。
创建技能前，要先弄清楚：用户会怎么提这个需求、希望技能做什么、哪些说法应该触发技能。
例如你在做一个图片编辑技能，至少要澄清：
提问时不要一口气问太多，优先问最影响技能边界和触发条件的问题。
这一步的退出条件：已经能列出清晰的典型输入与触发范围。
把具体样例转成资源规划清单：
scripts/references/assets/判断方式：先想“如果我从零执行这个任务，哪些内容下次还会重复需要？”
例如：
pdf-editor 经常要写相同的旋转脚本，就该沉淀到 scripts/rotate_pdf.pyfrontend-builder 总要起同一套前端脚手架，就该把模板项目放进 assets/big-query 总要重新摸表结构，就该把 schema 写进 references/schema.md从零创建技能时，优先运行 scripts/init_skill.py，不要手写初始骨架。
命令：
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
示例：
scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
它会：
如果目标技能目录已经存在，这一步可以跳过。
编辑时要始终记住：这个技能是写给“另一个代理”用的，不是写给人看的教程。
应该优先补：
通常先处理 scripts/、references/、assets/，再回头写 SKILL.md，会更清楚需要怎样导航和引用。
如果创建了示例文件，最后记得：
新增脚本后，必须实际运行验证，不要只写不测。
只写：
namedescription其中 description 要同时说明：
不要把“适用场景”只写在正文里。
正文尽量用祈使句/动作导向表达，重点包含：
开发完成后，用 scripts/package_skill.py 生成可分发的 .skill 文件：
scripts/package_skill.py <path/to/skill-folder>
scripts/package_skill.py <path/to/skill-folder> ./dist
打包前会自动校验：
如果校验失败，先修复再打包。
安全规则：目录中若存在符号链接，打包会拒绝或跳过，避免把 skill 根目录之外的内容带进去。
技能上线后，最有价值的改进往往来自真实使用反馈：
scripts/init_skill.py：初始化技能骨架scripts/quick_validate.py：做快速结构校验scripts/package_skill.py：校验后打包为 .skill如果是改造已有技能，通常至少要跑一次快速校验；如果要交付分发，则必须完成打包验证。
quick_validate.py 校验通过.skill 打包成功