build-cs-skill

build-cs-skill

目的

构建最精简、始终加载的控制界面，让 Agent 能够选择相关上下文、遵守硬性门槛、安全协作，并留下可恢复的证据。SKILL.md 是精简的运行框架；参考资料和仓库事实是厚重的上下文。厚重指对决策有用，而非内容庞大。

明确职责、权限、上下文选择、证据和停止条件。将安全的实现选择留给执行 Agent。

范围和参考资料

目标路径为 plugins/codestable/skills/<skill-name>/ 或 .claude/skills/<local-skill-name>/。

仅加载当前决策所需的参考资料：

• references/cs-skill-spec-standard.md：契约定义、类型化决策、恢复和输出语义。
• references/cs-skill-quality-gates.md：关于放置、上下文、演进、运行时对齐和验证安全性的审查算法。
• references/cs-skill-fixture-patterns.md：高风险路由、检查点、失败、兼容性或禁止操作场景。

规范

data SkillKind
  = OperatorSkill | WorkflowSkill | MethodologySkill | CompatibilityShim | ReferenceDoc

data SkillShape = NoActiveSkill | ThinOperator | ContextualWorkflow | ToolBackedWorkflow
                | ShimSkill | ReferenceSkill
data ProcessProtocol = WorkflowProtocol | DomainProtocol | LifecycleProtocol
                     | OperationProtocol | AlgorithmProtocol | ShimRoute | ReferenceOnly
data RulePlacement = Harness | StageContext | ProjectContext | DeterministicGate | Remove
data DelegationRole = Orchestrator | LeafExecutor

selectSkillShape :: SkillKind -> SkillSource -> SkillShape
selectSkillShape kind source | not (independentSkillNeeded kind source) = NoActiveSkill
selectSkillShape kind source =
  case kind of
    ReferenceDoc      -> ReferenceSkill
    CompatibilityShim -> ShimSkill
    OperatorSkill     -> ThinOperator
    WorkflowSkill
      | deterministicRouter source -> ToolBackedWorkflow
      | otherwise                  -> ContextualWorkflow
    MethodologySkill  -> ContextualWorkflow

selectProcessProtocol :: SkillKind -> SkillSource -> ProcessProtocol
selectProcessProtocol kind source =
  case kind of
    WorkflowSkill
      | lifecycleDriven source -> LifecycleProtocol
      | otherwise              -> WorkflowProtocol
    OperatorSkill
      | algorithmic source -> AlgorithmProtocol
      | otherwise          -> OperationProtocol
    MethodologySkill  -> DomainProtocol
    CompatibilityShim -> ShimRoute
    ReferenceDoc      -> ReferenceOnly

placeRule :: Rule -> RulePlacement
placeRule r
  | mechanizable r                                    = DeterministicGate
  | nonMechanizableSafety r                           = Harness
  | projectSpecific r                                 = ProjectContext
  | stageSpecific r                                   = StageContext
  | everyInvocationNeeds r && changesDecisionOrGate r = Harness
  | otherwise                                         = Remove

buildContextPlan :: SkillShape -> [PlacedRule] -> ContextPlan
buildThinHarness :: SkillShape -> ResponsibilityContract -> ContextPlan -> Markdown

构建流程

1. 明确范围和职责

阅读目标内容及相关仓库设计事实；检查 git 状态并保留无关改动。说明该技能负责的单一结果、权限边界、完成证据和不安全时的停止条件。编写技能本身不需要项目预检。只有当生成的技能行为依赖项目设置、仓库事实、制品写入或恢复时，才添加预检。

如果没有独立的可安装职责，或该职责已有技能、参考资料或工具负责，则选择 NoActiveSkill。已退役的 v1 CodeStable 名称也应选择 NoActiveSkill；迁移说明并不意味着要重新创建兼容垫片。仅当知识具有独立的分发契约时，才使用 ReferenceSkill。

2. 选择最小形态

先分类再编写；不要默认进行完整的协议重构。对于单个操作或制品，使用 ThinOperator；对于分阶段或可恢复的工作，使用 ContextualWorkflow；对于由确定性路由器或门槛负责脆弱选择的情况，使用 ToolBackedWorkflow。ShimSkill 仅包含规范目标和预设，并且仅在新接受的分发契约明确要求随附该别名时才允许使用。ReferenceSkill 只包含知识，不得虚构工作流。

安全的实现选择采用高度自由度，首选模式采用中等自由度；仅对脆弱操作或对不变量敏感的顺序采用低自由度。

3. 每条规则只放置一次

编辑前盘点现有规则和拟议规则。记录每条规则的来源、影响的决策、频率和 RulePlacement，然后应用 placeRule。

• 可机制化的安全措施和重复转换 -> 脚本、钩子或门槛。
• 阶段方法、模板和示例 -> 阶段参考资料。
• 项目事实、ADR 和经验总结 -> 仓库 CodeStable 制品。
• 每次调用都要做的决策和不可机制化的硬性门槛 -> 运行框架。
• 通用建议、重复的理由、过时的说明和对行为无影响的步骤 -> 删除。

信息必须有且仅有一个规范归属位置。不要在运行框架和文字参考资料中同时保留相同的路由、门槛或方法。

4. 在运行框架之前构建上下文计划

编写正文前调用 buildContextPlan。对于每个上下文来源，说明何时加载、为何重要、如何检查时效性、何时已收集足够上下文，以及如何复用已加载的事实。

