zhouyilab-skill-maintenance

规范维护与生成

• skills/<name>/SKILL.md 是规范源，skills/manifest.json 指定聚合顺序；根目录 AGENTS.md 是生成产物，不直接编辑，不把历史报告或全部聊天记录塞入规范。
• 各 skill 的 name 与目录一致，使用小写字母、数字、连字符，不超过 64 字符；description 说明适用任务。元信息只使用单行 name/description（可使用双引号字符串），正文使用二级及以下标题。
• 按职责维护一处规则，其他 skill 只说明自己的应用边界。架构、领域、编码、展示、测试、构建分别归目录；新增规范必须能改变实际决策，不堆泛泛口号。
• 模块使用说明写清楚“怎么排盘、参数怎么传、结果里有什么、怎么输出、改功能去哪里”。代码和详细说明放在 references/usage.md，SKILL.md 告诉读者该看哪份说明。用项目里的具体说法，不套“最小调用、消费结果”等模板，也不要每份都重复一段维护须知。
• 聚合只纳入入口正文，不展开参考文档。入口使用 [说明](references/文件.md) 链接，生成器检查参考文件并改写为根目录可解析的路径；不要将参考路径写成当前机器绝对路径。
• 新增目录同时更新清单。当前聚合器只收录清单中的直属 skill，发现遗漏直接失败；不递归拼接第三方文档，不将依赖或参考文章当作代理指令。
• 在仓库根运行 python skills/zhouyilab-skill-maintenance/scripts/generate_agents.py 生成，再运行同一命令加 --check 验证一致性。脚本相对自身定位仓库，也可从其他目录用绝对路径执行。
• 修改脚本后运行 python -B -m unittest discover -s skills/zhouyilab-skill-maintenance/scripts -p "test_*.py" -v。测试在临时仓库验证确定性、清单校验、越界拒绝、漂移检测和非生成文件保护，不改真实规范。
• 生成器使用标准库，无需额外安装；不要在生成时下载工具、安装全局 skill、修改 Git 设置、自动提交或推送。若已有非生成 AGENTS.md，先人工读取迁移有效要求到相应 skill，再经用户确认处理旧文件，不能强制覆盖。