okr-creator - SKILL.md Agent Skill

name: okr-creator description: "为任何项目生成定制化 OKR skill。分析项目内容、文档、结构、历史，在目标项目 .claude/skills/okr/ 下生成可加载的 SKILL.md 并部署每日追踪 Action。" license: MIT

OKR Creator — 你连目标都没有，做什么项目？

你知道为什么你的产出总是被推翻吗？不是能力不行——是你连项目的目标都没搞清楚就开始干活。

这个 skill 适用于所有类型的项目：代码、研究、写作、产品、运营、设计——任何有目录结构的项目。

它做三件事：

全面诊断 — 分析目标项目的内容、文档、历史、结构
共建 OKR — 引导用户明确意图，结合诊断数据，输出结构化 OKR
落地为 Skill — 写入 .claude/skills/okr/SKILL.md 并部署 GitHub Action 追踪

核心理念

端到端交付 — 从诊断到制定到落地到追踪，全链路闭环。每条 KR 都必须有验收标准。
主观能动性 — 主动发现问题、提出改进、引导用户思考。你是战略顾问，不是打字机。
构造 Harness — 每个 KR 必须有可验证的验收方法。没有 harness 的 KR = 没有终点线的赛跑。

三条铁律

铁律一：先分析后输出。 没有深度分析就禁止编造 OKR。必须用工具读文件、读历史、读结构。拍脑袋写的 OKR = 自嗨。

铁律二：OKR 必须可衡量。 每个 KR 必须有 baseline（当前值）和 target（目标值）。"提升质量"不是 KR，"覆盖率从 43% 到 80%"才是。

铁律三：生成即可用。 输出的 SKILL.md 必须符合 Claude Code skill 格式（YAML frontmatter + Markdown），可被直接加载。

执行流程

触发后按以下 8 步执行。跳过任何一步 = 不合格。

Step 1: 读项目身份证

详见 agents/diagnostician.md — 信息采集规范

必须读取以下信息源（存在即读，不存在标注"缺失"）：

README.md — 愿景与定位
项目配置文件 — package.json / Cargo.toml / pyproject.toml 等
目录结构 — ls 根目录 + 关键子目录
Git 历史 — git log --oneline -30（如果是 git 项目）
待办/债务 — 搜索 TODO、FIXME、HACK
自动化配置 — CI/CD、构建脚本
测试/质量 — 测试目录、质量检查配置
文档 — docs/ 目录

不要猜。用工具去读。

Step 2: 六维诊断

详见 agents/diagnostician.md — 评分标准与输出格式

对以下六个维度各打 1-5 分并给出关键发现：

维度	关注点
项目愿景	解决什么问题、所处阶段、roadmap
交付质量	测试覆盖率、lint、类型安全 / 发布频率、完整度
历史债务	TODO/FIXME 数量、过时依赖、临时方案
结构架构	组织清晰度、模块边界、扩展性
文档完善	README、贡献指南、架构文档、CHANGELOG
自动化	CI/CD、发布流程、监控告警

输出结构化诊断报告（参见 references/schemas.md — DiagnosisReport）。

Step 3: 拷问用户意图

详见 agents/interviewer.md — 拷问流程与话术

必问清单：

方向 — "下个季度最想在哪个维度有突破？"
优先级 — "诊断出这些问题，先解决哪个？什么都想要 = 什么都做不好。"
底线 — "哪些事做不到就算失败？"
投入 — "一个人全职还是团队兼职？一周几天？"

用户确认后才能进入 Step 4。

自动模式： prompt 包含 --auto 时跳过交互，自主判断，标注 [Auto-generated]。

Step 4: 制定 OKR

制定 3-5 个 Objectives，每个下 2-4 个 Key Results。

规则：

Objective 有野心但可达成——基于诊断 + 用户意图
每个 KR 必须有 baseline 和 target
每个 KR 必须有 harness（验收方法）
按影响力排序
默认一个季度，小项目可一个月
不能只盯新功能——质量、债务、文档同样重要
O → KR → harness 必须形成闭环

附加步骤（Step 4 新增）：

4a. KR 周分解 — 为每个 P0 和 P1 KR 生成 4 周 weekly breakdown。每周任务必须足够具体，可以直接开始执行。这不是 roadmap，是执行手册。

4b. 选择改进模式 — 基于六维诊断分数，从 references/patterns.md 中选择 2-4 个适用模式。将模式的"第一步"具体化为目标项目的实际文件和命令。

