ccf-skill-forger

CCF Skill Forger

家族文件约定

开始处理文件前，复用规范路径，并为每项任务／产物使用一个工作目录；默认使用项目根目录下的 ccfa-workfiles/<purpose>/<artifact-id>/。在原处更新，保留输入，并使用 UTF-8，同时检查中文文本。命名、所有权和任务创建文件的清理须遵循 artifact-contracts.md；交接时沿用这些路径。

协作约定

在专家开始执行前，先阅读并应用 ccf-humanization，然后阅读并应用 ccf-common。每次交接时，复用其中适用的有效规则，或刷新缺失／变更的规则。即使没有 prose，也必须完成这两项预检；仅在相关时才启用详细编辑、实验和维护模式。

整合必要的专家贡献，并由一个负责人统一负责；复用有效的前置成果，并验证受影响的结果。遵循协作路由，避免重复报告。

调用控制

CCFA 交接模式：PARTIAL（推荐）。 维护 CCFA 技能家族时，遵循 metadata.ccf_skill_controls.handoff_question_mode 和 ../ccf-common/references/handoff-modes.md。

维护 CCFA 技能家族时，在每个 SKILL.md 中保留 metadata.ccf_skill_controls。添加同级技能间的转换前，须先检查 ../ccf-common/references/routing.md、../ccf-common/references/task-modes.md、../ccf-common/references/handoff-modes.md，以及遵循拒绝名单的回退方案。

如果用户禁用某项技能或要求仅执行写作，则应将这一边界直接写入编辑后的技能说明。除非用户明确要求更改此策略，否则不要弱化写作技能中的构想范围保护。

添加来源时，应更新 ../ccf-common/references/source-registry.yaml，而不是在同级技能中重复 URL 列表。添加浏览或证据规则时，确保其与 ../ccf-common/references/privacy-and-evidence.md 保持一致。

绝不要在技能、README 文件、来源注册表、图表、示例、脚本或命令片段中提交特定于机器的绝对路径、用户名、展开后的主目录路径或私有本地目录名。请使用 $CODEX_HOME、$HOME、相对于仓库的路径，或不会暴露用户或机器身份的占位符。

核心规则

将技能编写为供另一个 Codex 会话使用的精简操作指南。让 SKILL.md 聚焦于与触发条件相关的工作流、决策和资源导航。将详细示例、检查清单、架构、策略文本或长篇说明放入 references/，并仅在需要时加载。本技能也负责 CCFA 文档 SVG 图表；不要为仓库架构或工作流图表另建运行时绘图技能。

工作流

1. 通过具体示例明确目标。如果用户的意图清晰，就基于合理假设继续。仅在缺少的信息会改变技能的范围、位置或所需资源时才提问。
2. 选择技能名称和目标位置。只能使用小写字母、数字和连字符；名称须少于 64 个字符；检查目标技能目录中是否存在名称冲突。默认使用 $CODEX_HOME/skills；如果未设置，则使用 ~/.codex/skills。
3. 确定资源结构：
   • 对于简短且稳定的流程指导，只使用 SKILL.md。
   • 添加 references/，用于存放 Codex 应有选择地阅读的详细文档。
   • 仅在可重复的确定性操作或脆弱的命令序列需要时，添加 scripts/。
   • 仅在最终输出会用到模板、图像、样板文件或其他文件时，添加 assets/。
4. 从零开始创建技能时，先初始化。若有本地 skill-creator 初始化工具，优先使用：

python '<skill-creator-dir>/scripts/init_skill.py' <skill-name> --path '<skills-dir>' --resources references,scripts

5. 先编写 SKILL.md，再填充可选资源。将所有“何时使用”触发描述放在 YAML description 中；只有触发选择完成后才会加载正文。在共享任务模式中，将功能命名规则应用于方法介绍和报告标题，同时保留源记录和叙述内容。使用祈使式指令，避免面向用户的教程式文字。
6. 添加能直接支持该技能的资源。移除占位文件和未使用的目录。通过在小型、有代表性的示例上运行脚本来测试脚本。
7. 使用现有的系列检查验证变更后的行为和结构。对比 SKILL.md、Agent 提示词、注册表、共享规则和文档，检查是否存在冲突。检查实际的 YAML 元数据、现有脚本的语法、资源依赖项和有代表性的任务边界；区分静态检查与实际模型评估。保留公开路径和命令兼容性。如果用户将工作限制在现有范围内，不要添加新文件、依赖项或评估。
8. 完成 CCFA 系列维护前，运行 ccf-common/scripts/check_path_privacy.py。将提交内容中的本地绝对路径或用户名替换为 $CODEX_HOME、$HOME、相对于仓库的路径或不含身份信息的占位符。
9. 对于 CCFA 文档中的图示，请在 CCFA 仓库检出目录中操作，并更新其中的 tools/build_ccfa_diagrams.py，重新生成所有语言版本，并对渲染出的 SVG 输出进行截图检查。使用 references/svg-style-guide.md；除非将同一变更回补到生成器，否则不要手动编辑生成的 SVG。

进行模型适配时，应使用当前官方指南，并将其来源记录在现有来源注册表中。添加新指令前，先移除相互冲突或重复的指令。模型设置和仅限 API 的能力应由宿主负责；不要在每项技能中硬编码模型，也不要在缺少有代表性的比较时声称效果有所提升。

在获准维护期间进行可选规则迭代时，应采用 Common 偏好中的 maintenance_evolution，并遵循 references/design-checklist.md 中限定范围的候选方案流程。即使关闭该流程，必需的修复及其检查仍须执行。采用固定的验收标准，最多比较一个额外候选方案，保留可用的基线，并将变更限制在任务涉及的文件内；研究任务不会触发技能自我编辑。

参考文件

仅在任务需要时加载以下文件：

• references/design-checklist.md：规划新技能、审查结构，或判断内容应放在 SKILL.md、references/、scripts/ 还是 assets/ 中时使用。
• references/patterns.md：撰写具体的 SKILL.md 结构、前置元数据描述或示例驱动工作流时使用。
• references/local-commands.md：在此机器上搭建或验证技能时使用，尤其适用于 PowerShell 或 Windows 路径。
• references/svg-style-guide.md：维护 CCFA 架构、工作流、路由、安装、产物、目录或演示用 SVG 图示时使用。

输出风格

使用已获批准的方案，无需再次确认。对于明确要求仅提供计划的请求，在提交可供审核的方案后停止；对于已授权的维护工作，在指定的现有文件中实施。创建完成后，报告技能名称、位置、关键文件和验证结果。如果因缺少本地依赖而无法运行验证，请准确说明失败原因，并执行 references/design-checklist.md 中的手动检查。