加载中

技能作为机构知识

第 6 课5 分钟

技能是组织将其机构知识转化为可操作内容的方式。这些指令是明确的、受版本控制的、广泛应用的,并在政策变更时集中更新。一个经验法则是:为必须一致应用的机构知识编写技能;不要为属于 CLAUDE.md 或提示的组件编写技能。

入门指南

  • 前提条件:无需任何前提条件。拥有 CLAUDE.md 会有所帮助,因为它能将智能体的工作知识保留在仓库中,但技能并不依赖于它。
  • 基础设施:一项有指定负责人和书面权威来源的政策。

如何执行

  1. 选择一项当前执行不一致的知识。这可以是一项安全标准、一项 API 设计规范,或一项品牌规则。
  2. 将其编写为一个技能,即一个包含 SKILL.md 的文件夹,其前置元数据说明何时触发,正文说明要做什么。工程师根据政策负责人的权威来源编写该技能,并借助 Claude 协助完成。
  3. 将该技能放入仓库的 .claude/skills/<name>/ 中,使其随代码一起发布,或通过插件在整个组织范围内分发。
  4. 测试该技能是否会触发。让 Claude 以不同方式执行相关任务,并确认每次都能加载该技能。
  5. 当政策发生变化时,修改该技能,并让政策负责人对变更进行签核。
  6. 工程师在下一次会话中会自动获取新版本。

实际效果

.claude/skills/secure-api-review/SKILL.md:

markdown
---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

治理考量

技能是一种控制手段,但属于建议性的。它使 Claude 在编写代码时更有可能应用该政策,但没有任何机制强制会话遵守它。必须始终成立的政策,需要在技能背后有某种确定性的机制,例如阻止该操作的钩子,或在 PR 阶段重新检查该政策的审查环节。技能使违规变得罕见,而钩子则使违规几乎不可能发生。钩子在编辑时捕获违规,而对拉取请求的同一检查则能捕获以其他方式进入分支的任何问题。技能调用会记录在会话追踪中,政策负责人会像审查代码一样审查技能变更。

如何衡量

  • 领先指标:从政策负责人批准政策变更到更新后的技能合并所花费的时间,取自该技能文件夹上的 PR。
  • 滞后指标:引用该政策的 PR 审查发现,一旦技能在代码编写时应用该政策,这一数字应趋近于零。如果该发现没有趋近于零,则说明该技能未被触发,或其文本已与官方政策脱节。

作为构建时防护机制的钩子

技能是一种建议性控制,而钩子则是其背后的确定性层。Claude 的大多数操作是在实现过程中进行的文件编辑和 shell 命令,因此构建阶段往往是钩子触发最频繁的地方。

构建阶段的钩子可以:

  • 阻止对受保护路径(例如生成的类或冻结的软件包)的编辑
  • 在文件编辑后运行格式化工具和代码检查工具,使偏差永不累积
  • 防止凭据进入差异(diff)
  • 为任何必须无例外成立的政策所对应的技能提供支撑

钩子会在每个与其匹配的操作上运行,因此构建阶段的钩子应当快速且仅针对发生变更的文件。更重的检查,例如完整的测试套件,应放在提交或 PR 阶段。

这是本页前面展示的 secure-api-review 技能第 4 条规则背后的钩子。该仓库属于一家保险公司,其端点文件位于 claims-api/routes/ 中。每次对这些文件之一进行编辑后,该钩子都会运行 scripts/check-endpoints.sh,这是该技能已经指明的、位于仓库根目录的脚本。当 OpenAPI 模式中标记为 pii 的字段进入日志调用或被抛出的错误中时,该脚本会失败。

该钩子在 .claude/settings.json 中注册。空的 args 列表使 Claude Code 直接运行该脚本,而不是通过 shell 运行:

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

该钩子脚本 .claude/hooks/api-policy.sh:

bash
#!/bin/bash
# 为 secure-api-review 技能的规则 4 提供支撑,使用该技能运行的同一脚本。
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

在编辑之后运行的钩子无法撤销该编辑,因此退出代码 2 会将脚本的消息呈现在 Claude 面前,Claude 随后可以修复该行。在记录了客户姓名的编辑之后,这是 Claude 从脚本中看到的消息:

text
secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

当 shell 命令重写文件时,Edit|Write 钩子不会触发。因此,同一脚本也会作为每个拉取请求上的必需检查运行:

yaml
name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

需要人工批准的钩子应归入第 5 阶段:部署中的关卡,因为在构建期间出现批准提示,会让一个人重新回到所有并行运行会话的关键路径上。