team-skills

v1.6.2

Published

14 days ago

AI Agent Skills framework — Spec-Driven development with directed-graph rollback and quality gates

0High
0Medium
0Low

andeya

ai agent skills spec-driven tdd claude cursor code-review ai-collaboration

Team Skills

让 AI Agent 团队像专业开发团队一样协作

Spec-Driven · 有向图回退 · 质量门禁

🤔 你是否有过这些经历？

| 场景 | 传统做法 | 结果 | |------|----------|------| | 给 AI 一句话就写代码 | AI 产出随机，改 5 轮才接近需求 | ❌ 浪费时间 | | AI 说"测试通过了" | 你相信了，结果 CI 全红 | ❌ 信任崩塌 | | Review 发现 bug | 只能手动修，没有回退机制 | ❌ 重复劳动 | | 换了 session 一切归零 | 规则不沉淀，每次从零开始 | ❌ 没有积累 | | 不知道项目做得好不好 | 凭感觉判断 | ❌ 无法量化 |

Team Skills 用工程化的方式解决了这些问题。

✨ 为什么 Team Skills 与众不同？

🎯 Spec-Driven，不是 Chat-Driven

传统方式：用户 → AI（一句话）→ 代码（随机产出）
Team Skills：用户 → CONFIRM_GOAL → SDD 规格 → CONFIRM_SPEC → TDD 实现 → 测试 → Review → HUMAN_ACCEPT

每个环节有明确的输入/输出标准，AI 不是"猜需求"，而是执行规格。

🔄 有向图回退，不是线性流水线

team-test 发现 bug ──→ 自动回退 team-impl
team-review 发现 spec 遗漏 ──→ 自动回退 team-spec
同一阶段回退 ≤ 2 次，超过触发人类介入

发现问题立即回退，不是"先记着后面修"。

🛡️ 质量门禁，不是"我觉得"

5 步验证协议：确定命令 → 新鲜执行 → 完整阅读 → 检查退出码 → 声明通过
9 条 Constitutional Rules：不可覆盖的硬约束
反规避条款：预判 9 种常见借口并逐一反驳
三视角对抗审查：攻击者/怀疑者/用户视角反向验证

📝 规则沉淀，不是"每次从零"

三层规则体系：项目级 → 模块级 → 任务级，冲突按优先级覆盖
消费方契约：每条规则含触发条件 + 可执行指令 + 示例，下游 Skill 可直接执行

📊 量化评估，不是"凭感觉"

7 硬门禁 + 24 评分项：五维度 100 分制量化打分
反虚构规则：占位符 >20% 或有效行 <10 → 判定 0 分

🚀 安装

前置条件

Node.js >= 18
Claude Code 或 Cursor：至少安装其中之一

一键安装（推荐）

npx team-skills@latest setup

自动将 Skills 以 symlink 方式安装到全局目录（Skills 安装后即为 IDE 斜杠命令）。

启用可选的项目评分功能（team-score）：

npx team-skills@latest setup --with-score

全局安装后可直接在终端调用：

npm i -g team-skills
team-skills setup

初始化到项目（可选）

将 Skills 复制到项目中，支持版本控制和自定义：

npx team-skills@latest init
# 含评分功能
npx team-skills@latest init --with-score

自动检测项目中的 .claude/ 和 .cursor/ 目录，将对应文件复制到 IDE 能发现的位置。后续更新：

npx team-skills@latest update

提示：全局安装（setup）和项目初始化（init）的区别在于：setup 使用 symlink 指向包源文件，init 复制文件到项目中支持版本控制和自定义。

安装内容

| 内容 | 位置 | 说明 | |------|------|------| | 13 个 Agent Skills | ~/.agents/skills/ + ~/.claude/skills/ | Cursor / Claude Code 自动发现（team-score 需 --with-score） | | 共享规则 | ~/.agents/skills/_team-rules/ + ~/.claude/skills/_team-rules/ | 被所有 Skill 引用 |

验证

# 在 Claude Code / Cursor 中输入 / 查看 team- 开头的命令
/using-team-skills

CLI 参考

| 命令 | 说明 | 关键选项 | |------|------|----------| | team-skills setup | symlink 安装到全局目录 | --with-score --force | | team-skills init [dir] | 复制到项目 IDE 目录 | --ide <claude\|cursor\|both> --with-score | | team-skills update [dir] | 升级包 + 更新项目副本 | --skip-self --ide --with-score | | team-skills uninstall | 移除所有全局 symlink | — | | team-skills list | 查看全局安装状态 | --json |

所有命令支持 --dry-run。

📖 使用方式

全自动编排（推荐）

一条命令启动完整流水线，适合从零开始的功能开发：

/team-orchestrator 实现用户登录功能

