示例：SKILL.md Adapter

这个 public example 把一个已有 SKILL.md 描述成 Adapter/grill-me-skill-md。它不把外部 Markdown 直接视为原生 Skill，也不因为 source 是本地文件就自动提升信任。当前 CLI 没有 import --as Adapter。本页复现的是：手写 Adapter 和 Trust 对象，再用 schema、explain 和 Preflight 检查它们。文中的 examples/... 是 Huoban source repo 内的路径，不是文档站链接。

对象关系

examples/fixtures/grill-me/SKILL.md
  <- Adapter.spec.requirements[skill-source]

Adapter/grill-me-skill-md
  trustRef -> Trust/local-reviewed-grill-me
  capabilities -> huoban.dev/designReview, huoban.dev/planning

Run.spec.bindings.primary-review
  adapterRef -> grill-me-skill-md

Adapter 标准化外部能力；Requirement 声明目标环境依赖；Trust 记录来源与审查；Policy 约束副作用。它们的职责不能互相替代。

完整 SKILL.md fixture

下面逐字取自 examples/fixtures/grill-me/SKILL.md：

---
name: grill-me
description: Ask focused questions before committing to a design.
---

# Grill Me

Challenge assumptions, expose missing constraints, and record explicit decisions before implementation.

完整 Adapter

下面逐字取自 examples/adapters/grill-me-skill-md.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Adapter
metadata:
  name: grill-me-skill-md
  labels:
    huoban.dev/imported-from: SKILL.md
spec:
  source:
    type: skillMd
    path: examples/fixtures/grill-me/SKILL.md
  capabilities:
    - huoban.dev/designReview
    - huoban.dev/planning
  requirements:
    - id: skill-source
      type: localPath
      origin: declared
      target:
        path: examples/fixtures/grill-me/SKILL.md
        access:
          - read
  mapping:
    inputs:
      prompt: user.prompt
      context: profile.effectiveContent
    outputs:
      review: artifact.decisionNotes
  sideEffects:
    declared:
      - readFile
      - writeFile
  checkpoint:
    recommended: true
    reason: SkillProducesDesignJudgment
  trustRef:
    name: local-reviewed-grill-me
status:
  conditions:
    - type: AdapterImported
      status: "True"
      reason: ImportedFromSkillMd
    - type: ImportNeedsReview
      status: "True"
      reason: CapabilityAndSideEffectsInferred

spec.source.path 与 required localPath Requirement 的路径必须完全一致，并且 target.access 必须包含 read。当前 Preflight 不会从 source metadata 自动发明依赖；缺失或不匹配会产生 SourceRequirementMissing，不能进入权威就绪结果。

Requirement 与 import review 不是一回事

这个 Adapter 的 Requirement 是：

- id: skill-source
  type: localPath
  origin: declared
  target:
    path: examples/fixtures/grill-me/SKILL.md
    access:
      - read

origin: declared 表示依赖由对象作者声明。Adapter status 中的 ImportNeedsReview=True 则表示 capability 和 side effects 来自导入推断，需要 review。如果 Requirement 本身写成 origin: inferred，schema 要求同时写 reviewStatus。reviewStatus: needsReview 会让 Preflight 的 resolution 与 readiness 都保持 Unknown。当前 CLI 没有接受命令，也不会自动把它改成 accepted。

完整 Trust

下面逐字取自 examples/trust/local-reviewed-grill-me.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Trust
metadata:
  name: local-reviewed-grill-me
spec:
  subjectRef:
    kind: Adapter
    name: grill-me-skill-md
  source:
    type: local
    path: examples/fixtures/grill-me/SKILL.md
  level: reviewed
  review:
    reviewer: core-maintainer
    reviewedAt: "2026-06-23T12:00:00Z"
    conclusion: approved-for-local-use
  sandbox:
    required: true
    network: deny
  policyRefs:
    - name: safe-defaults

level: reviewed 是记录，不是权限授予。执行实现仍需应用 Policy/safe-defaults、sandbox、Checkpoint 和平台权限。

Run binding

Flow 只声明 capability 与 role：

- id: sharpen-idea
  requires:
    capability: huoban.dev/designReview
    role: primary-review

Run 再锁定 Adapter：

bindings:
  primary-review:
    adapterRef: grill-me-skill-md

如果需要 fallback，写在同一个 Run binding 内：

bindings:
  primary-review:
    adapterRef: grill-me-skill-md
    fallback:
      skillRef: design-review

上面的 fallback 形状来自当前 Run schema；public Run example 没有配置 fallback。CLI 可用 --fallback primary-review=skill:design-review 把它锁入 dry-run Run，但当前仓库不会执行自动切换。

复现验证

在 source repo 根目录运行：

npm exec -- huoban validate examples/adapters/grill-me-skill-md.yaml
npm exec -- huoban validate examples/trust/local-reviewed-grill-me.yaml
npm run explain
npm run print:dry-run
npm run preflight

Preflight report 中对应的完整 check 逐字取自 examples/generated/idea-to-spec-review-preflight-report.yaml：

- id: stage.sharpen-idea.adapter.grill-me-skill-md.skill-source.0
  ownerRef:
    kind: Adapter
    name: grill-me-skill-md
  requirementType: localPath
  optional: false
  stage: sharpen-idea
  checkedAt: 2026-07-15T00:00:00.000Z
  resolution:
    status: "True"
    reason: PathResolved
    message: examples/fixtures/grill-me/SKILL.md resolved relative to the preflight workspace.
  readiness:
    status: "True"
    reason: PathAccessible
    message: examples/fixtures/grill-me/SKILL.md permits read.

它记录声明路径在该次检查时可读，不证明 Markdown 内容可信，也不授权 Adapter 执行。

当前边界

能力	当前状态
手写 Adapter / Trust	schema 支持。
`validate` / `explain`	CLI 支持。
localPath Requirement Preflight	CLI 支持。
`SKILL.md -> Adapter` import	未实现。
自动 Trust 提升	未实现，也不应从文件存在推断。
Adapter execution	未实现。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

示例：SKILL.md Adapter

对象关系

完整 SKILL.md fixture

完整 Adapter

Requirement 与 import review 不是一回事

完整 Trust

Run binding

复现验证

当前边界

相关页面

​对象关系

​完整 SKILL.md fixture

​完整 Adapter

​Requirement 与 import review 不是一回事

​完整 Trust

​Run binding

​复现验证

​当前边界

​相关页面

对象关系

完整 SKILL.md fixture

完整 Adapter

Requirement 与 import review 不是一回事

完整 Trust

Run binding

复现验证

当前边界

相关页面