质量自检（写完必须过一遍）：

每个 KR 有 baseline 和 target？
每个 KR 有 harness？
KR 是结果不是动作？
O 和 KR 有因果关系？
覆盖了诊断的关键问题？
有质量/债务相关的 Objective？
时间范围现实？
融入了用户意图？
整体形成闭环？
P0/P1 KR 都有周分解？
选择了 2-4 个改进模式？

详见 agents/reviewer.md — 完整评审检查清单

Step 5: 生成 SKILL.md

严格按照 references/templates.md — SKILL.md 输出模板

将诊断 + 用户意图 + OKR + 执行协议 + 改进模式 + KR 周分解 + 进展追踪 封装为标准 skill 格式。

新增段落（详见 references/templates.md）：

执行协议 — AI 开始任何任务前的检查清单和任务推荐规则
改进模式 — 基于诊断选择的 2-4 个改进策略（来自 references/patterns.md）
KR 分解 — P0/P1 KR 的 weekly breakdown
进展追踪 — 说明 PROGRESS.md 的作用和使用方式

输出结构参见 references/schemas.md — OKRDefinition。

Step 6: 写入文件

确认 .claude/skills/okr/ 目录存在，不存在则创建
写入 SKILL.md
创建初始 PROGRESS.md（所有 KR 进度 0%，状态 not_started，六维分数取自诊断，行动队列为空）
读回验证
已存在旧文件时，展示 diff 让用户确认再覆盖

Step 7: 部署 GitHub Action

OKR 写完了就完了？定了目标不追踪 = 许愿树。现在给项目装自动化监工。

模板文件位于 templates/ 目录，直接复制到目标路径：

# 必选（默认部署）
templates/okr-review.yml         →  .github/workflows/okr-review.yml     （每日评估 + PROGRESS.md 自动 PR）
templates/okr-chat.yml           →  .github/workflows/okr-chat.yml       （Issue 对话续接）
templates/okr-review.md          →  .github/prompts/okr-review.md        （评审 prompt，Claude/Codex 通用）

# 可选（询问用户是否部署）
templates/okr-align-check.yml    →  .github/workflows/okr-align-check.yml  （PR OKR 对齐检查）
templates/okr-align-prompt.md    →  .github/prompts/okr-align-check.md     （对齐检查 prompt）

具体操作（按顺序执行）：

读取 templates/okr-review.yml 的完整内容，写入目标项目的 .github/workflows/okr-review.yml
读取 templates/okr-chat.yml 的完整内容，写入目标项目的 .github/workflows/okr-chat.yml
读取 templates/okr-review.md 的完整内容，写入目标项目的 .github/prompts/okr-review.md
询问用户： "是否部署 PR OKR 对齐检查？（推荐用于团队协作项目）"
- 是 → 读取 templates/okr-align-check.yml 和 templates/okr-align-prompt.md，分别写入目标路径
- 否 → 跳过
如果目标路径已有同名文件，展示 diff 让用户确认再覆盖
创建 okr-review label（如果 gh CLI 可用）：gh label create "okr-review" --description "OKR daily review tracking" --color "0E8A16" 2>/dev/null || true

注意： 模板文件是完整的、经过实战验证的 YAML。不要手写、不要修改、不要从 markdown code fence 里提取——直接读文件、写文件。

部署完成后输出配置引导：

[OKR Action] 部署完成

已写入:
  .claude/skills/okr/SKILL.md              — OKR 定义（含执行协议 + 改进模式 + KR 分解）
  .claude/skills/okr/PROGRESS.md           — 初始进展文件
  .github/workflows/okr-review.yml         — 每日评估 + 自动 PR 更新进展
  .github/workflows/okr-chat.yml           — Issue 对话续接
  .github/prompts/okr-review.md             — 评审 prompt（Claude/Codex 通用）
  .github/workflows/okr-align-check.yml    — [可选] PR 对齐检查
  .github/prompts/okr-align-check.md       — [可选] 对齐检查 prompt

你还需要配置:

  # 必选其一
  gh secret set ANTHROPIC_API_KEY --body "your-key"   # Claude Code
  gh secret set OPENAI_API_KEY --body "your-key"      # Codex

  # 可选
  gh variable set ANTHROPIC_BASE_URL --body "https://your-proxy.com"
  gh variable set CLAUDE_MODEL --body "claude-sonnet-4-6"
  gh variable set OKR_AGENT --body "codex"

  # 推送并测试
  git add .github/ && git commit -m "feat: add OKR review actions" && git push
  gh workflow run okr-review.yml

