@captain_z/zsk-skills

ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 skills/ 生成的 core harness-first skills；旧 .best-practices/ 不再批量生成独立 installable skills，而是作为参考源按 skill 携带相关子集。

包内共有 26 颗 installable skills，全部来自根级 skills/。其中 legacy full-core profile 继续保留 24 颗生命周期 skill；check / health 是可选诊断能力，适合通过 custom、单颗安装或 GitHub skill 管理器引入。

合规审查（ARCHITECTURE §4.4 硬指标）

| 检查项 | 结果 | 说明 | | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- | | frontmatter 完整（name / description / category / domain / tier / triggers） | ✓ 26/26 | core 由 root skills/ 生成 | | name 使用公共命名，目录同名且只含小写/数字/连字符 | ✓ 26/26 | 主入口为 zskplan / zsk；其它 skill 使用 zsk-<slug> 避免裸名冲突；CLI 选择层继续兼容 zsk:<slug> | | description 简洁表达职责和使用时机 | ✓ 26/26 | 面向索引阅读；triggers 留给机器使用 | | category / domain / tier 枚举值合法 | ✓ 26/26 | stage/utility · core | | triggers 数组非空 | ✓ 26/26 | 至少含裸 slug | | 无硬编码项目名 / 技术栈（统一 {{config.*}} 占位符） | ✓ | harness-neutral | | related: 相对路径合法 | ✓ | core 不依赖参考层生成物 | | 单文件 ≤ 300 行 | ✓ 26/26 | core 由 lint:harness 强制 |

当前 max-lines 已由 tools/lint-frontmatter.ts 作为 error 强制；新增或修改 skill 不应超过 300 行。

使用方法通则

zsk skill 是 LLM 按需自动触发的资产。用户通常只做两件事：先安装 skill，再在业务项目里用 zsk init 建知识工作区。

1. 安装：npx @captain_z/zsk add → 选 profile bundle（或 custom 多选）+ 目标路径（~/.claude/skills/ / ~/.codex/skills/ / 自定义）→ 落盘
2. 自动发现：LLM（Claude Code / Codex / Gemini CLI）会话启动时扫描 skill 目录，读取每份 SKILL.md 的 frontmatter
3. 自动触发：遇到匹配 description 或 triggers 的任务时，LLM 载入对应 SKILL.md 的完整内容
4. 手动触发（可选）：会话中显式说 "用 zsk:dispatch 调度"、"用 zsk:spec 写规格"，LLM 直接载入指定 skill

Profile 选择

Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 skills/，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。Workflow 负责编排、约束、签字、角色投入和多角度会诊；单个 skill 只负责自己的职责、非目标、输出质量、证据、风险和置信度。

| profile | skills | 适用场景 | | --- | ---: | --- | | zsk-entry | 2 | 只装 zskplan / zsk 两个主入口，由它们按 harness 调度 | | zsk-lite | 4 | 小修、小项目、脚本、低风险任务；只暴露入口和 coding/verify | | zsk-sdlc | 12 | 标准工程交付；安装入口 + 一等阶段，capability/gate 由 workflow 调度 | | zsk-frontend | 13 | UI/UX/browser-facing 交付；基于 SDLC 阶段面加装 demo | | zsk-enterprise | 12 | 高治理交付；deploy/audit/review 由 profile gate/capability 开启 | | sdlc-only | 24 | 旧入口兼容；安装全部 core skills |

Skill 搭配流程图

dispatch 是 ZSK 给 OMX 的调度适配入口；flow 是恢复下一合法阶段的状态机入口；profile 决定主线顺序、可选节点和严格度，其他 skill 按阶段负责一段明确产物。遇到缺资料、缺证据、缺 owner 或发现缺陷时，workflow 决定是否降级、补资源、回退或阻塞；skill 本身记录 gap、影响和下一步，不把 sibling skill 的产物当作缺一不可的硬前置。