编排器自动完成：CONFIRM_GOAL 确认目标 → team-spec 产出 SDD → CONFIRM_SPEC 确认规格 → team-impl TDD 实现 → team-test 四维测试 → team-review 五维审查 → 分支完成处理 → HUMAN_ACCEPT 验收交付

简单任务可用精简模式：

/team-orchestrator --compact 修复登录页按钮样式

按需调用单个 Skill

| 场景 | 命令 | |------|------| | 需求模糊，需要讨论 | /team-brainstorm 这个功能怎么做？ | | 一句话需求展开为规格 | /team-spec 实现登录功能 | | 已有规格，开始编码 | /team-impl | | 测试覆盖够吗？ | /team-test | | 代码质量如何？ | /team-review | | Review 反馈来了 | /team-feedback | | 这个 bug 怎么回事？ | /team-debug | | 测试真的过了吗？ | /team-verify | | 代码写完了 | /team-finish | | AI 安全合规检查 | /team-security | | 项目做得好不好？ | /team-score | | 不知道用哪个 | /using-team-skills |

🏗️ 核心架构

flowchart TD
    classDef human fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0;
    classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
    classDef git fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef kill fill:#ffebee,stroke:#c62828,stroke-width:2px,stroke-dasharray: 5 5,color:#b71c1c;

    START(("用户提出需求"))
    CG["CONFIRM_GOAL<br/>人类确认目标理解"]:::human
    BRANCH["创建功能分支<br/>{slug} 分支"]:::git
    SPEC["team-spec — 规格制定<br/>产出 01-05 + prompt-template<br/>Socratic 提问 → SDD 规格"]:::agent
    CS["CONFIRM_SPEC<br/>人类确认规格方案"]:::human
    IMPL["team-impl — TDD 实现<br/>红-绿-重构循环<br/>增量提交 + 决策记录"]:::agent
    TEST["team-test — 四维测试<br/>功能/边界/异常/代码分支"]:::agent
    REVIEW["team-review — 五维审查<br/>资产沉淀 + 复盘"]:::agent
    FINISH["team-finish — 分支完成<br/>merge / PR / keep"]:::git
    HA["HUMAN_ACCEPT<br/>人类验收交付物"]:::human
    AH("ASK_HUMAN<br/>阻塞 / 决策 / Kill Switch"):::human

    START --> CG
    CG -->|确认| BRANCH
    CG -->|不确认| START

    BRANCH --> SPEC
    SPEC --> CS
    CS -->|确认| IMPL
    CS -->|不确认| SPEC
    CS -.->|Kill Switch| AH

    IMPL --> TEST

    TEST -->|全部通过| REVIEW
    TEST -->|发现 bug| IMPL
    TEST -->|spec 遗漏| SPEC
    TEST -.->|不可行| AH

    REVIEW -->|无问题| FINISH
    REVIEW -->|P0/P1| IMPL
    REVIEW -->|spec 遗漏| SPEC
    REVIEW -.->|不可行| AH

    FINISH --> HA
    HA -->|验收通过| DONE(("完成 ✅"))
    HA -->|不通过| IMPL

ASK_HUMAN 可在任何阶段触发，包括：发现任务不可行（Kill Switch）、回退超限、或需要人类决策的复杂问题。功能分支在 CONFIRM_GOAL 确认后自动创建，在 Review 通过后由 team-finish 处理（merge/PR/keep/discard）。

🗺️ Skill 使用地图

从你的场景出发，找到对应的 Skill。

graph TD
    classDef user fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#1565c0;
    classDef skill fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
    classDef orch fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#bf360c;

    YOU((👤 你)):::user
    YOU -->|"判断你的场景"| Q{你处于哪个阶段？}

    Q -->|"需求模糊，需要讨论"| BRAIN[🧠 team-brainstorm<br/>→ 设计思路]:::skill
    Q -->|"需求明确，需要规格"| SPEC[📝 team-spec<br/>→ SDD 规格文档]:::skill
    Q -->|"规格就绪，需要实现"| IMPL[💻 team-impl<br/>→ 代码 + TDD 日志]:::skill
    Q -->|"实现完成，需要测试"| TEST[🧪 team-test<br/>→ 四维测试报告]:::skill
    Q -->|"代码就绪，需要审查"| REVIEW[🔍 team-review<br/>→ 五维审查报告]:::skill
    Q -->|"收到审查反馈"| FB[💬 team-feedback<br/>→ 修改方案]:::skill
    Q -->|"遇到 Bug"| DEBUG[🐛 team-debug<br/>→ 根因分析 + 修复]:::skill
    Q -->|"声称完成"| VERIFY[✅ team-verify<br/>→ 验证证据链]:::skill
    Q -->|"实现完成，准备合并"| FINISH[🏁 team-finish<br/>→ 合并/PR/清理]:::skill
    Q -->|"项目做得好不好"| SCORE[📊 team-score<br/>→ 量化评分报告]:::skill
    Q -->|"AI 安全合规检查"| SECURITY[🔒 team-security<br/>→ 安全审计报告]:::skill
    Q -->|"不知道用哪个"| USING[🧭 using-team-skills<br/>→ Skill 推荐]:::skill
    Q -->|"需要完整交付流水线"| ORCH[⚙️ team-orchestrator<br/>→ 全自动编排]:::orch

    ORCH -.->|自动调度| SPEC
    ORCH -.->|自动调度| IMPL
    ORCH -.->|自动调度| TEST
    ORCH -.->|自动调度| REVIEW
    ORCH -.->|自动调度| FINISH
    SCORE -.->|评分时调度| SECURITY

