CX-06 Skills 完整指南：在 App 中调用和编写可复用工作流

启动时扫描可用 Skills
  -> 把 name / description / path 放进初始上下文
  -> 用户点名或任务匹配 description
  -> Codex 读取对应 SKILL.md
  -> 必要时再读取 references、调用 scripts 或工具
  -> 按 Skill 约定输出结果

$code-review 审查当前 diff，重点看安全、测试和边界情况。

按我们的代码审查 Skill 检查这次改动。

.agents/skills/code-review/
  SKILL.md

---
name: code-review
description: Review code changes for bugs, regressions, security risks, and missing tests.
---
 
# Code Review
 
## Workflow
 
1. Inspect the current diff.
2. Identify behavior changes.
3. Look for bugs, security risks, and missing tests.
4. Report findings first, ordered by severity.
 
## Output
 
- Findings with file and line references.
- Open questions.
- Test gaps.
 
## Rules
 
- Do not rewrite code unless explicitly asked.
- Do not praise changes before listing findings.

Use when [任务场景]. Do [核心动作]. Do not use when [边界].

description: Use when reviewing code changes for correctness, regressions, security risks, and missing tests. Report findings first. Do not use for general code generation.

description: Helps write high quality code.

---
name: code-review
description: Use when reviewing changed code for bugs, regressions, security risks, and missing tests. Report findings first.
---
 
# Code Review
 
## When To Use
 
- Current diff or PR needs review.
- User asks for review, audit, or risk check.
 
## Do Not Use
 
- User asks to implement a feature from scratch.
- There is no code diff or target file.
 
## Workflow
 
1. Inspect the diff.
2. Identify behavior changes.
3. Check correctness, security, tests, and scope.
4. Report findings first, ordered by severity.
 
## Output
 
- Findings with file / line references.
- Open questions.
- Verification gaps.

my-skill/
  SKILL.md
  references/
    checklist.md
    style-guide.md
  scripts/
    validate.js

## Scripts
 
- `scripts/check-links.js`
  - Purpose: check internal markdown links.
  - Reads: docs/\*_/_.md
  - Writes: nothing by default.
  - Network: no.
  - Runtime: Node.js 20+.
  - Failure: print broken links and exit non-zero.

.agents/skills/code-review/
  SKILL.md

---
name: code-review
description: Review changed code for correctness, security, and missing tests.
---
 
# Code Review
 
## Workflow
 
1. Read the current diff.
2. Check correctness, security, test coverage, and scope creep.
3. Report findings first, ordered by severity.
4. Do not modify files unless the user asks for fixes.
 
## Output
 
- Findings
- Open questions
- Verification notes

使用 $code-review 审查当前 diff。只报告问题，不修改文件。

.agents/skills/release-check/
  SKILL.md
  references/
    release-policy.md

这个流程只服务当前仓库。请帮我判断它应该做成项目级 Skill、用户级 Skill，还是 Plugin，并说明理由。不要创建文件。

---
name: code-review
description: Use when reviewing code changes for correctness, regressions, security risks, missing tests, and scope creep. Report findings first. Do not use for implementation.
---
 
# Code Review
 
## Workflow
 
1. Inspect the current diff or PR diff.
2. Identify behavior changes.
3. Check correctness, security, performance, tests, and scope.
4. Report findings first, ordered by severity.
 
## Output
 
- Findings with file and line references
- Open questions
- Verification gaps
- Suggested next action
 
## Rules
 
- Do not modify files unless explicitly asked.
- Do not praise before findings.
- Do not invent test results.

---
name: release-readiness
description: Use before a release to check changelog, tests, docs, migration notes, and rollback risk. Do not deploy.
---
 
# Release Readiness
 
## Workflow
 
1. Read release notes or changelog.
2. Check changed files and migration notes.
3. Verify relevant test / build commands.
4. Identify missing docs, rollback gaps, and risky dependencies.
 
## Output
 
- Ready / Not ready
- Blocking issues
- Non-blocking follow-ups
- Verification evidence
- Rollback notes

---
name: docs-drift-check
description: Use when checking whether docs match current repository commands, config, and source behavior. Report drift with evidence. Do not rewrite docs unless asked.
---
 
# Docs Drift Check
 
## Workflow
 
