1. 项目概述

sovereign-skills 是一个面向 Claude Code 的「主权技能」(sovereign-skills) 集合，提供从项目初始化到代码审查的完整 AI 协作工作流。该项目遵循"访谈优于模板、验证优于信任、范围先于代码、诚实报告、会话连续性"五大设计原则。资料来源：README.md:1-30

截至最新版本 v6.2，本仓库收录了 10 余个技能（Skill），按生命周期被划分为四类：Setup（一次性基础设施）、Daily Loop（每日循环）、On Demand（按需调用）和 Quality（质量审计）。资料来源：README.md:30-60

每个技能都是一个独立的目录，包含 SKILL.md（或 skill.md）作为主指令文件，以及可选的 agents/openai.yaml 用于多代理路由。例如 scope 技能定义任务范围与依赖关系，资料来源：scope/agents/openai.yaml:1-4；project-init 技能初始化新项目结构，资料来源：project-init/agents/openai.yaml:1-4；setup 技能配置运行时环境与依赖，资料来源：setup/agents/openai.yaml:1-4。

2. 安装与配置

2.1 作为 Marketplace 插件安装

本仓库在 .claude-plugin/marketplace.json 中注册为 Claude Code 的 Marketplace 插件源。安装流程：

1. 在 Claude Code 中添加 Marketplace 仓库地址：AlexZio00/sovereign-skills
2. 选择目标项目目录运行 /setup 或 /project-init
3. 技能自动从仓库内对应子目录加载

2.2 `/project-init` — 新项目引导

该技能通过一次一问的访谈生成 CLAUDE.md、ROADMAP、.gitignore、.env.example 等基础文件。访谈覆盖 Q1–Q7：项目一句话描述、语言/运行时、数据层、接口、部署、时间线与团队规模、Hard Rules。资料来源：project-init/skill.md:1-60

Discard 规则：已运行的产线项目若要替换 Hard Rules，应改用 /setup，而非 /project-init。资料来源：project-init/skill.md:30-50

生成的文件结构依据语言不同而变化，例如 Kotlin Spring Boot 项目会生成 controller/service/repository/domain 包结构，Go CLI 项目会生成 cmd/[app]/main.go。资料来源：project-init/skill.md:100-160

2.3 `/setup` — 基础设施与代理团队

/setup 在 /project-init 之上配置 Claude Code 的 harness 层——rules、hooks、memory、routing。它根据"项目规模"（Standard+、review gates 等条件）决定生成哪些文件。资料来源：setup/SKILL.md:1-30

关键产物包括 ~/.claude/rules/project rules、~/.claude/settings.json（合并 hooks）、memory/MEMORY.md 与 memory/session-handoff-LATEST.md。该技能的 Dominant Variable 是"生成的项目规则 Tier 0 规则能否通过违规测试"——没有测试的规则只是装饰。资料来源：setup/SKILL.md:30-60

3. 系统架构

3.1 技能目录结构