入口上下文是安全执行下一步操作所需的最少信息。选择后，加载一个阶段协议，以及仅与当前任务相关的事实和支持材料。不要预先加载所有参考资料、ADR、笔记或源文件。

5. 编写精简的运行框架

按以下顺序编写运行时内核：触发条件／frontmatter、职责、上下文约定、必要时的决策约定、硬性门槛、必要时的协作，以及完成／失败。

目标审查阈值：操作员文档正文 30–80 行，工作流入口文档 60–120 行，shim 最多 40 行。超出阈值时，必须再次检查内容放置位置并说明明确理由，不能直接截断。

不要在运行框架中加入冗长的理由说明、历史叙述、宽泛清单、模板或常规编码步骤。只有在能帮助新 Agent 从入口了解如何运行并在可恢复的出口结束时，才保留精简的 ## Operation、## Workflow 或 ## Lifecycle。

6. 仅在有用时添加协作

仅委派边界明确、有明确负责人且可独立检查完成情况的工作。不要预先编写特定提供方的角色，也不要固定 Agent 数量。

交付的运行框架应与后端无关：描述能力，不要写产品名称；确切的后端／模型固定项应归入 ProjectContext。 创建审查者之前，先发现当前会话中可调用的子 Agent 创建和管理能力。不要用扫描 PATH 中的可执行文件来代替能力发现。创建审查者的方法优先顺序为：使用新上下文、明确指定模型、可访问工作区、可控制生命周期且能提供终结报告的托管式结构化委派；其次使用宿主子 Agent；只有在前两者不可用时，才使用有界的一次性 Agent CLI。明确选择符合条件的最强稳定模型；只有达到质量门槛后，才优先考虑多样性。

健康运行中的委派应持续绑定到其运行实例和目标；可查询且处于 Awaiting 状态的运行仍属健康。之后发现更好的创建方法，不构成取消或重复派发的理由。 仅当出现以下情况时才切换：运行以失败终结且没有报告、无法恢复运行身份、能力不匹配，或目标失效。

派发前先判定拓扑。除非委派 Agent 的明确职责是编排，否则默认将其视为 LeafExecutor。LeafExecutor 不得派发其他 Agent、唤醒或跟进子 Agent，也不得调用自身或其别名。只有 Orchestrator 可以继续委派。

使用以下数据包约定：

contextPacket = goal + relevantContext + scopeOwnership + boundaries + evidence + returnContract
mainAgentOwnsIntegration = true

委派的 Agent 自行选择执行路径。调用方编排器负责集成、冲突处理、最终验证和持久化状态。等待返回约定；若没有返回负载，且运行身份不可恢复，则视为委派失败，而不是盲目重发任务的许可。 工作树／分支策略由宿主负责。

7. 保留硬性约定

Haskell 约定门槛

仅在确实存在闭合的决策、转换、生命周期或不变量时使用 Haskell。由提示词路由的工作流应保留一份精简的决策事实，不得并行使用文字路由器。根据规范主入口标记的恢复域，审查每个阶段检查点；持久化 Awaiting 状态、原因和运行身份。阶段类型在本地闭合并不足够。

运行时对齐门槛

对于 ToolBackedWorkflow，应说明工具约定、不变量边界、结果和失败行为，但不要照搬其分支表。确保运行框架、运行时、参考资料和测试之间的持久化架构、规范化处理、终结优先级及结果一致。

每个技能都必须能独立安装：不要依赖同级技能文件或集中式入门运行时。特定技能的上下文和确定性辅助工具应放在所属技能的 references/ 和 scripts/ 中。项目上下文应放在 .codestable/attention.md、.codestable/lessons/、.codestable/work/，或项目现有文档和 ADR 中。v2 技能可以查找有用的 v1 产物，但不得执行其中的工具，也不得将其视为当前的分发入口。Shim 应保持精简。分支／工作树策略和 Agent 后端由宿主负责。

8. 压缩、验证并完成

为实现持续演进，每次有新经验时，都要通过 placeRule 纳入；绝不能将其视为追加说明文字的许可。替换过时规则，将专业知识移至上下文，并对整个文件进行删除检查。只增不减是失败模式。

当变更的契约涉及相关技能、共享参考资料、测试和 ADR 措辞时，也要一并更新。不要在运行时技能中添加变更日志或迁移说明。

加载 references/cs-skill-quality-gates.md 并制定验证计划。根据适用情况，执行其中的 Regression Ladder、Live Host Safety Gate 和系列覆盖要求。结构契约不能替代场景测试或真实运行时一致性测试。

运行相关仓库测试和 git diff --check。只有当请求明确包含经过测量的多模型实验，或发布策略要求时，才使用 eval-cs-skill。

失败处理

如果目标或输出不明确、无法保留相互重叠的编辑、权威边界冲突、无法确定所需上下文，或拟议的压缩会移除恢复或安全契约，则返回 NeedsHuman。报告当前目标、阻碍因素、已保留文件和安全的下一步操作。

输出契约

报告：

• 目标技能路径和 SkillShape；
• 一句话说明职责和所选自由度；
• 规则的处置方式：保留在 harness 中、移至阶段或项目上下文、机制化处理，或移除；
• 上下文计划和协作契约，或说明为何不需要；
• 已更改的文件；
• 验证结果和跳过的层级；
• 尚待维护者决定的问题和下一项具体操作。

明确区分实际编辑和建议。不能仅凭行数减少就声称成功；结果必须保持安全、可恢复，并且让没有聊天记录的全新 Agent 也能使用。