---
name: knowledge-doc-format-rewrite
skill_id: knowledge-doc-format-rewrite
display_name: Skill 与知识文档 frontmatter 规范化
description: 对团队 Skill 文件或 K1-K12 知识文档进行 YAML frontmatter 智能创建与规范化，同时作为 Open API 前置合规检查工具。支持两种模式：A)
  无 frontmatter 文档——AI 根据正文内容智能推导 K 类型与字段值，通过交互式多选题确认流辅助用户快速创建合规 frontmatter；B) 已有
  frontmatter 文档——统一格式、补齐必填项、校验枚举值、清理模板注释、检查 Open API 必填字段完整性（tags/owner 缺失高优警告）。正文内容始终保留不变。
  核心原则：frontmatter 是唯一事实源，Open API 只接收 doc_id/skill_id + content，所有业务字段必须从 frontmatter
  解析。
version: 1.5.2
status: active
tags:
- 文档规范
- frontmatter
- 格式化
- 知识工程
- AI辅助
- 规范化
owner: 知脑平台业务组
disable-model-invocation: false
trigger_events:
- manual
- user.query
explicit_commands:
- /knowledge-doc-format-rewrite
- /fmt-frontmatter
triggers:
  keywords:
  - frontmatter
  - skill格式化
  - 知识文档格式化
  - yaml规范化
  - frontmatter整理
  - skill模板检查
  - frontmatter创建
  - 知识文档创建
  - K类型推导
  - 文档元数据
  filePatterns:
  - '**/*.md'
  changeTypes:
  - docs_change
  - skill_change
  whenToUse:
  - on_request
required_knowledge: []
tools: []
quality_gate:
  min_citations: 0
  require_source_reference: false
  forbid_unverified_claims: false
  max_latency_ms: 60000
metrics:
  total_runs: 0
  human_acceptance_rate: null
  latency_p95_ms: null
  last_run_date: null
---




# Skill 与知识文档 frontmatter 智能创建与规范化（`knowledge-doc-format-rewrite`）

## 能力摘要

对团队 Skill 文件或 K1-K12 知识文档进行 YAML frontmatter 的**智能创建**与**规范化改造**。支持双模式运行：

- **模式 A（智能创建）**：针对**无 frontmatter** 的 Markdown 文档，AI 分析正文内容（标题结构、技术关键词、代码语言、业务术语等），自动推导最可能的 K1-K12 知识类型及各字段值，通过**交互式多轮确认流**引导用户快速完成合规 frontmatter 的创建。
- **模式 B（规范化）**：针对**已有 frontmatter** 的文档，统一 YAML 格式（缩进、引号、列表风格）、补齐必填项、校验枚举值、清理模板注释、按标准 schema 重排字段顺序。

两种模式下，Markdown 正文内容均保持不变。遇到多义性选择时均以多选题向用户确认，降低用户对复杂 schema 的理解成本。

本 Skill 运行于 OpenCode、Claude Code 等 AI 编程工具环境，面向团队内部 Skill 与知识工程文档的标准化治理。

**适用场景**：

- **新建知识文档时不知道选什么 K 类型、怎么填 frontmatter** —— AI 推导 + 确认流降低门槛
- **已有 Skill 文件 frontmatter 格式混乱、字段缺失或包含模板占位符注释**
- **从其他平台迁移的知识文档 frontmatter 字段与团队规范不一致**
- **批量检查并统一已有文档的 YAML 头部格式**（缩进、引号、列表风格、字段排序）
- **入库前对 Skill/knowledge 文档进行 frontmatter 合规性预处理**

---

## 输入与输出

### 输入

| 字段 | 说明 | 必填 |
|------|------|------|
| `document` | 待处理的完整文档内容（Markdown 正文，可含或不含 `---` 包裹的 YAML frontmatter） | 是 |
| `doc_type` | 文档类型：`skill`（K10 Skill 文件）或 `knowledge`（K1-K9、K11、K12 知识文档） | 否，默认自动识别 |
| `create_mode` | 创建模式：`auto`（自动判断：无 frontmatter 则进入智能创建，有则进入规范化） / `create`（强制智能创建） / `format`（强制规范化） | 否，默认 `auto` |
| `strict_mode` | 是否严格模式：缺失必填字段时报错而非提示 | 否，默认 `false` |
| `preferred_k_type` | 用户倾向的 K 类型（如 `K5`），用于辅助推导 | 否 |

### 输出

- **格式**：Markdown 结构化输出
- **模式 A 输出**：
  - 推导的 K 类型及置信度说明
  - 逐字段确认交互（多选题，含"接受/修改/跳过"选项）
  - 最终生成的完整文档（新建 frontmatter + 未改动正文）
  - 字段推导依据摘要
- **模式 B 输出**：
  - frontmatter 规范化后的完整文档
  - 改动摘要（格式修复、字段排序、枚举校验等）
  - 合规性提示（缺失字段、非法枚举值清单）

---

## 执行策略

### 模式判定

1. 读取 `create_mode` 参数和 `document` 内容
2. 若 `create_mode=auto`：检测文档是否含 `---` 包裹的 YAML frontmatter
   - **无 frontmatter** → 进入**模式 A（智能创建）**
   - **有 frontmatter** → 进入**模式 B（规范化）**
3. 若 `create_mode=create` → 强制进入模式 A
4. 若 `create_mode=format` → 强制进入模式 B

