cs-docs

Docs 主入口。触发：写/更新开发者指南、用户指南、API 参考；不包含 docs-neat 收尾整理。不要用于新功能实现(cs-feat)、修 bug / 诊断报错(cs-issue)、大需求拆解(cs-epic)、领域建模或 ADR 决策记录(cs-domain)。

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

cs-docs

Name: cs-docs
Rating: 73.6 (1 reviews)
Author: codestable

启动必读

动作前先跑 CodeStable preflight：读 .codestable/attention.md（缺失先 cs-onboard）；不要用 AGENTS.md/CLAUDE.md 等外部入口代替它；细则见 .codestable/reference/execution-conventions.md。

cs-docs 是对外文档写作的唯一推荐入口，只覆盖开发者/用户指南和 API 参考。阶段收尾、知识库卫生、agent 入口同步仍走独立的 cs-docs-neat。

旧技能 cs-doc-tutorial、cs-doc-api 长期保留为兼容入口，只传入 requested_mode。

入口意图

本次调用参数：$ARGUMENTS

意图来源按优先级：调用参数 flag > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 $ARGUMENTS）时跳过该来源；调用参数用 --mode tutorial|api 表示文档模式，其余文本作为文档主题。旧裸 token（如 api）只作为历史提示词兼容识别；新文档和新调用一律用 --mode。

无参数默认行为：没有 mode / topic 时，先扫既有文档和公开表面，按状态机找 pending / draft / outdated 文档；若没有可恢复文档目标，再根据用户原话判断目标读者，不清楚就问用户选择。

用户没有明确文档类型时先判断目标读者和使用场景；仍不清楚就问用户选择。

模式边界

模式	产物	适用
tutorial	开发者指南 / 用户指南	教读者怎么完成一个任务
api	API / 组件 / 命令参考	给读者查公开表面、参数、返回值、示例

cs-docs 不做全局同步、不整理 .codestable/、不毕业 agent memory。发现这些需求时提示 cs-docs-neat。

Spec

csDocs :: DocsRequest -> DocsOutcome
csDocs req | attentionMissing req.repoFacts = NeedsHuman "route to cs-onboard"
           | otherwise = either Blocked (\s -> restoreDocsStage s req) (applyDocsResume req.resumeInput (restoreDocsState req.repoFacts))

data DocsRequest = DocsRequest
  { requestedMode : Maybe Mode           -- tutorial | api
  , userTopic     : Maybe Text
  , resumeInput   : Maybe DocsResume
  , repoFacts     : RepoFacts            -- 优先于 args / 聊天历史
  }

data Mode = Tutorial | Api

data Stage = TutorialStage | ApiStage | FocusedEdit | NeatHandoff

data DocsState = DocsState              -- 全部从 docs/ + manifest.yaml + 源码公开表面恢复
  { targetDoc   : Maybe Path
  , docStatus   : Missing | Draft | Current | Outdated  -- frontmatter status
  , manifest    : NoManifest | HasManifest             -- docs/api/manifest.yaml
  , entryStatus : Pending | Draft | Current | Outdated | Skipped
  , codeDrift   : InSync | Drifted       -- 相关源码/spec 是否已变
  , workflowStage : Maybe Stage           -- draft 的临时 workflow_stage；current 时必须清除
  , pendingCheckpoint : Maybe CheckpointReason
  , rejectedCheckpoint : Maybe CheckpointReason
  }

data DocsOutcome
  = RoutedTo Stage
  | HumanCheckpoint CheckpointReason
  | Completed DocsSummary
  | NeedsHuman Reason
  | Blocked Reason

data CheckpointReason
  = ReviewDraft | ReviewManifest | ConfirmOverwrite | ConfirmContractWording
  | ReviewEntry | ReviewSamples | ReviewAllDrafts
data DocsDecision = ApproveDocs | ReviseDocs | RejectDocs
data DocsResume = ResumeDocsCheckpoint CheckpointReason DocsDecision

applyDocsResume :: Maybe DocsResume -> DocsState -> Either Reason DocsState
applyDocsResume Nothing s = Right s
applyDocsResume (Just (ResumeDocsCheckpoint reason decision)) s
  | s.pendingCheckpoint == Just reason = Right (persistDocsDecision reason decision s)
  | otherwise                          = Left InvalidDocsResume
-- 目标读者/类型模糊不是 checkpoint：走 NeedsHuman "which reader?"（见 restoreDocsStage 与 Failure Behavior）

restoreDocsStage 从仓库事实选下一步（全局同步 / 记忆整理 → 路由 cs-docs-neat）：

