技能文档同步
- 作者仓库星标 3,406
- 作者仓库 claude-octopus
- 领域
- 写作
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @nyldn · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
查找项目根目录中的所有`.md`文件(最大深度2),跳过`node_modules/`和`.git/`。阅读每个发现的文档文件,以便了解其当前内容的上下文。
运行`git diff --stat HEAD~1`(如果在功能分支上,则与基础分支进行比较)以识别哪些文件已更改以及每个文档中哪些内容现在可能已过时。对于每个文档文件,检查文档中提到的任何路径、函数名称、计数或版本号是否受到差异的影响。
自动修复路径、计数、表条目和版本号。这些是机械变化,不会改变意义。自动更新目标:在 diff 中重命名或移动的文件路径 数字计数(例如,数字更改时为“42 个测试”) 版本字符串(例如,当 `package.json` 碰撞时为 `v9.5.0`)
标记叙述、哲学或安全相关的文档部分以供用户确认。不要自动编辑这些。风险类别(需要用户批准): 标题包含以下内容的部分:“理念”、“原则”、“愿景”、“使命”、“安全”、“威胁模型”、“架构决策” 表达观点、策略或基本原理(不仅仅是事实)的段落 `## Why` 或 `## Rationale` 标题下的内容
将“销售测试”应用于每个变更日志条目:“阅读此项目符号的用户会认为‘哦,太好了,我想尝试一下’?”规则: 以用户利益为主导,而不是实施细节 使用主动语态(“添加 X”而不是“添加了 X”) 将项目符号控制在 120 个字符以内
检查所有文档文件中的键值是否一致。一致性检查: 版本号与 `README.md`、`CLAUDE.md`、`package.json`、`CHANGELOG.md` 以及引用当前版本的任何其他文件相匹配 自述文件中的功能列表与实际实现的内容相匹配(与命令/技能目录交叉引用) 徽章 URL 和shield.io 引用是最新的
确保每个文档文件都可以从`README.md`或`CLAUDE.md`访问。孤立文档是不可见的文档。检查:项目中的每个`.md`文件都应从`README.md`或`CLAUDE.md`链接(直接或通过另一个链接文档传递)标记没有入站链接的孤立文档建议在何处添加孤立文档的链接
根据差异更新项目的任务跟踪。操作: 标记已完成的项目:扫描差异中删除的 TODO/FIXME/HACK 注释,并将相应的项目标记为已完成 标记新的推迟工作:扫描差异中添加的 TODO/FIXME/HACK 注释并创建新的跟踪条目 如果项目使用进度跟踪,则更新完成百分比
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.
# Post-Ship Documentation Synchronization
Automated documentation synchronization for the Deliver phase. After code is committed and a PR is created, this skill reads all `.md` files in the project, cross-references the diff, auto-updates factual content, checks cross-doc consistency, and updates the PR body.
## Caps
- **Max 30 doc files scanned** — skip files beyond the cap, warn the user
- **Never clobber CHANGELOG** — append only, never delete existing entries
- **Ask user before changing narrative/philosophy sections** — risky changes require confirmation
## Step 1: Discover Docs
Find all `.md` files in the project root (max depth 2), skipping `node_modules/` and `.git/`.
```bash
# Discover all markdown files (max depth 2, skip noise directories)
DOC_FILES=$(find . -maxdepth 2 -name '*.md' \
-not -path './node_modules/*' \
-not -path './.git/*' \
-not -path './vendor/*' \
-not -path './.claude/*' \
2>/dev/null | head -30)
DOC_COUNT=$(echo "$DOC_FILES" | wc -l | tr -d ' ')
echo "Found $DOC_COUNT doc files to scan (cap: 30)"
if [[ "$DOC_COUNT" -ge 30 ]]; then
echo "WARNING: Doc file cap reached (30). Some files may be skipped."
fi
```
Read each discovered doc file so you have their current content in context.
## Step 2: Cross-Reference Diff
Run `git diff --stat HEAD~1` (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc.
```bash
# Get the diff stat to identify changed files
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
DIFF_STAT=$(git diff --stat HEAD~1)
DIFF_FULL=$(git diff HEAD~1)
else
BASE_BRANCH=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
DIFF_STAT=$(git diff --stat "$BASE_BRANCH"..HEAD)
DIFF_FULL=$(git diff "$BASE_BRANCH"..HEAD)
fi
echo "$DIFF_STAT"
```
For each doc file, check whether any paths, function names, counts, or version numbers mentioned in the doc were affected by the diff.
## Step 3: Auto-Update Factual Corrections
Fix paths, counts, table entries, and version numbers automatically. These are mechanical changes that do not alter meaning.
**Auto-update targets:**
- File paths that were renamed or moved in the diff
- Numeric counts (e.g., "42 tests" when the number changed)
- Version strings (e.g., `v9.5.0` when `package.json` bumped)
- Table entries referencing renamed or removed items
- Import/require paths that changed
**WHY:** Stale factual references erode trust in documentation. A user who sees a wrong path or count will doubt everything else in the doc.
## Step 4: Risky Change Detection
Flag narrative, philosophy, or security-related doc sections for user confirmation. Do NOT auto-edit these.
**Risky categories (require user approval):**
- Sections with headings containing: "Philosophy", "Principles", "Vision", "Mission", "Security", "Threat Model", "Architecture Decision"
- Paragraphs that express opinion, strategy, or rationale (not just facts)
- Content under `## Why` or `## Rationale` headings
- Any changes to `SECURITY.md` or `CONTRIBUTING.md` beyond version bumps
**WHY:** Narrative and philosophy sections reflect human judgment. Silently rewriting them risks misrepresenting the project's intent.
When risky changes are detected, present them to the user:
```
The following doc sections may need updating but contain narrative/philosophy content.
I will NOT auto-edit these. Please review and confirm each change:
1. README.md ## Philosophy — mentions "single-binary deployment" but diff adds Docker support
2. SECURITY.md ## Threat Model — new auth endpoint not documented
Approve changes? (list numbers to approve, or "skip all")
```
## Step 5: CHANGELOG Voice Polish
Apply the "sell test" to every CHANGELOG entry: **"Would a user reading this bullet think 'oh nice, I want to try that'?"**
**Rules:**
- Lead with the user benefit, not the implementation detail
- Use active voice ("Add X" not "X was added")
- Keep bullets under 120 characters
- Never delete existing CHANGELOG entries (append only)
- Group by: Added, Changed, Fixed, Removed (Keep a Changelog format)
**Example transformations:**
```
BAD: "Refactored spawn_agent to use parameter expansion instead of basename"
GOOD: "Speed up agent spawning by eliminating 750 subshell forks (92% reduction)"
BAD: "Added SUPPORTS_MCP_ELICITATION flag"
GOOD: "Support MCP elicitation for richer interactive prompts (CC v2.1.76+)"
```
**WHY:** The CHANGELOG is marketing copy for developers. Every bullet should make someone want to upgrade.
## Step 6: Cross-Doc Consistency
Check that key values are aligned across all documentation files.
**Consistency checks:**
- Version numbers match across `README.md`, `CLAUDE.md`, `package.json`, `CHANGELOG.md`, and any other files referencing the current version
- Feature lists in README match what is actually implemented (cross-reference with command/skill directories)
- Badge URLs and shield.io references are up to date
- Links between docs are not broken (relative path references)
- Command counts and skill counts match actual directory listings
```bash
# Example: check version consistency
PKG_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": *"//' | sed 's/".*//')
echo "package.json version: $PKG_VERSION"
# Check README mentions this version
if ! grep -q "$PKG_VERSION" README.md 2>/dev/null; then
echo "WARNING: README.md does not mention version $PKG_VERSION"
fi
# Check CHANGELOG has an entry for this version
if ! grep -q "$PKG_VERSION" CHANGELOG.md 2>/dev/null; then
echo "WARNING: CHANGELOG.md has no entry for version $PKG_VERSION"
fi
```
## Step 7: Discoverability Check
Ensure every documentation file is reachable from `README.md` or `CLAUDE.md`. Orphaned docs are invisible docs.
**Check:**
- Every `.md` file in the project should be linked from either `README.md` or `CLAUDE.md` (directly or transitively through another linked doc)
- Flag orphaned docs that have no inbound links
- Suggest where to add links for orphaned docs
**WHY:** Documentation that cannot be found does not exist from the user's perspective. Every doc must be one or two clicks from the entry points.
## Step 8: TODOS.md Update
Update the project's task tracking based on the diff.
**Actions:**
- Mark completed items: scan TODO/FIXME/HACK comments that were removed in the diff and mark corresponding items as done
- Flag new deferred work: scan TODO/FIXME/HACK comments that were added in the diff and create new tracking entries
- Update completion percentages if the project uses progress tracking
```bash
# Find new TODOs added in the diff
NEW_TODOS=$(echo "$DIFF_FULL" | grep '^+' | grep -iE 'TODO|FIXME|HACK' | grep -v '^+++' || true)
if [[ -n "$NEW_TODOS" ]]; then
echo "New TODOs found in diff:"
echo "$NEW_TODOS"
fi
# Find TODOs removed in the diff
REMOVED_TODOS=$(echo "$DIFF_FULL" | grep '^-' | grep -iE 'TODO|FIXME|HACK' | grep -v '^---' || true)
if [[ -n "$REMOVED_TODOS" ]]; then
echo "Resolved TODOs (removed in diff):"
echo "$REMOVED_TODOS"
fi
```
## Step 9: Commit Doc Changes
Commit all documentation changes to the current branch and update the PR body with a doc-sync summary.
```bash
# Stage only .md files that were modified by this skill
git add *.md docs/*.md 2>/dev/null || true
# Check if there are staged changes
if git diff --cached --quiet; then
echo "No documentation changes needed — all docs are up to date."
else
git commit -m "docs: post-ship documentation sync
- Auto-updated paths, counts, and version references
- CHANGELOG entries polished for user benefit
- Cross-doc consistency verified
- Discoverability check passed
"
echo "Documentation sync committed."
fi
```
If a PR exists for the current branch, update its body to include a doc-sync section:
```bash
# Update PR body with doc-sync summary (if PR exists)
PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || true)
if [[ -n "$PR_NUMBER" ]]; then
echo "Updating PR #$PR_NUMBER with doc-sync summary..."
fi
```
## Integration
This skill is designed to work as a sub-step of `flow-deliver`. After validation and review are complete, invoke doc-sync to ensure documentation stays current with the shipped code.
**Invocation from flow-deliver:**
```
After PR creation and CI passes:
1. Run doc-sync to update documentation
2. Push doc changes to the PR branch
3. Re-run CI if doc changes affect tests
```
**Standalone invocation:**
```
User: "sync docs"
User: "update documentation after merge"
User: "document changes from last release"
```
按说明文件中的顺序排列。
帽子
第 1 步:发现文档
第 2 步:交叉引用差异
第 3 步:自动更新事实更正
步骤 4:风险变更检测
文件/命令 -> /octo:* · skills/blocks/codex-host-adapter.md · .md · node_modules/ · .git/ · git diff --stat HEAD~1 · v9.5.0 · package.json
内容校验值 -> 3d2a2a419529
当前原文的自动摘译,尚未人工审校。
帽子
扫描最多 30 个文档文件 — 跳过超出上限的文件,警告用户 切勿破坏更改日志 — 仅追加,绝不删除现有条目 在更改叙述/哲学部分之前询问用户 — 有风险的更改需要确认
第 3 步:自动更新事实更正
自动修复路径、计数、表条目和版本号。这些是机械变化,不会改变意义。自动更新目标:在 diff 中重命名或移动的文件路径 数字计数(例如,数字更改时为“42 次测试”) 版本字符串(例如,当
package.json碰撞时为v9.5.0)