每个技能是一个自包含的子目录，统一使用 SKILL.md 承载主指令、agents/*.yaml 承载代理元数据。这种"一个技能一个目录"的约定使得技能可以独立分发、独立升级。

graph TD
    A[sovereign-skills 仓库] --> B[Setup 类]
    A --> C[Daily Loop 类]
    A --> D[On Demand 类]
    A --> E[Quality 类]
    B --> B1[project-init]
    B --> B2[setup]
    C --> C1[session-start]
    C --> C2[scope]
    C --> C3[freeze]
    C --> C4[goal-lock]
    C --> C5[pre-push]
    C --> C6[session-checkpoint]
    D --> D1[stepback]
    D --> D2[adr]
    D --> D3[brief]
    E --> E1[code-autopsy]
    E --> E2[project-check]
    E --> E3[collab-audit]

资料来源：README.md:30-80、scope/SKILL.md:1-20、freeze/agents/openai.yaml:1-4、goal-lock/SKILL.md:1-30

3.2 技能元数据规范

agents/openai.yaml 描述了技能的多代理路由信息，字段包括 name、description、instructions（指向 ../SKILL.md）。例如：

name: scope
description: "Define and document task scope, dependencies, and architectural boundaries."
instructions: "../SKILL.md"

资料来源：scope/agents/openai.yaml:1-4

3.3 生命周期流

README 中给出了完整的工作流图：Setup（一次性）→ 每日循环 → 按需调用 → 质量审计。每日循环的核心路径是 session-start → scope → freeze → goal-lock → work → stepback → code-autopsy → pre-push → session-checkpoint。资料来源：README.md:40-70

4. 核心技能一览

See Also

• 技能索引与最新发布说明：参考 README.md 中分类表
• 各技能详细指令：进入对应子目录的 SKILL.md
• 项目模板生成器：/project-init 的 Phase 3 文件模板
• 基础设施配置：/setup 的 7 行文件生成矩阵

概述与定位

sovereign-skills 仓库提供 12 个面向 Claude Code 完整生命周期的技能,位于项目启动阶段的有两个:project-init 与 setup。它们承担的职责截然不同却互相衔接——project-init 用于在空目录或早期原型中,通过采访式问答生成项目业务层的脚手架(CLAUDE.md、ROADMAP、.gitignore、.env.example);setup 用于在已有项目根目录之上装配 Claude Code 的 AI 编排层(rules、hooks、memory、agent routing)。README 明确指出两者都属于 skill_type: infrastructure 类别,并体现「interview over template」的核心设计原则:技能通过提问采集决策,再生成带有真实内容的文件,而非空骨架 资料来源:README.md。

project-init — 项目脚手架设计采访

project-init 的核心变量是「采访收集的决策是否准确反映到生成文件中」,若采访回答与最终生成的 CLAUDE.md/ROADMAP 内容不一致,项目便会基于错误前提启动 资料来源:project-init/skill.md。其执行流程分四个阶段:

• Phase 0 — 上下文检查:检测当前工作目录是否存在 CLAUDE.md。若已存在,询问用户「更新 / 重新写入 / 取消」,避免覆盖既有内容 资料来源:project-init/skill.md。
• Phase 1 — 采访:逐题询问语言/运行时、数据层、交互接口、部署目标、项目规模与团队、Hard Rules 等关键决策。每题附带决策指引,例如 Python 适合数据/ML/自动化,TypeScript 适合 Web/API 全栈统一,Go 适合高性能服务与 CLI 工具 资料来源:project-init/skill.md。
• Phase 2 — 栈决策摘要:汇总采访答案并要求用户显式确认,确认后方可进入生成阶段,避免在未对齐时即落盘 资料来源:project-init/skill.md。
• Phase 3 — 文件生成:按语言生成定制化的 CLAUDE.md、docs/DEVELOPMENT_ROADMAP.md、.gitignore 与(按需).env.example;目录布局也按 Python、TypeScript、Kotlin-后端、Kotlin-Android、Go 等分别给出 资料来源:project-init/skill.md。

触发词涵盖 /project-init、韩语「새 프로젝트」「프로젝트 셋업」、英语 project setup、new project 等 资料来源:project-init/skill.md。OpenAI 端代理元数据通过 instructions: "../SKILL.md" 复用同一份技能定义,使 Codex 与 Claude 共享行为契约 资料来源:project-init/agents/openai.yaml。

setup — Claude Code 基础设施与代理团队配置

setup 的核心变量是「初始化后的 harness 能否在下一会话立即生效」,rules/hooks/memory/routing 必须从安装后的第一个 session 起即可用,否则视为失败 资料来源:setup/SKILL.md。与 project-init 关注业务脚手架不同,setup 装配的是 AI 协作层:

• 生成 ~/.claude/rules/project rules、agents.md(Standard+ 项目)、output-style.md、development-workflow.md(含 review gates 的项目)等规则文件。其中 Tier 0 规则必须通过违规测试,未测试的规则仅是装饰 资料来源:setup/SKILL.md。
• 合并 ~/.claude/settings.json 中的 hooks,并初始化 memory/MEMORY.md 与 memory/session-handoff-LATEST.md,为后续 session-start / session-checkpoint 提供上下文载体 资料来源:setup/SKILL.md。
• 通过领域预设(domain presets)输出预填充规则,确保 rules 不是空壳 资料来源:setup/SKILL.md。

其触发词包含 /setup、setup、harness setup、agent team setup 等;OpenAI 代理描述补充了「运行时环境配置、依赖安装、项目初始化校验」 资料来源:setup/agents/openai.yaml。

关键差异与协作流程

下表对二者边界做精确切分,并衔接 README 中 Quick Start 给出的执行序列 资料来源:README.md。

README 推荐的序列是:新建项目先执行 /project-init,再执行 /setup,之后才进入 /session-start、/scope、/freeze、/goal-lock、/stepback、/code-autopsy、/pre-push、/session-checkpoint 的日常循环 资料来源:README.md。

常见边界条件与失效模式

• project-init 不适用于「在已上线生产项目中替换 Hard Rules」——该技能专为初始设计而设计,混用会破坏既有上下文 资料来源:project-init/skill.md。
• setup 在已有完整 harness 的项目中应谨慎使用,新增单一规则即可的场景不应触发全流程重装 资料来源:setup/SKILL.md。
• 若 Write 工具不可用,project-init 只能回退为「输出文件内容、由用户手动保存」 资料来源:project-init/skill.md。
• stepback 是定位完全不同的辅助技能,输出上限 10 行、只产生 1 个抽象重构问题,且明确不会写入代码或调用代理,因此不应与 project-init/setup 混用为长流程 资料来源:stepback/SKILL.md。
• goal-lock 的 PLAN→DO→VERIFY→FINALIZE→OUTPUT 循环在初始化完成后才生效——它解决执行期纪律,而非初始化期缺失 资料来源:goal-lock/SKILL.md。

See Also

• 项目整体生命周期与 Quick Start:README
• 范围与边界冻结:/freeze 技能(freeze/SKILL.md)
• 执行期纪律引擎:/goal-lock 技能(goal-lock/SKILL.md)
• 视角重置:/stepback 技能(stepback/SKILL.md)

Daily Workflow & Discipline Skills（每日工作流与纪律技能）

概述与设计目标

sovereign-skills 是一套覆盖 Claude Code 项目完整生命周期的技能集。本页聚焦于「日常开发流」中用于约束 AI 行为、防止范围蔓延与目标漂移的五个纪律技能：/scope、/freeze、/goal-lock、/pre-push、/stepback。

这些技能共享一套核心设计哲学：「面谈优于模板」、「验证优于信任」、「范围先于代码」、「诚实汇报」、「会话连续性」。 资料来源：README.md

它们按典型开发节奏串行工作：会话开始 → /session-start；每个特性前 → /scope 定义 IN/OUT/退出准则；实现前 → /freeze 锁定可编辑区；开发过程中 → /goal-lock 强制 PLAN→DO→VERIFY 循环；任意时刻 → /stepback 视角重置；推送前 → /pre-push 密钥扫描 + 代理评审。资料来源：README.md

技能矩阵

资料来源：scope/SKILL.md stepback/SKILL.md README.md

详细工作机制

/scope — 范围定义引擎

/scope 在写代码前回答「做什么 / 不做什么」。它提供两种模式：

• Quick（默认）：三段式 IN / OUT / exit criteria，输出至 BRIEF.md
• Full（/scope full）：执行 L0→L4 分层规格链，输出至 spec.md

其「支配变量」是 OUT 项是否被显式写出 —— 仅声明 IN 项会导致实现过程中范围膨胀。Full 模式下则额外以 L2 决策清晰度作为支配变量。资料来源：scope/SKILL.md

不应触发场景：bug 修复、单文件改动、已有规格、脑暴。资料来源：scope/SKILL.md

/freeze — 范围冻结

/freeze 在实施前对输入进行解析，将文件分类为可编辑 / 冻结 / 只读，然后输出 FROZEN SCOPE 块并立即停止 —— 不生成代码，也不派生子代理。当输入存在歧义时，先发出一个澄清问题；若仍模糊，则冻结更大的范围以保证安全。资料来源：freeze/agents/openai.yaml（release notes v5.0）

/goal-lock — 代理纪律引擎

/goal-lock 强制 PLAN → DO → VERIFY → FINALIZE → OUTPUT 五阶段循环，并检测 11 类「成功伪装」模式（删除测试、Mock 包裹、阈值放宽等）。资料来源：README.md

提供两种模式：Quick 模式（3 字段，适用于小改动）与 Full 模式（7 字段，适用于其他所有情况）。资料来源：README.md

在 DO 阶段开始前，需对照 RISK 表进行风险检查（破坏性变更、竞态、过期状态、数据丢失、安全、性能回归、向后兼容）。任一风险命中即返回 PLAN 并附加规避策略。资料来源：goal-lock/SKILL.md

VERIFY 阶段必须「真正执行」验证命令，按栈自动选择配方：pytest -q + ruff check（Python）、npm test + npx eslint .（JS）、npx tsc --noEmit + npm test（TS）、go test ./... + go vet ./...（Go）、cargo test + cargo clippy（Rust）。未验证项标记为 NOT RUN: [reason]，绝不容忍「应该没问题」式假设；同时还需进行 GroundEval，确认验证命令本身确实执行过。资料来源：goal-lock/SKILL.md

/stepback — 一次性视角重置

/stepback 是只读、零副作用技能，用于在深度实现中重新校准方向。

架构流程（PARSE → STEP-BACK → CHECK → OUTPUT）：

flowchart LR
    A[最近对话上下文] --> B[PARSE<br/>提取当前方向与意图]
    B --> C[STEP-BACK<br/>生成 1 个抽象重框问题]
    C --> D[CHECK<br/>3 项检查:<br/>范围漂移 / 副作用 / 更优方案]
    D --> E[OUTPUT<br/>≤10 行,立即返回]

阶段说明：

• PARSE：抽取当前方向、原始意图、范围信号
• STEP-BACK：采用 DeepMind step-back 模式，从具体主题抽象到一般原则或系统
• CHECK：执行 3 项检查 —— 范围漂移、副作用、更优方案

严格不变式（任一违反即失败）：

1. 10 行上限 —— 超出即视为过度解释，稀释了视角重置效果
2. 1 个问题限制 —— 多问题会分散焦点
3. 立即返回 —— 不附加后续动作或菜单，让用户决定下一步

资料来源：stepback/SKILL.md

不应触发场景：工作已完成（用回顾工具）、请求代码评审（用代码评审工具）、需要具体变更影响分析（用范围定义工具）。资料来源：stepback/SKILL.md

集成模式与失败应对

五个技能构成顺序门禁链：scope 定义 → freeze 锁定 → goal-lock 守护 → stepback 校准 → pre-push 验收。每个阶段都强制产出「可验证产物」（文档 / 块 / 检查表），避免「应该通过」式幻觉。

在 v4.7 中，pre-push 引入了代理失败恢复机制：代理超时或出错时重试一次；仍失败则在汇总中标记 ⚠️ SKIPPED (agent unavailable — {agent}) 并继续流程；绝不会把失败的代理静默视为 PASS。这一原则与 goal-lock 中「验证必须实际执行」的纪律一脉相承。资料来源：README.md

参见

• Code Review & Analysis（code-autopsy）
• Session Management（session-start / session-checkpoint）
• Project Setup（project-init / setup）

概述

sovereign-skills 把"质量保证"拆成三个层次：单次代码评审（code-autopsy）、项目级成熟度审计（project-check）、协作行为模式审计（collab-audit）；再用两个会话生命周期技能（session-start / session-checkpoint）保证上下文在多次会话之间可恢复。五个技能在 README 的 Daily Loop 中被编排为标准工作流的一部分 资料来源：README.md:1-50。

code-autopsy 在 v6.2 中首次发布，定位为可独立运行的提示词，不绑定 Claude Code；project-check 与 collab-audit 已在 README 分类表中列出；session-start / session-checkpoint 自 v4.0 起作为会话开闭的固定节点 资料来源：README.md:25-70。

code-autopsy — 12 问量化代码评审

设计目标与作用域

code-autopsy 自称 "12 Questions + Quantified Severity + Deployment Verdict + 4-Axis Scoring"，身份被声明为 "Staff Security Engineer (20yr experience)"，使命是 "Trust nothing" 资料来源：code-autopsy/SKILL.md:42-48。它采用白名单（allow-list）约束：仅允许 12Q 分析、严重度评分、diff 建议、审计工具执行、部署裁决与复合得分；推测、空泛赞美、虚构 CVE 等行为被显式禁止 资料来源：code-autopsy/SKILL.md:48-58。

12 个评估维度

评审问题分为 Q1–Q12，覆盖设计、简洁性、缺陷、功能、安全、重复、性能、通用化、死代码、测试质量、错误弹性、可观测性 资料来源：code-autopsy/SKILL.md:1-28。其中安全相关问题被加粗强调（API 向后兼容、嵌套 ≤3、注释仅解释 "why"、竞态/死锁/共享状态、依赖与许可证、供应链等），体现了对 OWASP 与工程实践的硬性要求 资料来源：code-autopsy/SKILL.md:1-20。

4 轴加权与部署裁决

四个评估轴及权重：Security × 0.35、Stability × 0.30、Robustness × 0.20、Operability × 0.15 资料来源：code-autopsy/SKILL.md:1-10。Severity Anchor Table 给出 7–8 / 5–6 / 3–4 / 1–2 四档严重度，并按 Impact、Probability、Fix Cost、Detectability 四个属性做矩阵 资料来源：code-autopsy/SKILL.md:30-38。最终输出 SHIP / FIX / RISKY / BLOCK 四档部署裁决，并在标注 🔴 CRITICAL 之前强制走 CRITICAL Reachability Gate——若不可达或触发不现实，必须降级并标记 [theoretical] 资料来源：code-autopsy/SKILL.md:36-42。

反作弊机制

为防止 LLM 抬高分数，code-autopsy 引入两条元检测规则：

另外，静默失败通过 grep 模式直接抓取（空 except / except pass、日志报错但调用方无感知、宽 catch 吞错、or default 隐藏回退），并赋予 CRITICAL 或 HIGH 严重度 资料来源：code-autopsy/SKILL.md:58-70。

project-check 与 collab-audit — 项目与协作维度

project-check 扫描已有项目，按 4 个维度输出缺口排序：Infrastructure、Security、Quality、Harness 资料来源：README.md:30-50。其 agent 注册文件则描述为 "Audit project harness maturity across 6 axes and 58-item checklist with static and behavioral analysis"，意味着它同时做静态与行为分析 资料来源：project-check/agents/openai.yaml:1-3。

collab-audit 是 14 节 AI 协作审计，与问卷调查不同，它分析用户真实的工作模式——生成行为画像、盲点与成长方向 资料来源：README.md:30-50。两者的区别在于：project-check 评估"项目自身"，collab-audit 评估"人与 AI 协作的方式"。

Session Management — 上下文延续

会话类技能解决"跨会话记忆丢失"问题。session-start 在会话打开时加载 handoff、回顾 lessons、发出 ready 信号；session-checkpoint 在会话关闭前抽取实体、重写 handoff、保存 memory 资料来源：README.md:50-70。v5.0 之后 session-checkpoint 吸收了 retro 的反思能力，作为 Phase 1.7 Reflexion 步骤内置 资料来源：README.md:60-80。

整体工作流

flowchart LR
    A[session-start] --> B[scope / freeze]
    B --> C[goal-lock]
    C --> D[work + stepback]
    D --> E[code-autopsy]
    E --> F[pre-push]
    F --> G[session-checkpoint]
    G -.handoff.-> A

stepback 在工作过程中随时触发，作用是生成 1 个抽象重述问题 + 3 项快速检查（scope drift / side effects / better approach），并以 10 行内输出立即返回 资料来源：stepback/SKILL.md:1-30。goal-lock 提供 PLAN→DO→VERIFY→FINALIZE→OUTPUT 循环，并在 VERIFY 阶段依据栈自动选择验证命令（pytest / jest / tsc / go test / cargo test / git diff --stat） 资料来源：goal-lock/SKILL.md:1-50。

失败模式与边界

• 评审超出范围：code-autopsy 限定白名单，凡未列入 12Q 与裁决流程的判断一律 fail-closed 资料来源：code-autopsy/SKILL.md:48-58。
• 会话中断：若无 session-checkpoint 写入 handoff，下次 session-start 无法恢复实体与教训。
• LLM 策略性逃避：CEF Fabrication 与 CapCode 是 code-autopsy 的两道防线，遇到"系统错误"或分数异常跳升必须复核 资料来源：code-autopsy/SKILL.md:42-58。
• 视角漂移：进入实现深水区时应主动调用 stepback 触发 10 行内的重置 资料来源：stepback/SKILL.md:1-30。

See Also

• 项目结构与生命周期入口：参见 README.md
• Agent 团队与基础设施初始化：setup/SKILL.md
• 目标锁定与执行循环：goal-lock/SKILL.md
• 视角重置与盲点检查：stepback/SKILL.md

Pitfall Log / 踩坑日志

项目：AlexZio00/sovereign-skills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 sovereign-skills 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx skills
• 证据：identity.distribution | https://github.com/AlexZio00/sovereign-skills | repo=sovereign-skills; install=skills

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/AlexZio00/sovereign-skills | host_targets=claude_code, claude, cursor

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/AlexZio00/sovereign-skills | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/AlexZio00/sovereign-skills | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/AlexZio00/sovereign-skills | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | release_recency=unknown