1. Read target docs.
2. Read source-of-truth files such as package.json, AGENTS.md, config, scripts, or official docs.
3. Compare claims with evidence.
4. Report drift and suggested edits.
 
## Output
 
- Document location
- Claim
- Source of truth
- Drift type
- Suggested correction

---
name: security-triage
description: Use when triaging a suspected security issue in code, config, MCP, plugins, automations, or cloud setup. Report impact and containment steps first.
---
 
# Security Triage
 
## Workflow
 
1. Identify asset, entry point, and affected scope.
2. Check whether secrets, production data, permissions, or external services are involved.
3. Separate confirmed facts from assumptions.
4. Recommend containment, verification, and follow-up.
 
## Output
 
- Severity
- Affected files / systems
- Evidence
- Immediate containment
- Follow-up fixes

- 一次性任务。
- 当前项目的临时 bug。
- 模糊人设包装。
- 需要每天变化的命令。
- 真实密钥或私有账号信息。

description: A powerful helper for many tasks.

description: Review Markdown course chapters for factual consistency, broken commands, missing learner steps, and Chinese readability. Use when editing docs or course material; do not use for source code review.

<Verb> <target artifact> for <specific outcome>. Use when <trigger>. Do not use when <non-goal>.

description: Prepare release notes from Git commits and PR summaries. Use when the user asks for changelog or release communication; do not use for code implementation.

.agents/skills/
  docs-drift/
    SKILL.md
    references/
      docs-style.md
      product-terms.md
    scripts/
      link_check.js
    assets/
      icon.png
    agents/
      openai.yaml

---
name: docs-drift
description: Check documentation against code, config, and recent changes. Use for docs drift review; do not use for general copywriting.
---
 
Workflow:
 
1. Identify the document scope.
2. Read nearby source files and config.
3. Compare commands, paths, feature names, and behavior claims.
4. Return confirmed drift, likely drift, and questions.

# Product Terms
 
Use "workspace" for the user's active project boundary.
Use "thread" for a Codex conversation.
Avoid calling plugins "extensions" in course material.

// scripts/check-links.js
// Check local Markdown links and print broken targets.

interface:
  display_name: "Docs Drift"
  short_description: "Check docs against code and config"
  brand_color: "#3B82F6"
  default_prompt: "Check this document for drift against the project."
 
policy:
  allow_implicit_invocation: false

1. description 的前半句最重要。
2. 不要把所有资料写进 description。
3. 长资料放 references，需要时再读。

- 每个 Skill 只做一件事。
- 禁用不常用或不相关 Skill。
- 把同类 Skill 打包进 Plugin。
- 用清晰 description 避免互相抢触发。
- 对高风险 Skill 关闭 implicit invocation。

## Commands
 
- Test docs links: `pnpm docs:links`
- Lint Markdown: `pnpm docs:lint`

---
name: docs-drift
description: Check docs against project source and config.
---
 
Workflow:
 
1. Read the target doc.
2. Use AGENTS.md commands when verification is needed.
3. Compare claims against source and config.
4. Return drift findings and suggested edits.

/plan
我准备使用 $docs-drift 检查 docs/codex。
请先规划要读哪些文件和如何分批执行。
不要修改文件。

$docs-drift
每周一检查 docs/ 是否和代码、配置、README 不一致。
默认只读。
有发现时进入 Triage，没有发现时归档。

{
  "name": "course-authoring-pack",
  "version": "1.0.0",
  "description": "Course authoring workflows for Codex.",
  "skills": "./skills/"
}

---
name: course-chapter-review
description: Review Chinese course chapters for learner flow, factual accuracy, command correctness, missing examples, and natural tone. Use for Markdown course material; do not use for code review.
---
 
Workflow:
 
1. Identify the target learner and chapter goal.
2. Read the chapter headings before editing.
3. Check whether examples match the feature being taught.
4. Flag commands or feature claims that need source verification.
5. Improve learner flow before polishing language.
6. Do not add screenshot placeholders.
 
Output:
 
- Key issues
- Suggested edits
- Questions that need source verification

$course-chapter-review
请审查 docs/codex/CX-05-Codex-MCP外部工具完整指南.md。
重点看新手是否能按章节一步步学会 MCP。
不要直接改文件，先给问题列表。