实线 = 你主动调用；虚线 = 编排器自动调度。每个节点下方标注了产出物。

📦 包含 13 个可独立使用的 Skill

| Skill | 一句话说明 | 使用场景 | |-------|-----------|----------| | team-brainstorm | 需求模糊时讨论形成方案 | "这个功能怎么做？" | | team-spec | 一句话需求展开为完整 SDD 规格 | "实现登录功能" | | team-impl | TDD 红-绿-重构循环实现 | "规格有了，开始写代码" | | team-test | 四维测试矩阵 + 补充测试 | "测试覆盖够吗？" | | team-review | 五维审查 + 资产沉淀 + 复盘 | "代码质量如何？" | | team-feedback | 先验证再实施，非表演性同意 | "Review 反馈来了" | | team-debug | 四阶段根因分析 + 修复 | "这个 bug 怎么回事？" | | team-verify | 5 步验证门禁，杜绝虚假通过 | "测试真的过了吗？" | | team-finish | 分支完成处理（合并/PR/保留/丢弃） | "代码写完了" | | team-orchestrator | 有向图流程编排 + 分支管理，4 个人类介入点 | "我要完整交付流水线" | | team-score | 7 硬门禁 + 24 项五维度评分（100 分制） | "项目做得好不好？" | | team-security | AI 安全红线合规检查（6+4 红线 + 6 场景） | "AI 使用安全吗？" | | using-team-skills | Meta-skill，自动引导你选正确的 Skill | "我该用哪个？" |

每个 Skill 可独立使用，也可通过 team-orchestrator 串联成完整流水线。team-score 为可选评估工具，安装时需 --with-score。

📋 结构化文档体系

团队协作过程中产出的所有文档，统一存放在 docs/ 目录下：

docs/
├── tasks/                          # 任务文档（核心目录）
│   ├── progress.md                 # 进度账本 — 所有任务的状态追踪表
│   │
│   ├── {NNNN}-{keyword}/           # 单个任务目录（最多产出 18 个结构化文档）
│   │   ├── 00-design-brief.md      #   设计概要（team-brainstorm 产出，可选）
│   │   ├── 01-plan.md              #   任务规划（目标 + 分期 + 预算）
│   │   ├── 02-context.md           #   上下文选择（术语 + 引用 + 排除）
│   │   ├── 03-sdd.md              #   SDD 规格（九章节完整）
│   │   ├── 04-boundary.md          #   修改边界（allow + deny）
│   │   ├── 05-risk.md              #   风险 + 验证计划
│   │   ├── prompt-template.md      #   AI 任务提示词模板
│   │   ├── 06-tdd-log.md           #   TDD 日志（红-绿-重构循环）
│   │   ├── 07-prompt-log.md        #   Prompt 工程记录（五要素 + 纠偏）
│   │   ├── 08-ai-decisions.md      #   AI 决策记录（选择 + 拒绝 + 理由）
│   │   ├── 09-test-matrix.md       #   四维测试矩阵
│   │   ├── 10-test-report.md       #   测试运行报告（证据链）
│   │   ├── 11-review.md            #   代码审查报告（五维度 + 合规）
│   │   ├── 12-asset-update.md      #   资产更新记录（消费方契约）
│   │   ├── 13-retrospective.md     #   个人复盘（新规则沉淀）
│   │   ├── task-rules.md           #   任务级规则
│   │   ├── 14-team.md              #   团队协作记录
│   │   └── 15-brief.md             #   答辩提纲
│   │
│   └── ...                         # 更多任务目录
│
├── review-checklist.md             # Review 检查清单（项目级，跨任务累积）
├── delivery-checklist.md           # 交付检查清单（项目级，跨任务累积）
├── security-audit.md               # AI 安全红线合规审计报告（team-security 产出）
└── specs/                          # SDD 归档（任务验收通过后存档）

