mcpField
N
normalize-skill-for-claude

normalize-skill-for-claude

github.com/ulpi-ioAgent 工作流5118 次安装9 周前更新
代码仓库

关于 normalize-skill-for-claude

面向 Claude Code 的技能，用于依据其运行机制审查和规范技能。默认先生成 DAG 计划，只有明确要求时才执行重写。

主要功能

  1. 01基于运行机制审查技能
  2. 02生成 Markdown 和 JSON DAG 计划
  3. 03检查元数据与正文
  4. 04支持按需重写技能
  5. 05提供变更后验证

适用场景

  1. 01规划 Claude Code 技能更新
  2. 02检查元数据是否符合运行机制
  3. 03精简过长的技能正文

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ulpi-io/skills --skill normalize-skill-for-claude

安装后在 Claude Code 中输入/normalize-skill-for-claude确认已加载。

附带文件references/claude-skill-runtime.md

详细介绍

每项建议都必须以 Claude Code 的运行时行为为依据，而非个人偏好。

不可妥协的规则：

  1. 在规划或重写前，先阅读 references/claude-skill-runtime.md。
  2. 默认使用 --mode plan，除非用户明确要求立即重写。
  3. 将 frontmatter 视为影响最大的部分。Claude 首先根据元数据路由技能并分配预算。
  4. 让 SKILL.md 专注于工作流。将冗长示例、框架变体和边缘情况目录移至 references/ 或 scripts/。
  5. 没有具体的运行时原因时，不要添加 context: fork、paths: 或 user-invocable: false。
  6. 绝不要给技能添加仅限 Agent 使用的 frontmatter。tools、disallowedTools、skills、initialPrompt、permissionMode、maxTurns、background、memory、isolation、color 和 mcpServers 属于 Agent，不属于技能。

为 Claude 规范化技能

输入

  • $target：技能目录或 SKILL.md 的直接路径
  • $mode：可选。plan 或 rewrite。默认为 plan

目标

生成经过 Claude Code 优化的技能，使其更易于自动调用、占用更少的提示词预算，并且执行更安全。除非用户明确要求直接重写，否则始终从创建针对该技能的 DAG 计划开始。

步骤 1：解析目标

  1. 接受技能目录或 SKILL.md 的直接路径。
  2. 规范化为技能根目录，并确认 SKILL.md 存在。
  3. 确定模式：
    • --mode rewrite 表示先规划，再在同一次运行中重写
    • 未指定模式时使用 plan
  4. 检查当前技能：
    • SKILL.md 的行数
    • 现有 frontmatter 字段
    • 是否已存在 references/、scripts/ 或 assets/
    • 该技能看起来是仅供内部使用，还是可由用户调用

成功标准：明确技能的准确根目录、目标模式、当前文件结构以及可能的重写范围。

步骤 2：加载 Claude Code 技能运行时参考

在提出任何建议前，完整阅读 references/claude-skill-runtime.md。

从参考文档中提取以下约束：

  • Claude 会优先根据 frontmatter 和简短描述来分配技能发现预算。
  • 完整技能正文会在调用时加载，而非列出技能时加载。
  • 当访问匹配的文件时，paths: 会激活条件技能。
  • context: fork 会在派生的子 Agent 中运行技能，应谨慎使用。
  • allowed-tools 应尽可能缩小到所需的最低权限范围。
  • 重写技能时，只能使用技能原生 frontmatter，不能使用 Agent 原生头部字段。

如果此代码库包含 claude-code-source/，请使用参考文档中列出的确切源文件，在重写不常见的 frontmatter 前核实边缘情况。

成功标准：每项计划中的更改都能对应到具体的 Claude 运行时行为。

步骤 3：根据 Claude 的运行时审查当前技能

使用以下清单评估目标技能：

  1. 描述和触发质量
    • description 是否说明了技能的功能、适用时机和示例触发短语？
    • when_to_use 是否缺失或不够完善？
  2. Frontmatter 完整性
    • 添加 allowed-tools、arguments、argument-hint、user-invocable、paths、context 或 agent 是否能改善运行时行为？
    • 是否存在必须移除或明确避免的仅适用于 Agent 的标头？
  3. 正文大小和结构
    • 正文是否包含了参考资料，而非核心工作流？
    • 是否有庞大的示例、重复的清单，或应放入 references/ 的特定框架章节？
    • 结构内容审查：技能是否包含路由表（任务→参考资料映射）、个性／专业知识定义、编号规则集或关卡分类？这些是高信号内联内容，不是大量示例。为每项标记 PRESERVE-INLINE 或 EXTRACT-WITH-MANDATORY-LOAD。
  4. 调用类型
    • 这是一个公开的斜杠命令、内部路由器，还是按条件启用的路径作用域辅助工具？
  5. 执行模型
    • context: fork 是否有帮助？还是会割裂工作并要求流程中途与用户交互？
  6. 确定性优化机会
    • 是否有重复的 shell 代码片段或脆弱的转换操作适合放入 scripts/？