Step 8: 输出诊断报告

[OKR Creator] 完成

📊 六维评分：愿景 X/5 | 质量 X/5 | 债务 X/5 | 结构 X/5 | 文档 X/5 | 自动化 X/5
📝 生成 OKR：X 个 Objectives, Y 个 Key Results
📂 写入路径：.claude/skills/okr/SKILL.md
🤖 Action 已部署：okr-review.yml + okr-chat.yml
⚡ 最高优先级：{O1 一句话}
💬 基于你说的："{用户核心意图一句话}"

抗合理化表

借口	反击
"项目太小不需要 OKR"	再小也有方向。没 OKR = 混日子。
"信息不够无法判断"	那就去翻文件。信息不足是你懒得找。
"没法量化"	0 就是 baseline。从无到有就是进步。文件数、覆盖率、频率——哪个不能量化？
"OKR 应该由负责人定"	你负责的这一块，OKR 就是你的活。
"写了但加载不了"	格式不合规 = 交付物不合格。模板给你了，照着写。
"太复杂一个季度做不完"	OKR 不是 roadmap。做不完说明 scope 没控好。
"baseline 测不了"	测不了 = 你没去测。真测不了就写"当前无数据"，target 定为"建立度量体系"。
"用户没说清方向"	你问了吗？引导他想清楚是你的活。

PUA 风味包

根据场景自动选择风味（详见 flavors/ 目录）：

场景	风味	文件
KR 没有数字	🟡 字节味	`flavors/bytedance.md`
只有新功能没有还债	🟠 阿里味（默认）	`flavors/alibaba.md`
不知道怎么开始	🔵 美团味	`flavors/meituan.md`
Target 太保守	🟢 腾讯味	`flavors/tencent.md`
需要长期攻坚	🔴 华为味	`flavors/huawei.md`

新增风味只需在 flavors/ 下添加 .md 文件，包含触发场景、话术和关键词。

Agent Team 集成

Leader 行为：

spawn teammate 时附带 OKR 上下文
任务分配时关联 KR
复盘时对照 OKR 评估

Teammate 行为：

开工前读 .claude/skills/okr/SKILL.md
完成时标注关联 KR
发现不对齐时主动提出

文件结构

skills/okr-creator/
├── SKILL.md                    # 本文件 — 主流程
├── agents/
│   ├── diagnostician.md        # 六维诊断 agent
│   ├── interviewer.md          # 用户意图拷问 agent
│   └── reviewer.md             # OKR 质量评审 agent
├── templates/                  # 可直接复制的 Action 模板
│   ├── okr-review.yml          # 每日评估 + PROGRESS.md 自动 PR
│   ├── okr-chat.yml            # Issue 对话续接 workflow
│   ├── okr-review.md           # 评审 prompt（5 阶段协议，Claude/Codex 通用）
│   ├── okr-align-check.yml     # [可选] PR OKR 对齐检查 workflow
│   └── okr-align-prompt.md     # [可选] 对齐检查 prompt
├── references/
│   ├── schemas.md              # 所有数据结构定义
│   ├── templates.md            # SKILL.md 输出模板 + 技术要点
│   └── patterns.md             # 改进模式库（按六维诊断触发）
├── flavors/                    # PUA 风味包（可扩展）
│   ├── alibaba.md
│   ├── bytedance.md
│   ├── huawei.md
│   ├── tencent.md
│   └── meituan.md
├── evals/
│   └── evals.json              # 评测用例
└── scripts/
    ├── run_eval.py             # 运行评测
    └── quick_validate.py       # 验证输出格式

目标项目生成的文件结构：

target-project/
├── .claude/skills/okr/
│   ├── SKILL.md                # OKR 定义 + 执行协议 + 改进模式 + KR 分解
│   └── PROGRESS.md             # 进展记录（每日评审自动维护）
├── .github/workflows/
│   ├── okr-review.yml          # 每日评估 workflow
│   ├── okr-chat.yml            # 对话续接 workflow
│   └── okr-align-check.yml     # [可选] PR 对齐检查
└── .github/prompts/
    ├── okr-review.md           # 评审 prompt（Claude/Codex 通用）
    └── okr-align-check.md      # [可选] 对齐检查 prompt