flowchart TD
  Start([开始或恢复工作]) --> Dispatch[zsk:dispatch<br/>让 OMX 按 ZSK workflow 调度]
  Dispatch --> Flow[zsk:flow<br/>读取状态与资源]
  Flow --> Prepare[zsk:prepare<br/>计划并选择性同步资源]
  Prepare --> Proposal[zsk:proposal<br/>定义 why / scope / non-goals]
  Proposal --> Spec[zsk:spec<br/>写 FR/NFR/AC/场景]
  Spec --> Design[zsk:design<br/>映射接口/数据流/风险]
  Design --> Task[zsk:task<br/>拆任务与证据钩子]
  Task --> Coding[zsk:coding<br/>小步实现]
  Coding --> Smoke[zsk:smoke<br/>本地证明变更可运行]
  Smoke --> Review[zsk:review<br/>目标审查/多角度可选]
  Review --> Commit[zsk:commit<br/>review 后 scoped commit]
  Commit --> Ready[zsk:ready<br/>整理待验收证据]
  Ready --> Verify[zsk:verify<br/>独立验证 claim]
  Verify --> Acceptance[zsk:acceptance<br/>业务接受或拒绝]
  Acceptance --> Archive[zsk:archive<br/>归档产物与学习反馈]

  Coding -.发现问题.-> Issue[zsk:issue<br/>缺陷/阻塞/风险/问题]
  Smoke -.失败.-> Issue
  Review -.拒绝.-> Issue
  Verify -.不通过.-> Issue
  Issue --> Coding
  Commit -.需要环境.-> Deploy[zsk:deploy<br/>部署到非生产/演示环境]
  Deploy -.进入验证.-> Ready
  Demo[zsk:demo<br/>正式测试前演示] --> Defect[zsk:defect<br/>QA 缺陷归类与复现]
  Defect --> Coding
  Commit -.需要演示.-> Demo

Direct review 只需要明确 review target（代码 diff、本地路径、stage 文档或可检测变更）。缺少 spec/design/tasks/smoke/signoff/专家面板时，review 应记录为 N/A、风险或 confidence gap，并继续做目标审查；只有 workflow profile 明确启用 strict gate 时，才由 workflow 把这些缺口升级为阻塞。

每个 stage 输出都应包含 Output Quality Check：质量分、置信度、证据、缺口/不确定性、漂移信号、下一步。若缺口属于本 skill 职责内，应先做 bounded ReAct 修复；若属于 workflow 编排、资源准备或外部决策，则交给 workflow 路由。

常见用法