restoreDocsStage :: DocsState -> DocsRequest -> DocsOutcome
restoreDocsStage(s, intent)
  | needsGlobalSync(intent)                              -> RoutedTo NeatHandoff   -- 全局同步/README/agent 入口/记忆整理，转 `cs-docs-neat`
  | ambiguousReader(s, intent)                           -> NeedsHuman "which reader?"
  | s.rejectedCheckpoint == Just ConfirmOverwrite       -> Completed (preservedExistingDocSummary s)
  | Just reason <- s.rejectedCheckpoint                 -> Blocked (OwnerRejectedDocsCheckpoint reason)
  | Just reason <- s.pendingCheckpoint                   -> HumanCheckpoint reason
  | s.docStatus == Draft && s.workflowStage == Just FocusedEdit
                                                         -> RoutedTo FocusedEdit   -- 批准后跨会话完成最小 patch
  | requestedMode intent == Just Api || wantsReference(intent)
                                                         -> RoutedTo ApiStage      -- 无 manifest 则初始化，缺条目则补
  | s.manifest == HasManifest && s.entryStatus in [Pending, Draft, Outdated]
                                                         -> RoutedTo ApiStage      -- 生成或增量更新条目
  | wantsTaskGuide(intent) && s.docStatus == Missing     -> RoutedTo TutorialStage -- 新建
  | s.docStatus == Current && s.codeDrift == Drifted     -> RoutedTo TutorialStage -- 更新
  | s.docStatus == Outdated                              -> RoutedTo TutorialStage -- 更新
  | s.docStatus == Current && smallEdit(intent)          -> RoutedTo FocusedEdit   -- 聚焦编辑，保持事实可追溯
  | otherwise                                            -> RoutedTo TutorialStage

restoreDocsStage 是唯一路由真相：启动后先扫既有文档和公开表面（docs/、README*、用户点名路径、相关源码导出/API/命令）恢复 DocsState，按上方分支选下一步。用户说“继续写文档”时，也按文件和 frontmatter / manifest 状态判断，不靠聊天历史。

Workflow

主执行主线（每次调用按序走；各 stage "怎么做" 的厚规则见对应 protocol，本节只定顺序与边界）：

preflight — 读 .codestable/attention.md；缺失则 route to cs-onboard；不得用 AGENTS.md/CLAUDE.md 代替 CodeStable attention。
parseEntryIntent — 优先级 flag > compat-preset > utterance；repoFacts override requestedMode；空参不推断 mode，先按仓库事实恢复。
restoreDocsStage — 扫 docs/、README*、manifest.yaml + 相关源码公开表面恢复 DocsState；先用 applyDocsResume 精确匹配并持久化 typed resume，再选 next stage；全局同步 / 记忆整理（非对外文档）→ route to cs-docs-neat。
loadStageProtocol — progressive reference loading：进某 stage 才按 stageProtocol 加载该 stage 一个 protocol，禁止 eager 读全部 references。
executeOrRoute — 先读代码和既有文档再落盘；tutorial/api 生成或增量更新，status 落到合法值；遇 HumanCheckpoint 必停。
exitRecoverable — 文档 status / manifest 状态明确、可从源码追溯，next stage 或 checkpoint reason 明确。

Reference 加载

stageProtocol :: Stage -> Protocol
stageProtocol TutorialStage = "references/tutorial/protocol.md"
stageProtocol ApiStage      = "references/api/protocol.md"      -- 必要时 references/api/reference.md
stageProtocol FocusedEdit   = "references/focused-edit/protocol.md"
stageProtocol NeatHandoff   = skill "cs-docs-neat"

先读代码和既有文档，再按对应模式生成或更新文档。不要凭记忆写 API。

人工 checkpoint

必须停下等用户明确确认的点：

目标读者、文档类型（tutorial / api）或落点路径缺失时返回 NeedsHuman "which reader?"；草稿完成后以 ReviewDraft / ReviewEntry / ReviewSamples / ReviewAllDrafts 放行。
覆盖或重写已有 current 文档前：确认旧内容确实过期，不是并行有效版本。
文档表述会改变 user-facing 契约或公开理解时：让用户确认口径后再落盘。

checkpoint 以 ResumeDocsCheckpoint reason decision 作为 typed resume input；草稿或 manifest 必须先以 draft 状态持久化，reason 精确匹配后再改为 current / approved，因此跨会话也能恢复待确认对象。无 pending、reason 不匹配或旧状态无法证明 checkpoint 时 Blocked InvalidDocsResume。API manifest 初次生成后用 ReviewManifest 放行，不能把“文件已存在”当作“用户已确认”。

Failure Behavior

返回 NeedsHuman 当：.codestable/attention.md 缺失（→ cs-onboard）；无法识别目标文档或落点路径；目标读者/文档类型模糊无法从仓库事实判定；requested mode 与仓库事实冲突；写 API 时源码事实源不足只能靠猜。覆盖当前文档、公开契约口径和各类草稿 review 属 HumanCheckpoint；全局同步 / 记忆整理属于 RoutedTo NeatHandoff，不得混成 NeedsHuman。报告：当前目标文档、阻塞或 checkpoint 原因、下一步用户动作、已写文件、是否可安全重试。

退出条件

文档目标读者、入口路径和状态已明确。
新增/更新文档的 status 或 manifest 状态已落到 draft / current / outdated / pending / skipped 中的合法值。
新增/更新的文档能从源码或现有项目事实追溯。
需要同步 README、agent 入口或记忆时，明确提示后续运行 cs-docs-neat。

Repository: codestable/CodeStable
Path: plugins/codestable/skills/cs-docs/SKILL.md
Commit: 7bed4ed

Last updated: 1 day ago
First committed: 12 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.