Skill 对象

​

字段

​

副作用枚举

readFile, writeFile, deleteFile, executeCommand,
modifyGitIndex, modifyGitHistory, networkAccess, sendMessage,
publishRemote, spendMoney, accessSecret, installDependency,
changePermission

​

合法示例

apiVersion: huoban.dev/v1alpha1
kind: Skill
metadata:
  name: design-review
spec:
  capabilities:
    - huoban.dev/designReview
  inputs:
    - name: proposal
      type: markdown
  outputs:
    - name: review
      artifactType: decision-notes
  sideEffects:
    declared:
      - readFile
      - writeFile
  checkpoint:
    required: true
    reason: human-design-decision

​

当前 CLI 行为

• validate 检查本页字段、capability 正则、必填项和副作用枚举。
• explain 输出 capabilities、Requirement、输入输出、副作用及 checkpoint reason。
• 当 Skill 被 Run stage 或 Lifecycle Handler 绑定时，Preflight 检查它是否提供所需 capability，并检查其 Requirement。
• 如果被绑定 Skill 有 adapterRef，Preflight 解析 Adapter，继续检查 Adapter Requirement、trustRef 和关联 Policy。
• 未被当前 Run 使用的 Skill 不会因为位于 workspace 就自动接受 Preflight 检查。

​

验证边界

• schema 不要求 input/output 名称唯一，也不解释类型兼容性。
• schema 不解释 profileHints，不检查 layer 是否存在。
• checkpoint 是开放提示结构，不等于一次 Checkpoint 对象。
• 普通 schema validation 不解析 adapterRef；当前 Preflight 只在 Skill 可达时解析。
• Skill 的副作用声明不会触发 Policy rule evaluation；当前 Preflight 不执行授权。

​

相邻概念边界

​

常见错误

• 漏写必填的 sideEffects.declared；无副作用时应写 declared: []。
• 把 capability 写成没有 / 的自由文本。
• 把外部环境依赖藏进 input 或 prompt，而不写 requirements[]。
• 把 profileHints 当作 Profile object reference。
• 认为 Skill 声明了 writeFile 就已经获得写权限。
• 把具体执行顺序或 shell 命令写进 Skill；编排属于 Flow，外部执行接口属于 Adapter。