为每个问题分类：

  • ROUTING：元数据过弱，无法自动调用
  • PROMPT：正文过长或冗余
  • SAFETY：工具范围或执行模式过于宽泛
  • STRUCTURE：应提取参考资料或脚本

成功标准：提供具体且有来源依据的审查，说明必须修改的内容及原因。

步骤 4：编写每项技能的 DAG 计划

创建以下两个文件：

  • .ulpi/plans/skills/<skill-name>-normalize-for-claude.md
  • .ulpi/plans/skills/<skill-name>-normalize-for-claude.json

计划必须包含：

  1. 当前状态
    • 行数
    • 现有 frontmatter
    • 当前文件夹
    • 最大的臃肿内容区域
  2. Claude 运行时审查结果
    • 将每项发现关联到 references/claude-skill-runtime.md 中的来源引用
  3. 目标状态
    • 最终 frontmatter 结构
    • 要保留、改写、创建或拆分的文件
  4. DAG 任务
    • 重写 frontmatter
    • 精简正文
    • 提取参考资料
    • 可选的脚本提取
    • 验证
  5. 护栏
    • 不得更改的内容
    • 不得过度自动化的内容
  6. 验证
    • 用于确认技能结构健全的具体命令或检查

每项 DAG 任务都应包含：

  • id
  • title
  • rationale
  • filesToModify
  • filesToCreate
  • dependencies
  • validation

成功标准：Markdown 和 JSON 计划描述相同的工作，并且可安全执行。

步骤 5：仅在用户要求时重写

如果模式为 plan，完成 DAG 产物后即停止。

如果模式为 rewrite：

  1. 先重写 frontmatter。
  2. 正文聚焦于：
    • 输入
    • 目标
    • 工作流步骤
    • 护栏
    • 输出约定
  3. 将大篇幅内容移至 references/，但要遵守内容分类：
    • 大篇幅内容（移至参考资料）：巨型示例、框架变体、边缘案例目录、冗长清单、前后代码示例
    • 结构性内容（保留在正文中，或提取并附带强制加载指令）：路由表（任务→参考资料映射）、EXTREMELY-IMPORTANT 中的编号护栏规则、门槛分类（BLOCK/CONCERN/OBSERVATION）、个性/专业知识章节
    • 将任务类型映射到参考文件的路由表必须保留在正文中——它们是技能的主要导航界面。
    • 具体的护栏列表（编号规则、始终/绝不）必须保留在 EXTREMELY-IMPORTANT 区块中，或在需要它们的步骤中添加强制加载指令——不能只用“参见参考资料”这种非强制提示。
    • 将个性/专业知识提取到参考文件时，必须在会话开始时添加强制加载指令，而不能只在“何时加载参考资料”中提及。
  4. 只有在确实需要确定性、重复逻辑时才创建 scripts/。
  5. 保持生成的 SKILL.md 简洁，便于后续编辑。

优先考虑以下重写结果：

  • description 和 when_to_use 改为以触发条件为导向
  • 内部路由技能设为 user-invocable: false
  • 只有在按文件触发确实有帮助时，领域技能才添加 paths:
  • 只有在工作流是独立的分析/研究流程时，才使用 context: fork
  • 重写后的技能中不引入仅供 Agent 使用的标题

成功标准：重写后的技能在结构上更精简、路由更清晰，并且符合 Claude 的运行时行为。

步骤 6：验证结果

规划或重写后：

  1. 重新阅读最终的 SKILL.md。
  2. 确认正文没有重复参考文件的内容。
  3. 确认 frontmatter 字段经过有意选择，而非盲目照搬。
  4. 确认没有引入仅供 Agent 使用的标题。
  5. 确认 references/ 中的每个文件都由 SKILL.md 直接链接。
  6. 确认没有删除路由表、编号护栏规则或门槛分类，除非已提供替代内容。
  7. 确认计划或重写摘要指出了推动主要决策的 Claude 源锚点。

成功标准：人类或后续 Agent 无需猜测即可立即使用输出。

输出约定

始终报告：

  1. Skill: 目标路径和规范化根目录
  2. Mode: plan 或 rewrite
  3. Top runtime issues: 最重要的 Claude 不匹配项
  4. Artifacts: 计划或重写文件的确切路径
  5. Guardrails applied: 3 至 5 条与 Claude 运行时行为相关的要点

如果使用了重写模式，还需报告：

  • 哪些章节移至 references/
  • 添加、移除或有意省略了哪些 frontmatter 字段

评论

支持 Markdown