---
name: pr-risk-review
description: Review a pull request or Git diff for behavior regression, security risk, missing tests, and review readiness. Use when the user asks for PR or diff review.
---
 
Workflow:
 
1. Read the diff and nearby files.
2. Identify user-visible behavior changes.
3. Prioritize correctness, security, and test gaps.
4. Avoid style-only findings unless they affect maintainability.
5. Return findings first, then questions.

$pr-risk-review
请审查当前分支相对 main 的 diff。
不要修改文件。
只输出真实风险和需要我判断的问题。

---
name: release-notes
description: Draft release notes from commits, PR summaries, and product impact notes. Use for changelog and release communication; do not use for implementation.
---
 
Workflow:
 
1. Gather commits or PR summaries.
2. Group changes by user impact.
3. Separate features, fixes, docs, and internal changes.
4. Avoid exaggeration.
5. Call out migration or risk notes when present.

$release-notes
请根据最近 10 个 commit 生成中文发布说明。
不要编造用户影响。
如果 commit 信息不足，请列出需要补充的问题。

我的 Skill 没有按预期触发。
请帮我检查：
1. name 和 description 是否清楚
2. 这个任务是否应该显式用 `$skill`
3. 是否有其它 Skill 抢触发
4. `SKILL.md` 是否缺少输入、步骤或输出
5. 是否应该把长资料移到 references

- 触发是否准确。
- 输出是否稳定。
- 里面的命令是否还存在。
- references 是否过期。
- scripts 是否还能跑。
- 是否应该升级成 Plugin。

# Skill Change Note
 
Skill: docs-drift
 
## Why
 
The previous workflow missed package script drift.
 
## Changed
 
- Added package metadata check.
- Added output section for uncertain claims.
 
## How to try
 
Use `$docs-drift` on README and package.json.

1. 先用普通 prompt 跑 3 次。
2. 确认流程稳定。
3. 写 `SKILL.md`。
4. 用显式 `$skill` 测试。
5. 再考虑 implicit invocation。
6. 多人使用后再打包 Plugin。

请审查这篇中文课程文档。
看看有没有事实错误、命令过期、步骤跳跃、术语不一致、表达太像 AI 的地方。
先给问题，再给修改建议。

Use when:
- 审查中文课程文档
- 检查教程章节
- 对比命令和事实
 
Do not use when:
- 审查源代码
- 写营销文案
- 生成图片或视频

---
name: zh-course-review
description: Review Chinese technical course chapters for factual accuracy, command correctness, learner flow, terminology consistency, and natural tone. Use for Markdown course material; do not use for source code review.
---
 
Workflow:
 
1. Read the chapter title, learning goals, and heading structure.
2. Identify the target learner.
3. Check commands, paths, and feature claims against available sources.
4. Look for missing hands-on steps.
5. Separate factual issues from writing improvements.
6. Keep edits course-facing and learner-facing.
 
Output:
 
- Key issues
- Suggested structure improvements
- Fact checks needed
- Rewrite suggestions

$zh-course-review
请审查 docs/codex/CX-03-Codex-Commands工作流入口完整指南.md。
不要修改文件，先给审查结果。

When reviewing command examples:
 
- Flag commands that may not exist in Codex.
- Prefer current official command names.
- Distinguish App commands, CLI commands, Skills, Plugins, and MCP.

为什么“今天修 checkout bug”不应该做成 Skill？
为什么“PR 风险审查流程”适合做成 Skill？
为什么每周检查 docs 不是单独 Skill，而是 Automation + Skill？

# Skill Owner Note
 
Skill:
Owner:
Primary users:
Trigger:
Non-goals:
Known failure modes:
Last reviewed:

name: helper
description: Help with all project tasks.

name: pr-risk-review
description: Review Git diffs for correctness, security risk, missing tests, and scope creep. Use when preparing a PR; do not use for implementation.

name: prod-db-fixer
description: Fix production database issues automatically.

帮我看一下这个 PR 有没有风险。

name: pr-helper
description: Help with PRs.

- 触发太宽，什么 PR 任务都可能误用。
- 没说只读还是可写。
- 没说输出格式。
- 没说风险优先级。
- 没说不应该做什么。

name: pr-risk-review
description: Review Git diffs for correctness, security risk, missing tests, and scope creep. Use before opening or updating a PR. This skill is read-only and should not implement fixes.

