skill-update

技能更新

遵循 Anthropic 最佳实践，生成或优化 Claude Code 技能。

硬性上限（由 scripts/skill_linter.py 强制执行）

• SKILL.md ≤ 150 行
• reference/*.md ≤ 200 行（reference/scenarios/*.md ≤ 400 行）
• README.md ≤ 100 行
• 每个 SKILL.md 都必须包含带有 name + description 的 YAML frontmatter
• ## Anti-Patterns 章节之外不得出现 DO NOT / MUST NOT / NEVER
• 不得包含特定挑战的标识符（机器名称、实验室 ID、实验室 IP、保留标记）
• 每个 Markdown 链接都必须指向现有文件
• 每个参考文件都必须至少从另一个文件链接（不得存在孤立文件）

原则

• 简洁优先。 每个文件都要简短、简单、易读。斟酌每个词。
• 渐进式披露。 SKILL.md 用于导航；reference/ 存放细节；reference/scenarios/ 存放具体的利用流程。
• 职责分离。 SKILL.md = 做什么 + 何时做。reference/role-*.md = 生成的 Agent 应如何行动。
• 每条跨领域规则都有唯一规范来源（输出规范、凭据加载、暴力破解等）。其他文件只引用，不重复陈述。

文件结构

skills/<skill-name>/
├── SKILL.md           # ≤150 lines, YAML + navigation
├── reference/
│   ├── *-principles.md  # ≤150 lines (decision tree)
│   ├── INDEX.md
│   ├── *.md             # patterns, ≤200 lines
│   └── scenarios/
│       └── <category>/
│           └── *.md     # ≤400 lines, self-contained
└── README.md          # optional, ≤100 lines

SKILL.md 模板

---
name: <skill-name>
description: What it does AND when to use. Include trigger phrases.
---

# <Skill Name>

<one-paragraph scope>

## When to use

- <bullet>

## Workflow / Quick start

<≤30 lines>

## References

- [reference/...](reference/...)

## Anti-Patterns

- <when negative framing is genuinely needed, put it here>

运行

该流程是一套工作流——每个步骤都由代码强制执行，因此无法跳过。

Workflow('skill-update', { output_dir: 'projects/<engagement>' })   // harvest an engagement
Workflow('skill-update', { learnings: [{ text, technique_type }] }) // judge a known set
Workflow('skill-update', { mode: 'audit' })                         // read-only, writes nothing

添加 dryRun: true，即可查看写入计划而不实际写入。仅限父级编排器使用。

阶段。 接收（基线 skill_linter.py --json）→ 收集（重新组织经验）→ 评审（四道关卡 + 盲审反驳者）→ 路由（编写内容块）→ 写入（原样保存）→ 扫描（机密信息防护）→ 验证（检查 linter 差异，而非绝对干净的树—— 基线中已有违规项）。

每项晋升／拒绝／写入决策都由 .claude/workflows/lib/wf-helpers.mjs 中的纯 JS 实现 （promotionGate、capBudget、writeGate、lintDelta、skillUpdateGate）。没有 Agent 会决定是否晋升某条经验或是否允许写入。

四道晋升关卡

处理已完成任务中的技术和失败模式。只有满足全部四项，才能将经验加入技能库：

1. 可泛化。 可复用的模式，而非特定目标的知识。不得包含机器名称、实验室 ID、目标 IP、保留标记、撰写归属信息。
2. 有实质性改进。 能提升未来任务的覆盖范围、效率或决策质量。
3. 尚未在技能库其他位置收录。（scripts/skill_linter.py 会标记重复内容。）
4. 占用空间最少。 优先扩展现有条目，而非新增文件。保持技能库精简且信息密度高。

重新组织经验的方法

始终将经验表述为可复用模式：“遇到 X 条件时，尝试 Y 方法”——绝不要写成“在 box-N 上，Y 方法有效”。工具示例中使用 <TARGET_IP>、<DC_FQDN>、<DOMAIN> 占位符。

输出

三个类别，由代码构建，确保运行结果不会声称做了实际未执行的编辑： 已更新。 / 已跳过。（注明未通过的关卡）/ 无更改。

参考

• STRUCTURE.md — 目录布局要求。
• FRONTMATTER.md — YAML 规则。
• CONTENT.md — 写作指南。
• ROUTING.md — 技术类型 → 目标文件。

反模式

• 创建 CHANGELOG.md / SUMMARY.md / VERIFICATION.md 等辅助文件。
• 在技能本身中添加有关创建流程的元文档。
• 编写冗长的内联模板和示例（改为链接到 reference/）。
• 重新引入重复的规则说明（暴力破解、输出目录、环境变量读取器）。
• 文件超过上限——立即拆分到 reference/。