用途：为 Apache Magpie 框架编写新技能，或将已有技能更新到当前规范。若只是想让已有技能更精简、行为不变，官方建议改用 optimize-skill。
前置检查：先运行预检命令，需带上技能 frontmatter 中的 name 与 surface_hash，并为每个 requires_config 条目加一个 --requires：
PYTHONPATH=.apache-magpie-local python3 -m setup_preflight
--skill <name> --hash <surface_hash> [--requires <file>]...
返回 {"verdict": "ok"} 则静默继续；返回 action 则按各条 rules 处理。命令未运行成功不得当作通过，也不应手工重写检查。若项目没有 .apache-magpie.lock、.apache-magpie-local/ 或 .apache-magpie-overrides/，说明尚未初始化，需自行解析 requires_config，必要时运行 /magpie-setup config。不要无人值守运行 /magpie-setup adopt。
主要流程：
- 先收集三到五个真实调用示例，明确用户会说什么、智能体如何响应、apply 步骤是什么。
- 决定内容归属：确定性部分放 scripts/，偶发需要的 schema、表格放同级文件，逐字输出的模板放 assets/。多数技能只需小的 scripts/。
- 脚手架：python3 <framework>/skills/write-skill/scripts/init_skill.py
<skill-name> --path skills/<skill-name> - 按 conventions.md 写正文，动词优先、占位符规范、一行一句。
- 若会读取外部内容，按 security-checklist.md 的九种提示注入模式加固。
- 校验：uv run --directory tools/skill-and-tool-validator --group dev
skill-and-tool-validate - 提交前必须运行 optimize-skill：正文低于 5,000 token，description + when_to_use 低于 200。
- 发布后在真实使用中迭代，每次修复单独提交。
限制与硬性规则：每个改变状态的步骤都必须是经用户确认的提案，技能不得自行发布、编辑或推送；攻击者可控文本不得进入 gh 引号参数，使用临时文件加 -F field=@file，正文用 --body-file 而非 --body "$(cat …)"；frontmatter 必须含 license: Apache-2.0 和 capability，取值见 docs/labels-and-capabilities.md；引用的第三方内容需在 NOTICE 中署名；未通过第 7 步的技能不得发布。详细内容见 anatomy.md、conventions.md、security-checklist.md、provenance.md。