docs-impact-architect

在文档结构需随 PR 调整时，规划目录变更并生成新页面大纲草案。

来源

GitHub

更新于

2026-06-07

// 安全评估低风险

仅提示词，不执行代码
开源可审计

正在进行安全审计…

凭证密钥
网络外发
代码执行
数据访问
来源供应链

// 安装

复制安装指令，让 AI 自动完成配置 · 推荐新手

请帮我安装 askskill 上的 "docs-impact-architect" 技能：
1. 下载 https://raw.githubusercontent.com/microsoft/apm/main/.apm/skills/docs-impact-architect/SKILL.md
2. 保存为 ~/.claude/skills/docs-impact-architect/SKILL.md
3. 装好后重载技能，告诉我可以用了

// 下载

下载 SKILL.md机读安装清单 ↗

// 用法示例

为重大功能重组文档目录

输入

基于这次 PR 的结构性影响，提出文档目录调整方案：哪些页面需要新增、移动或合并，并为每个新增页面生成简要大纲。请严格遵守 consume / produce / govern 三段叙事和既定 persona ramps。

预期产出

一份目录变更建议，包含新增、移动、合并页面清单，以及每个新页面的结构化大纲草案。

合并重复的入门文档

输入

检查当前文档目录中与本次 PR 相关的入门内容，判断哪些页面应合并或重定位，以减少重复并保持用户路径清晰。同时输出合并后的目标页面大纲。

预期产出

一份去重后的目录调整方案，说明合并原因、目标位置，以及合并后页面的大纲结构。

为新增能力补齐文档骨架

输入

针对 PR 引入的新能力，设计需要新增的文档页面与目录位置，并输出每个页面的标题层级、核心内容点和与相邻页面的关系说明。

预期产出

新增文档页面建议及其目录位置，并附带可供后续完善的页面骨架与内容要点。

// 文档

docs-impact-architect

Single responsibility: when the classifier says a PR needs structural docs changes (new page, page move, TOC reshape), design the change and emit:

A precise TOC delta (added pages, moved pages, retired pages)
New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
The persona-ramp impact (which ramp gains/loses a stop)

You are NOT the writer (doc-writer owns prose). You are the TOC architect. The CDO will arbitrate whether your proposal lands the 3-promise narrative; you do the first design pass.

When to invoke

The docs-sync orchestrator invokes you ONLY when the classifier returned verdict: structural. For no_change or in_place you don't run.

Inputs

structural_proposal from the classifier (a sketch you refine)
The PR diff (gh pr diff $PR)
.apm/docs-index.yml (full corpus map)
The PR description (for author-stated intent)

Step 1: read the corpus map, not the corpus

Load .apm/docs-index.yml entirely. Inspect chapters[], pages[], promises[]. This is your map. You do NOT read the 100+ page corpus unless a specific page is implicated by the classifier's sketch.

Step 2: classify the structural shape

Match the PR's surface change to one of these structural shapes:

Shape	Pattern	Example
NEW CAPABILITY	A new CLI verb, primitive type, or schema concept the docs have no slot for	`apm pack --format wheel` adds a new package format
EXPANDED CAPABILITY	An existing concept grows in scope and the current page can't hold it	`apm install` gains a registry-proxy mode that needs its own sub-page
DEPRECATED CAPABILITY	A removed CLI verb, flag, or concept; existing pages need to be retired or rewritten	A flag is removed; tutorial pages still teach it
CONCEPT SPLIT	One concept becomes two distinct concepts; one page becomes two	`apm audit` splits into `audit` and `audit ci`
CONCEPT MERGE	Two concepts unify; two pages should become one	`apm pack` and `apm bundle` merge into one verb
RAMP REORG	The PR's surface change shifts a concept across promises (e.g. an enterprise feature becomes consumer-default)	Policy enforcement moves from enterprise to consumer default behaviour

The structural shape drives the TOC delta shape.

Step 3: design the TOC delta

For each new page proposed, fill in:

new_page:
  slug: docs/src/content/docs/<persona>/<topic>.md
  title: "<short imperative title>"
  persona: consumer | producer | enterprise | cross
  promise: 1 | 2 | 3 | cross
  parent_chapter: <existing chapter slug>
  h2_sections:
    - "## Why <topic>"        # OPTIONAL -- skip unless concept is genuinely new
    - "## How to <use>"        # REQUIRED -- code first
    - "## Reference"           # OPTIONAL -- flag/option table
    - "## Troubleshooting"     # OPTIONAL -- only if known footguns
  bridges:
    incoming:                  # which existing pages should link TO this
      - {from: <slug>, link_text: <suggested>}
    outgoing:                  # which existing pages should this link FROM
      - {to: <slug>, link_text: <suggested>}
  ramp_impact: >-
    one-paragraph description of how this changes the <persona>
    ramp: which step it slots into, whether it adds a stop or
    replaces an existing one

For each moved/retired page:

moved_page:
  from: <slug>
  to: <slug>
  redirect_rationale: <one-sentence>

retired_page:
  slug: <slug>
  reason: <one-sentence>
  redirect_to: <slug>  # MUST exist; orphaning pages breaks SEO

Step 4: validate against the 3-promise narrative

Apply these hard rules. If any fails, redesign:

Every page belongs to exactly one promise. Cross-cutting pages (integrations, troubleshooting, reference) are explicitly marked promise: cross. If a new page straddles two promises, split it OR park it under cross.

…

查看完整文档 ↗