文档职责分层

| 层级 | 目录 | 生命周期 | 说明 | |------|------|----------|------| | 进度追踪 | tasks/progress.md | 持续更新 | 防止跨 session 任务重复派发，记录所有任务状态 | | 任务文档 | tasks/{slug}/ | 随任务创建 | 每个任务独立目录，slug 格式 {NNNN}-{keyword} | | 项目级清单 | review-checklist.md | 跨任务累积 | 每次 Review 发现新检查项后追加，持续积累 | | 项目级清单 | delivery-checklist.md | 跨任务累积 | 每次交付发现新检查项后追加，持续积累 | | 安全审计 | security-audit.md | 每次重写 | team-security 产出的 AI 安全红线合规审计报告 | | 规格归档 | specs/ | 验收后存档 | SDD 快照归档，供后续任务参考 |

任务文档产出阶段

| 阶段 | 产出文件 | 负责 Skill | |------|----------|------------| | 头脑风暴 | 00-design-brief.md | team-brainstorm | | 规格设计 | 01-plan.md ~ 05-risk.md + prompt-template.md | team-spec | | TDD 实现 | 06-tdd-log.md ~ 08-ai-decisions.md | team-impl | | 测试审计 | 09-test-matrix.md ~ 10-test-report.md | team-test | | 代码审查 | 11-review.md ~ 13-retrospective.md + task-rules.md | team-review | | 安全审计 | docs/security-audit.md | team-security | | 团队交付 | 14-team.md + 15-brief.md | team-orchestrator |

📚 体系来源

Team Skills 融合了业界多个 AI 协作框架的精华：

| 来源 | 吸收的精华 | |------|-----------| | SuperPowers (obra) | 5 步验证协议、四态完成状态、反规避条款、Socratic 探索 | | OpenSpec (Fission AI) | Delta Spec 增量规格、RFC 2119 + Given/When/Then | | Karpathy Skills | 过度抽象防御、死代码清理、困惑管理 | | Agent-Style | 5 条 LLM 输出质量约束 | | 独创 | 有向图回退、质量追溯矩阵、消费方契约、CONFIRM_GOAL-HUMAN_ACCEPT 人类介入点、100 分制量化评估、Skill Spec Language（21 条设计原则） |

推荐：禁用 EnterPlanMode（Claude Code）

Team Skills 的每个 Skill 都定义了完整的结构化工作流（Phase/Step），不需要 Claude Code 的 EnterPlanMode。长对话中 LLM 可能自动切入 plan mode，绕过 Skill 流程（跳过 TDD、根因调查、有向图调度等纪律流程）。

在项目的 .claude/settings.json 中添加 PreToolUse Hook 可彻底阻止：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "EnterPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: team-skills STEPS 是完整工作流，不需要 EnterPlanMode。' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

exit 2 会阻止工具调用并将 stderr 消息反馈给 LLM。此 Hook 仅影响当前项目，不影响其他项目中 EnterPlanMode 的正常使用。

🔧 本地开发

git clone https://github.com/andeya/team-skills.git
cd team-skills
npm install

开发命令

npm run lint       # 检查 Markdown 格式 + Skill 结构完整性（CI 同款）
npm run format     # 自动修复 Markdown 格式
npm run cli-test   # CLI 冒烟测试
npm run setup      # 安装 Skills 到全局目录

Skill 编写规范

编写或修改 Skill 时，请参考 CLAUDE.md §2.7（Skill Spec：格式约定 + 关键词参考 + 设计原则）。

开发者斜杠命令（Claude Code）

在 Claude Code 中可使用以下开发者命令（仅限本仓库，不随 Skills 分发到用户项目）：

| 命令 | 说明 | 参数 | |------|------|------| | /team-refine | 改进飞轮：规范 ↔ SKILL.md 双向对抗审计（15 维度）+ LLM 执行质量打磨，逐轮收敛 | 轮次数，默认 5 | | /team-range | 逐文件遍历：对项目文件逐个执行指定操作，修改后重检直到干净 | --scope skills\|rules\|commands\|all\|<glob> + 操作描述 | | /team-release | 版本发布：更新 package.json + CHANGELOG，运行 install/format/lint/cli-test | patch / minor / major / x.y.z |

CI 流程

提交后 GitHub Actions 自动运行：

| Workflow | Job | 说明 | |----------|-----|------| | CI | Lint | Markdown 格式 + Skill 结构检查 | | CI | CLI Smoke Test | CLI 功能验证 | | CI | Check Links | 外部链接有效性 | | Release | Publish to npm | v* tag 触发，自动发布到 npm |

🤝 贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

如果 Team Skills 对你有帮助，请给一个 ⭐ — 让更多人看到工程化的 AI 协作方式。