来源：https://academy.claude.com/courses/ai-native-sdlc-playbook/skills-as-institutional-knowledge 读这篇之前：05 CLAUDE.md 有帮助但不是必须 不确定：ZH 是 Clint 译官方英文课体，不是 Anthropic 中文。
本课词汇
| English | 中文 | 怎么记 |
|---|---|---|
| skill | 技能包 | 一个文件夹，里面有 SKILL.md：何时触发、做什么 |
| SKILL.md | 技能说明 | frontmatter 写触发条件，正文写步骤 |
| advisory control | 劝告性控制 | 让 Claude 更可能遵守，但不强制 |
| deterministic | 确定性的 | 同一输入同一结果。hook 属于这类 |
| plugin | 插件 | 把 skill 发到全组织，不只一个仓库 |
对照正文
技能是什么 / What skills are
EN Skills are how an organization makes its institutional knowledge operational. The instructions are explicit, version controlled, applied broadly, and updated centrally when policy changes. The rule of thumb: write a skill for institutional knowledge that must be applied consistently; don’t write a skill for components that belong in CLAUDE.md or a prompt.
ZH Skills 是组织把内部知识变成可执行的方式。说明是显式的、进版本库、大范围套用，政策一变集中更新。经验法则：必须一致套用的组织知识才写成 skill；属于 CLAUDE.md 或 prompt 的东西不要写成 skill。
怎么起步 / Getting started
EN Prerequisites: None required. Having a CLAUDE.md helps, because it keeps the agent’s working knowledge in the repo, but a skill does not depend on it.
Infrastructure: One policy with a named owner and a written source of truth.
ZH 先决条件：无。有 CLAUDE.md 有帮助，因为它把 agent 的工作知识留在仓库，但 skill 不依赖它。
基础设施：一条政策、有点名的主人、有书面权威来源。
怎么做 / How to execute it
EN 1. Pick one piece of knowledge that is enforced inconsistently today. This could be a security standard, an API design convention, or a brand rule.
2. Write it as a skill, a folder containing a SKILL.md whose frontmatter says when it triggers and whose body says what to do. An engineer writes it from the policy owner’s source of truth, using Claude to help.
3. Put the skill in the repo at .claude/skills/<name>/ so it ships with the code, or distribute it organization-wide through a plugin.
4. Test that the skill triggers. Ask Claude to do the relevant task in different ways and confirm the skill loads each time.
5. When the policy changes, change the skill and have the policy owner sign off on the change.
6. Engineers pick up the new version automatically in their next session.
ZH 1. 挑一块今天执行不一致的知识。可以是安全标准、API 设计约定、或品牌规则。
2. 写成 skill：一个文件夹，里面有 SKILL.md，frontmatter 写何时触发，正文写做什么。工程师按政策主人的权威来源写，Claude 帮忙。
3. 放到仓库 .claude/skills/<name>/，跟代码一起走；或用 plugin 发到全组织。
4. 测它会不会触发。用不同说法让 Claude 做相关任务，确认每次都加载。
5. 政策变了，改 skill，政策主人签字。
6. 工程师下次会话自动拿到新版本。
长什么样 / What it looks like
EN .claude/skills/secure-api-review/SKILL.md:
ZH .claude/skills/secure-api-review/SKILL.md：
---
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.ZH 官方示例，保持英文。对外接口：要网关 JWT、按 OpenAPI 校验、改状态要审计事件、PII 不准进日志。跑 scripts/check-endpoints.sh，输出写进摘要。
治理 / Governance considerations
EN A skill is a control, though an advisory one. It makes Claude likely to apply the policy while the code is written, and nothing forces a session to comply with it. A policy that must always hold needs something deterministic behind the skill, such as a hook that blocks the action or a review pass that re-checks the policy at the PR. The skill makes violations rare and the hook makes them close to impossible. Skill invocations are logged in session traces, and the policy owner reviews skill changes like code.
ZH Skill 是一种控制，但是劝告性的。它让 Claude 写代码时更可能套政策，没有东西强制一次会话必须遵守。必须永远成立的政策，skill 后面要有确定性的一层：拦住动作的 hook，或 PR 上再查一遍的审查。Skill 让违规变少，hook 让违规接近不可能。Skill 调用记在会话轨迹里，政策主人像审代码一样审 skill 改动。
怎么衡量 / How to measure it
EN Leading indicator: Time from the policy owner approving a policy change to the updated skill merging, taken from the PR on the skill folder.
Lagging indicator: PR review findings that cite the policy, which should fall toward zero once the skill is applying the policy while the code is written. Where the findings don’t fall toward zero, either the skill isn’t triggering or its text has drifted from the official policy.
ZH 领先指标：政策主人批准政策变更，到更新后的 skill 合并，用 skill 文件夹上的 PR 计时。
滞后指标：引用该政策的 PR 审查发现。skill 在写代码时就在套政策的话，这数字应趋向零。如果没掉，要么 skill 没触发，要么正文已经跟官方政策漂开了。
Hooks 当构建时护栏 / Hooks as build-time guardrails
EN A skill is an advisory control, while a hook is the deterministic layer behind it. Most of Claude’s actions are file edits and shell commands during implementation, so the build phase is where hooks can end up firing most often.
ZH Skill 是劝告性控制，hook 是它后面那层确定性的。Claude 大多数动作是实现时改文件和跑 shell，所以 hook 最常在构建阶段开火。
EN Build-phase hooks can:
- Block edits to protected paths such as generated classes or a frozen package
- Run the formatter and linter after file edits so drift never accumulates
- Keep credentials out of the diff
- Back any skill whose policy has to hold without exception
ZH 构建阶段的 hook 可以：
- 拦住对受保护路径的编辑，例如生成类或冻结的包
- 改文件后跑 formatter 和 linter，不让风格漂
- 不让凭据进 diff
- 给必须毫无例外成立的 skill 垫底
EN A hook runs on each action that matches it, so build-phase hooks should be fast and scoped to the file that changed. Heavier checks such as the full test suite belong at the commit or the PR.
ZH Hook 对每个匹配的动作都跑，所以构建阶段的 hook 要快，范围收在改过的文件。全量测试这类更重的检查，放提交或 PR。
EN A hook that asks a human for approval belongs with the gates in Stage 5: Deploy, because an approval prompt during the build puts a person back on the critical path of all the sessions running in parallel.
ZH 要人批准的 hook 放到 Stage 5: Deploy 的闸门里。构建中弹出批准，等于把人重新放回所有并行会话的关键路径上。
读完能记住的三句话
EN A skill is advisory. A hook is deterministic. Policies that must always hold need both. ZH Skill 是劝告。Hook 是硬拦。必须永远成立的政策，两样都要。
EN Write a skill for knowledge that must apply consistently, not for things that belong in CLAUDE.md or a prompt.
ZH 必须一致套用的知识才写成 skill；属于 CLAUDE.md 或 prompt 的别写成 skill。
EN Don’t put human-approval hooks on the build path; they stall every parallel session. ZH 别把要人点头的 hook 放构建路径上，并行会话全会卡住。