| 目标 | 推荐说法或命令 | 结果 | | --- | --- | --- | | 安装默认 core skills | npx @captain_z/zsk add | 交互选择 target 和 bundle | | CI 安装 ZSK 主入口 | npx @captain_z/zsk add zsk-entry --target=~/.claude/skills --yes | 非交互安装 zskplan / zsk 两个入口 | | CI 安装轻量 profile | npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes | 非交互安装 4 颗入口/执行 skills | | CI 安装标准 SDLC profile | npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes | 非交互安装 12 颗标准 entry/stage skills | | Claude plugin 分层安装 | /plugin marketplace add codeshareman/zsk 后 /plugin install zsk-entry@zsk | 在 Claude 内按 profile 安装 ZSK skills | | Claude plugin 全量兼容 | /plugin install zsk@zsk | 安装 24 颗 core skills，保留给旧工作流或高级用法 | | GitHub skills 管理器安装 | npx skills add codeshareman/zsk | 从仓库安装公共命名的 ZSK skills 或单颗 skill；不要加 @ | | Skill 质量 dry-run | npx @captain_z/zsk skills dry-run --min-score=90 | 不调用 LLM、不写项目；模拟每颗 skill 的输入、输出、质量检查、stop condition 和专属场景断言；总分、qualityItems[] 和 scenarioChecks[] 单项都必须达到阈值 | | 准备项目资源 | npx @captain_z/zsk prepare draft && npx @captain_z/zsk prepare plan && npx @captain_z/zsk prepare sync --all | 先审查建议，再同步确认后的 .zsk/raws/** snapshot | | 只想让 ZSK 自己规划和执行 | "用 zskplan 规划" / "用 zsk 继续" | 计划写入 .zsk/plans/，执行产物写入 .zsk | | 不确定该用哪个阶段 skill | "用 zsk:dispatch 调度" | 让 OMX 围绕 ZSK skills 分配 subagents | | 恢复一个项目的下一步 | "用 zsk:flow 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 | | 明确进入某阶段 | "用 zsk:spec 写模块规格" | 只载入对应 stage contract |

典型消费路径（production，安装后）。<public-name> 表示 zskplan / zsk 两个裸入口，或其它 skill 的 zsk-<slug>：

• ~/.claude/skills/<public-name>/SKILL.md — Claude Code / flat target
• ~/.codex/skills/<public-name>/SKILL.md — Codex / flat target
• ./.claude-plugin/skills/<slug>/SKILL.md + commands/<slug>.md — Claude plugin local target
• skills/.curated/<public-name>/SKILL.md — npx skills / Claude plugin marketplace repository target
• @captain_z/zsk-skills/<public-name>/SKILL.md — 通过 npm 读

仓库根还发布 .claude-plugin/plugin.json 和 .claude-plugin/marketplace.json，用于 Claude Code /plugin marketplace add codeshareman/zsk 后按 profile 安装 zsk-entry@zsk、zsk-lite@zsk、zsk-sdlc@zsk、zsk-frontend@zsk 或 zsk-enterprise@zsk；zsk@zsk 保留为全量兼容入口。根级 skills/.curated/ 同时兼容 npx skills add codeshareman/zsk。

和项目知识工作区的关系

zsk init 生成的 .zsk/config.yaml、.zsk/CONTEXT.md、.zsk/docs/SYSTEM-SPEC.md、.zsk/raws/、.zsk/modules/、.zsk/issues/、.zsk/evidence/、.zsk/playwright/ 和 .zsk/plans/ 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、通过 zsk prepare draft / zsk prepare plan 生成可审查建议，并通过 zsk prepare sync 选择性刷新 .zsk/raws/manifest.json、snapshot 和 readiness evidence。zsk config check / zsk check 做确定性校验。

Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；登录态优先转成 Playwright storageState；视觉/当前页面判断优先 Computer Use；没有 Computer Use 的运行时用 Playwright MCP/ARIA/CDP、手工证据或可用的 Browser Use 兼容处理。Skills 必须通过 .zsk/config.yaml 和 .zsk/modules/{module}/module.yaml 解析路径，不能硬编码 .zsk/raws、root docs、root .issues、root .playwright 或 root plans。

每个 skill/stage 的输入、输出、工具/能力、脚本策略和运行时 UI 观察策略由 harness 的 skill-io-contract.yaml 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 completion-contract.yaml 约束；质量评分、角色/人员建议和 direct review 降级规则由 quality-roles.yaml、skill-classification.yaml 和 workflow-orchestration-policy.yaml 共同说明。缺少 Documentation Feedback 时，zsk check 可以把它作为阶段未收口的证据。

领域总览

包内只保留默认可安装的 core 领域。Frontend、quality、design-handoff 等内容仍由根级 .best-practices/ 维护，但会按相关性复制到各 skill 的 harness/best-practices/；它们不是单独可触发的 installable skills。

| 领域 | skill 数 | 职责 | | ----------------- | -------- | ------------------------------------------ | | skills/ | 26 | harness-first 默认工作流入口与可选诊断能力 | | 总计 | 26 | |

安装套件（bundles.yaml）

| name | skills | 场景 | | ------------------------------ | ------ | --------------------------------------------- | | zsk-entry | 2 | 只安装 ZSK / ZSK Plan 两个主入口 | | zsk-lite | 4 | 小型低风险任务；入口 + coding/verify，review/smoke/commit 作为 workflow capability | | zsk-sdlc（推荐） | 12 | 标准工程交付；安装入口 + 一等阶段 | | zsk-frontend | 13 | 前端/视觉/browser-facing 任务；强化 demo 和 evidence | | zsk-enterprise | 12 | 高治理交付；deploy/audit/review 由 profile gate/capability 开启 | | sdlc-only | 24 | 旧入口兼容；安装全部 core skills | | frontend-project | 24 | 旧入口兼容；推荐改用 zsk-frontend | | frontend-with-design-handoff | 24 | 旧入口兼容；推荐改用 zsk-frontend | | custom | 交互 | 通过 zsk add 任意多选 |

Skill 清单（core skills）

内容由 tools/catalog.ts 从 packages/skills/<public-name>/SKILL.md frontmatter 生成；zsk / zskplan 为裸入口，其它 skill 使用 zsk-<slug>。重生成：pnpm catalog。 默认 profile bundles 只安装 entry 和保留的一等 stage；capability / gate / mode 由 zskplan / zsk 内部调度或通过 custom/legacy 明确安装。Legacy aliases 仍保留 24 个 skill 以兼容旧安装。

Entry Skills (2)

用户默认只需要理解的入口。

• zskplan · type: workflow · keep-entry Use as the ZSK-aware RalphPlan-style planning entrypoint that clarifies vague intake, then freezes scope, module decomposition, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.

• zsk · type: workflow · keep-entry Use as the ZSK-aware Ralph-style execution loop that follows ZSK plans, dispatches expert lanes, verifies, fixes, and writes only .zsk outputs.

Stage Skills (11)

有独立产物边界、质量门禁和下游消费关系的一等阶段。

• zsk-prepare · type: capability · keep-stage After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.

• zsk-preproposal · type: capability · keep-stage Before proposal, turns a one-sentence or vague intake brief into a clear, reviewed product, roadmap, UX, and readiness raw resource pack.

• zsk-proposal · type: capability · keep-stage Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.

• zsk-spec · type: capability · keep-stage After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.

• zsk-design · type: capability · keep-stage After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.

• zsk-task · type: capability · keep-stage After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.

• zsk-coding · type: capability · keep-stage For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.

• zsk-demo · type: capability · keep-stage Before formal testing, runs planned demos and captures evidence without making acceptance claims.

• zsk-verify · type: capability · keep-stage Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.

• zsk-acceptance · type: capability · keep-stage After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.

• zsk-archive · type: capability · keep-stage After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.

Capabilities (7)

可被多个阶段复用的内部能力；默认由入口或阶段调度。

• zsk-dispatch · type: workflow · downshift-to-capability At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.

• zsk-review · type: capability · downshift-to-capability After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.

• zsk-defect · type: capability · downshift-to-capability After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.

• zsk-deploy · type: capability · downshift-to-capability After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.

• zsk-learn · type: capability · downshift-to-capability Use after repeated friction or supplied public skill/harness references to learn, compare, record gaps, and prepare one reviewed ZSK optimization batch.

• zsk-issue · type: utility · keep-capability Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.

• zsk-health · type: capability · keep-capability Use when auditing ZSK agent, skill, workflow, harness, and installation health to find coupling, token waste, trigger overlap, stale generated surfaces, and output-quality gaps without owning product delivery.

Gates (4)

阶段内部的质量检查点或发布检查点。

• zsk-smoke · type: capability · downshift-to-gate After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.

• zsk-commit · type: capability · downshift-to-gate After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.

• zsk-ready · type: capability · downshift-to-gate Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.

• zsk-check · type: capability · downshift-to-gate Before commit, push, release, or handoff, runs a lightweight readiness preflight over local changes and reports evidence, risks, and a clear ready/not-ready verdict without owning workflow gates.

Modes (2)

入口或阶段内部的执行模式。

• zsk-flow · type: workflow · downshift-to-mode Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.

• zsk-fix · type: workflow · downshift-to-mode For persisted issues, diagnoses root cause, applies the smallest scoped correction, adds a regression guard, updates the issue, and hands off verification.