### 模式 A：智能创建（无 frontmatter 文档）

1. **内容分析与 K 类型推导**：扫描正文标题、关键词、代码块语言、表格结构、章节主题，对照 K1-K12 类型特征矩阵推导最可能的类型（输出 Top-3 候选及置信度）
2. **K 类型确认**：以多选题形式呈现推导结果，等待用户确认
3. **Schema 加载**：根据确认的 K 类型加载对应 frontmatter schema（K1-K9、K11、K12 来自 `frontmatter-schemas.yaml`，K10 Skill 来自 Claude Code Skills 标准）
4. **字段智能推导**：逐字段分析正文可提取的元数据：
   - `title` → 从一级标题提取
   - `display_name` / `skill_id` → 从标题和描述提取
   - `platforms` / `domains` / `projects` / `teams` → 从技术栈/业务/项目/团队关键词推导
   - `scope` / `trust_level` → 从内容范围和权威度描述推导
   - `owner` → 从正文署名或默认推断
   - **K10 特有**：`trigger_events` / `explicit_commands` / `triggers`（keywords, filePatterns, changeTypes, whenToUse）→ 从 "When to use"、"触发词"、Workflow 章节推断
   - **K10 特有**：`required_knowledge` / `tools` / `quality_gate` / `metrics` → 从 References、Workflow 工具、验证步骤推断
5. **交互式确认流**：每个推导字段以多选题输出"接受 / 修改 / 跳过"，必填字段不允许跳过；对枚举字段提供下拉式选项说明
6. **frontmatter 组装与规范化**：按标准 schema 顺序组装、统一缩进/引号/列表格式
7. **输出结果**：输出完整文档（新建 frontmatter + 未改动正文），附推导依据摘要

### 模式 B：规范化（已有 frontmatter 文档）

1. **识别文档类型**：根据 frontmatter 字段特征自动判断 Skill（`skill_id`/`trigger_events`）或 Knowledge（`doc_id`/`knowledge_type`）
2. **解析 frontmatter**：提取 YAML 头部，检查格式错误（缩进、引号、换行等）
3. **字段完整性检查**：对照 schema 检查必填字段是否缺失
4. **枚举值校验**：`status`、`scope`、`knowledge_type`、`changeTypes`、`whenToUse` 等字段值是否在允许枚举范围内
5. **格式规范化**：统一 YAML 缩进（2 空格）、统一列表格式（block style）、统一字符串引号策略、清理模板注释和占位符
6. **字段排序**：将 frontmatter 字段按标准 schema 的推荐顺序重新排列
7. **输出结果**：输出规范化后的完整文档，附改动摘要

> 详细调用顺序、推导规则、确认流格式详见 `prompt.md`。

---

## 依赖与边界

- **依赖知识**：无（规范化规则内置于 prompt，不依赖外部知识库）
- **依赖工具**：无（纯文本处理，不调用 MCP 工具）
- **不覆盖场景**：
  - 不修改 Markdown 正文内容（标题、段落、列表、代码块、表格等均保留原样）
  - 不修改正文语义、术语、数据值、代码逻辑
  - 不处理 frontmatter 严重语法错误导致无法解析的文件（提示用户手动修复）
  - 对 K 类型推导结果不做 100% 保证，最终类型选择由用户确认
  - 不从外部系统（如 GitLab、LDAP）查询真实人员/项目信息，owner/teams 等字段基于正文推断或用户输入

---

## 风险与限制

- frontmatter 严重语法错误（如缩进混乱、冒号缺失）可能导致解析失败，此时会输出错误提示而非自动修复
- 对自定义扩展字段（超出标准 schema 的字段）仅做格式规范化，不做值校验
- 超大文档（>5000 行）可能超出上下文窗口，建议分段处理

---

<!-- eval-skip-start -->
## Eval 与发布

> 此节不参与 AI 检索（ingest.py 跳过 eval-skip 区域）。

- eval case 见同目录 `eval.yaml`
- 上线前 eval case 数量 >= 10，通过率 >= 80%
- 每次版本升级须人工抽检 3 个真实案例

| 版本 | 日期 | 维护人 | 说明 |
|------|------|--------|------|
| 1.0.0 | 2026-05-15 | 知识平台团队 | 初始版本（通用文档格式改写） |
| 1.1.0 | 2026-05-15 | 知识平台团队 | 重构为 Skill/Knowledge frontmatter 专用规范化 |
| 1.2.0 | 2026-05-18 | 知识平台团队 | 新增无 frontmatter 文档的智能创建能力：K 类型推导引擎、字段智能提取、交互式确认流、友好字段解释 |

<!-- eval-skip-end -->

## 字段说明参考

- **Skill frontmatter 规范**：遵循 Claude Code Skills 标准（`skill_id`、`name`、`description`、`version`、`status`、`trigger_events`、`explicit_commands`、`triggers`、`required_knowledge`、`tools`、`quality_gate`、`metrics`）
- **K1-K9、K11、K12 知识文档 frontmatter 规范**：遵循 `frontmatter-schemas.yaml` 中各类型 schema（`doc_id`、`knowledge_type`、`title`、`scope`、`status`、`platforms`、`domains`、`projects`、`teams`、`owner`、`tags` 等）
- **通用 YAML 格式规范**：缩进 2 空格、列表使用 block style（`- ` 前缀）、字符串统一双引号、字段间保留 1 个空行分组、移除模板注释和占位符
