Skills Hooks and Instructions zh CN

Skills、Hooks 与 Instructions

语言： English · 简体中文

LWC 能否发挥作用，不只取决于 Agent 知道有哪些命令，更取决于它能否在正确时机判断记忆、图、转换或写回是否会改善当前任务。三层互补集成负责这一点：

Instructions -> 始终可见的能力发现与安全边界
Skill        -> 详细的决策与操作教学
Hook         -> 生命周期边界的当前 readiness 与有界强上下文

MCP 提供只读数据，这三层则教 Agent 应在何时、怎样使用它。

规范 using-lwc Skill

LWC 内置一个名为 using-lwc 的规范 Agent Skill。简短的 SKILL.md 负责路由，聚焦 reference 则各自讲解一项能力：

• 核心记忆与主动记忆；
• LLM Wiki 建模；
• 记忆策略与触发时机；
• Source 整合与日常操作；
• 文档图、CodeGraph 与词图；
• 强标签与上下文；
• 文档转换；
• Agent 首次接入；
• 恢复与维护。

Skill 还包含可移植 bootstrap/install 脚本和全局 Purpose/Schema 资产。AgentTarget 安装器会把完整的版本化 bundle 写入 host 官方 Skill 目录，不依赖 AMC、私有包管理器或维护者本机路径。

实质项目工作、代码结构问题、文档关系、持久研究、排障、设计、恢复和已验证记忆维护都应使用该 Skill。没有可复用项目上下文的简单独立修改可以跳过。

为什么只有一个 Skill

稳定的单一 Skill 名称让每种 host 使用同一触发方式，也避免 Agent 在多个重叠工具中猜测。聚焦 reference 仍然保持渐进式上下文：Agent 只读取当前任务所需的能力文档。

规范调用方式为：

$using-lwc

不支持显式 Skill 调用的 host 仍可通过已安装 Instructions 主动发现它。

带边界标记的 Instructions

LWC 会把一段短指导写入每种 Agent 官方的全局或项目 instruction surface，例如 AGENTS.md、CLAUDE.md、GEMINI.md、rules 或插件指导。

该段落使用以下边界：

<!-- LWC_AGENT_START -->
<!-- LWC_AGENT_END -->

它要求 Agent：

• 实质工作使用 using-lwc；
• 把 lwc 识别为 MCP entry，把 lwc_explore 识别为唯一只读工具；
• 在生命周期边界检查 LWC_READINESS 与强标签上下文；
• 初始化缺失图能力前只询问一次；
• 分别验收文档图与 CodeGraph；
• 说明可选转换能力，但不从 Hook 安装；
• 把已载入 Wiki 内容当作参考数据，而不是更高优先级指令。

安装与刷新只替换 LWC 拥有的 marker block，保留前后用户指令。标记重复、不平衡或顺序错误时会安全失败，不会猜测应该怎样重写文件。

生命周期 Hooks

Native Hook 在对应 Agent 支持的生命周期边界运行，例如会话开始、恢复、清空或上下文压缩。它通过以下命令编译本地有界上下文：

lwc --scope all agent hook --agent codex --event SessionStart

输出 envelope 会适配 host 官方 Hook 协议。Kiro 可以接收 raw 文本，其他 host 则获得各自需要的 JSON 字段结构。

边界 Hook 输出包括：

• 项目 Wiki 状态的 LWC_READINESS；
• 文档图设置、来源、投影和授权需求；
• CodeGraph 运行时与项目索引 readiness；
• Markdown 转换器设置与可执行文件可用性；
• Agent 集成检查指引；
• 策略与全局预算内的完整强标签页面；
• 省略项与重复项诊断。

Hook 安全契约

生命周期 Hook 只做有界本地读取，绝不会：

• 初始化 Wiki；
• 启用或切换图引擎；
• 下载 CodeGraph 或建立索引；
• 安装转换器；
• 读取聊天记录；
• 写入记忆；
• 在每次 prompt 时广泛搜索 Wiki。

Readiness 检测只代表应该询问或选择路线，不代表已经获准修改状态。用户选择“稍后”后不改变任何内容，也不能阻塞主要任务。

Claude Prompt Hook

Claude Code 默认还可以安装一项 UserPromptSubmit Hook。它把当前 prompt 交给现有 CodeGraph prompt helper，并且只有确实找到有用内容时才返回上下文。

不需要这项可选逐 prompt 集成时，可以在安装时关闭：

lwc agent install --target claude --no-prompt-hook

这不会关闭会话边界 readiness 或规范 Skill。其他 host 使用自己支持的生命周期 surface，不会仿造 Claude 私有 Hook schema。

失败行为

Hook 失败时会闭合为空 host envelope，不会破坏 Agent 会话。完整 Skill 缺失时，Instructions 会告诉 Agent 怎样检查安装状态：

lwc agent status --target auto --location global
lwc agent refresh --target auto --location global

不要从维护者 HOME 复制文件来修复其他机器，应使用已经全局安装的 lwc 刷新，确保路径和 host 格式遵循官方环境。

信任边界

• Hook 上下文和 Wiki Page 都是参考数据。
• System、developer、user、仓库与安全指令保持更高优先级。
• Skill 解释策略，但不授予图或外部文件授权。
• 已安装 Instructions 应保持简短，只负责能力发现，不能复制整本手册。
• 只有 Agent 存在官方 permission surface 时才配置权限。

完成证据

指导栈只有满足以下条件才算健康：

• Host 能加载规范 using-lwc Skill 及全部 bundle reference；
• Instruction 文件中 owned marker 只出现一次；
• 边界 Hook 以 host 有效 envelope 返回 LWC_READINESS；
• 强标签页面完整、有界，并带省略项诊断；
• 重复 refresh 不会复制文件、marker 或 Hook entry；
• 卸载只删除 LWC 拥有的集成状态。

下一篇：AgentTarget 安装与集成