# PR Risk Review
 
## When To Use
 
Use when the user is preparing a PR, updating a PR after comments, or deciding whether a diff is safe to submit.
 
## Workflow
 
1. Read the user's stated PR goal.
2. Inspect the current diff or provided files.
3. Classify findings by severity.
4. Check for scope creep and missing tests.
5. Return actionable findings with file evidence.
 
## Do Not
 
- Modify files.
- Stage, commit, push, or reply to external reviewers.
- Invent test results.
- Comment on style unless it affects behavior or reviewability.
 
## Output
 
Return:
 
- Summary
- Findings
- Missing verification
- Scope concerns
- Suggested next prompt

$pr-risk-review
请审查当前 diff，重点看 auth redirect、测试覆盖和是否有无关改动。

name: fix-today-checkout-bug
description: Fix today's checkout bug in branch kim/test.

- 带有今天、具体分支、具体事故。
- 过期很快。
- 没有复用价值。

请修复当前分支的 checkout bug。
范围：只改 checkout flow 和相关测试。
修完后运行 checkout 相关测试。

name: think-better
description: Think deeply before doing any task.

- 无法判断何时触发。
- 没有明确输入输出。
- 会和所有任务抢上下文。

name: prod-hotfix
description: Fix production incidents automatically.

name: incident-readonly-triage
description: Summarize incident context, logs, likely code areas, and safe next questions. Use during incident analysis. Do not execute production actions.

1. 总结现象。
2. 读取允许的日志或本地材料。
3. 标出可能影响范围。
4. 给出下一步人工决策。
5. 明确不执行回滚、发布、封禁或生产写入。

1. 这次改动解决什么重复问题？
2. 会影响哪些使用场景？
3. 如果效果变差，怎么退回？

# Skill Changelog
 
## 2026-06-09
 
Changed:
 
- Added "scope concerns" to PR risk output.
- Clarified that the skill is read-only.
 
Why:
 
- Reviewers kept missing unrelated cleanup in large PRs.
 
Watch:
 
- If output becomes too long, split findings into blocking and follow-up.

请分析这个 Skill 的三次失败输出。
 
目标：
1. 找出是触发条件不清楚、workflow 不清楚，还是用户输入不够。
2. 建议修改 SKILL.md 的哪一段。
3. 不要重写整个 Skill。

# Skill Owner Note
 
Skill: pr-risk-review
Owner: Engineering Productivity
Primary users: feature teams before PR update
Trigger: preparing or updating a PR
Non-goals: implementation, commit, external replies
Known failure modes: too many style comments, missing security angle
Last reviewed: 2026-06-09

name: docs-helper
description: Help with docs.

name: docs-drift-review
description: Compare documentation against repository code and scripts. Use when checking whether README, docs, or examples are outdated. This skill is read-only unless the user asks for a specific documentation edit.

帮我看看文档。

$docs-drift-review
请检查 README 的安装命令是否和 package scripts 一致。
只读输出问题，不要修改文件。

1. Skill 是否在 `.agents/skills` 或用户/插件可发现位置。
2. `SKILL.md` frontmatter 的 name 是否清楚。
3. description 是否描述了触发场景，而不是性格。
4. 是否有多个同名 Skill 让选择变混乱。
5. App 是否需要 reload skills。

我希望你使用 `$docs-drift-review`。
请先说明你是否能看到这个 Skill。
如果能看到，请按它的 workflow 执行。
如果不能看到，请告诉我可能的安装或发现问题。
不要改文件。

## Output
 
Give useful suggestions.

## Output
 
Return exactly these sections:
 
1. Summary
2. Blocking Issues
3. Follow-up Suggestions
4. Files Referenced
5. Suggested Next Prompt
 
Rules:
 
- Each Blocking Issue must include a file path or evidence.
- Do not include more than 5 Follow-up Suggestions.
- If no issue is found, say "No obvious drift found" and stop.

请分析这个 Skill 的输出为什么太散。
 
重点看：
1. output section 是否清楚。
2. 是否限制数量。
3. 是否要求证据。
4. 是否定义没有发现时怎么回答。
5. 是否把实现和审查混在一起。

.agents/skills/my-skill/
  SKILL.md          # 入口、流程、规则
  references/       # 参考文档
  scripts/          # 可选脚本