@captain_z/zsk-skills

ZNorth Standard Kit 的内容包：51 颗原子 skill，按领域分簇组织，通过 npx @captain_z/zsk add 可安装到 Claude / Codex / Gemini 等多 harness。

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

| 检查项 | 结果 | 说明 | | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- | | frontmatter 完整（name / description / category / domain / tier / triggers） | ✓ 51/51 | 结构化 lint 通过 | | name 以 zsk: 前缀，扁平 slug | ✓ 51/51 | 命名空间统一 | | description 使用直接陈述风格，触发词放入 triggers | ✓ 51/51 | 触发语义由 description + triggers 共同承担 | | category / domain / tier 枚举值合法 | ✓ 51/51 | stage/workflow/standard/resource/meta · core/optional | | triggers 数组非空 | ✓ 51/51 | 每颗至少 4 个关键词 | | 无硬编码项目名 / 技术栈（统一 {{config.*}} 占位符） | ✓ | harness-neutral | | related: 相对路径合法（build 已重写） | ✓ | 无孤儿引用 | | 单文件 ≤ 300 行 | ✓ 51/51 | lint-frontmatter 作为 error 强制 |

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

使用方法通则

zsk skill 是 LLM 按需自动触发的资产：

1. 安装：npx @captain_z/zsk add → 选 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:spec"、"走 zsk:feature 工作流"，LLM 直接载入指定 skill

典型消费路径（production，安装后）：

• ~/.claude/skills/<domain>/<slug>/SKILL.md — Claude Code
• ~/.codex/skills/<domain>/<slug>/SKILL.md — Codex
• @captain_z/zsk-skills/<domain>/<slug>/SKILL.md — 通过 npm 读

和项目知识工作区的关系

zsk init 生成的 .zsk/config.yaml、docs/SYSTEM-SPEC.md、.raws/、docs/ 和 .issues/ 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 {paths.raws}/manifest.json，并通过 zsk config check / zsk check 做确定性校验。

Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，使用 Computer Use / Browser Use 验证运行时行为，并把问题写入配置的 issue 根。Skills 必须通过 .zsk/config.yaml 和 docs/{module}/module.yaml 解析路径，不能硬编码 .raws、docs 或 .issues。

每个阶段都要把确认过的决策、约束、例外和验证结果写回持久文件。缺少 Documentation Feedback 时，zsk check 可以把它作为阶段未收口的证据。

领域总览

| 领域 | skill 数 | 职责 | | ----------------- | -------- | ------------------------------------------ | | sdlc/ | 18 | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 | | frontend/ | 16 | React + Web 层实现规范 | | quality/ | 5 | 跨栈质量原则 | | design-handoff/ | 5 | 设计交付方法论 | | system/ | 6 | 工程宪法级资源 | | meta/ | 1 | 元信息 | | 总计 | 51 | |

安装套件（bundles.yaml）

| name | skills | 场景 | | ------------------------------ | ------ | --------------------------------------------- | | sdlc-only | 11 | 纯流程骨架（7 阶段 + 3 工作流 + Agent 编排），不涉及技术栈 | | frontend-project（推荐） | 30 | SDLC 10 + Agent 编排 + Frontend 16 + Quality 3 | | frontend-with-design-handoff | 35 | frontend-project + 设计交付 5 | | custom | 交互 | 通过 zsk add 任意多选 |

Skill 清单（按领域）

内容由 tools/catalog.ts 从各 SKILL.md frontmatter 生成。重生成：pnpm catalog。

sdlc/ — SDLC · 7 阶段 + 3 变更工作流 + task 框架 (18)

• zsk:proposal [stage 1 · stage · core] New-change framing (feature / bugfix / refactor) before spec work — why, success criteria, out-of-scope boundary, alternatives considered, and risks. Always the first stage of the 7-stage SDLC. 触发：new feature proposal · bug report · refactor trigger · SMART goals

• zsk:spec [stage 2 · stage · core] Behavioral contract writing after proposal approval — scope, numbered functional and non-functional requirements, scenarios, acceptance criteria, edge cases, and impact boundaries. Stage 2 of the 7-stage SDLC. 触发：writing spec · behavior contract · acceptance criteria · numbered requirements

• zsk:design [stage 3 · stage · core] Solution design after spec freeze — current-state scan, architectural decisions, implementation mapping, delivery slices, risks, rollback, and observability. Stage 3 of the 7-stage SDLC. 触发：technical design · solution design · architecture decision · current state scan

• zsk:coding [stage 4 · stage · core] Implementation execution after design freeze — smallest viable change, auditable delivery batches, explicit TDD rules by change type, continuous evidence capture, and local quality gates before review. Stage 4 of the 7-stage SDLC. 触发：implementing design · auditable delivery batches · local quality gates · smallest viable change

• zsk:reviewing [stage 5 · stage · core] PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、多视角 Sub-Agent 审查、测试执行流分析、代码整洁/重构纪律、置信度校准以及按严重性排序的判定协议。 触发：code review · PR review · 审查合并请求 · review this PR

• zsk:verify [stage 6 · stage · core] Acceptance verification before merge — independent contract check, FR/NFR coverage, AC evidence, gate records, and verdict with reproducible proof. Stage 6 of the 7-stage SDLC. 触发：acceptance verification · evidence before assertion · FR coverage matrix · AC evidence

• zsk:archive [stage 7 · stage · core] Iteration closing / archive — move historical snapshots to docs/{module}/archive/, write postmortem (P0/P1 mandatory), update changelog (SemVer + Keep a Changelog), flush ADRs, update SYSTEM-SPEC if cross-module constraints emerged, feed back to standards/system docs. Stage 7 of the 7-stage SDLC. 触发：archive iteration · postmortem · changelog · ADR flush

• zsk:bugfix-tasks [core] Bugfix task template with TDD enforcement — Step 1 Red (write failing reproduction test), Step 2 Green (minimal fix, no opportunistic refactor), Step 3 Regression (adjacent scenarios), Step 4 Evidence (before/after reproduction). Requires Superpowers' 3 confidence questions before starting. 触发：bugfix task template · TDD bug fix · red green regression · bug confidence questions

• zsk:dor-dod [core] DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in zsk:dor-dod-frontend. 触发：definition of ready · definition of done · DoR DoD · task gate

• zsk:refactor-tasks [core] Refactor task template (characterization + small-step atomic) — Step 1 capture behavior baseline, Step 2 apply one Fowler technique per atomic commit (revert on red), Step 3 Parallel Change for large refactors (Expand → Migrate → Contract), Step 4 prepare behavior-unchanged evidence. 触发：refactor task template · characterization baseline · Fowler techniques · Parallel Change tasks

• zsk:task [core] Cross-stage task execution mindset — what a task is, how it threads spec → verify, which template to pick by change type, cross-stage hard principles. Not for writing a specific task; use zsk:task-structure for that. 触发：task framework · task execution overview · cross-stage tasks · which task template

• zsk:task-evidence [core] Task verification evidence discipline — FR coverage matrix (every FR/NFR from spec has coverage task + acceptance evidence), AC checklist with reproducible links, validation records per gate (lint/type-check/test/security/etc.). Enforces "evidence before assertion" — links must be clickable and reproducible. 触发：FR coverage matrix · AC verification · validation record · evidence links

• zsk:task-structure [core] tasks.md authoring discipline — task granularity (0.5-2 person-days), two-level structure (parent/child, no deeper), estimation unit (T-shirt or Fibonacci), required fields per task (status/owner/covers-FR/deliverable/verification), FR coverage numbering rules. 触发：task granularity · task estimation · T-shirt sizing · story points

• zsk:task-tracking [core] Task execution tracking — dependencies (Mermaid graph), blockers (dated log with severity H/M/L and escalation rules), milestones, auditable LLM execution batches, and task state transitions (TODO → DOING → DONE, with BLOCKED requiring log entry). 触发：task dependency graph · blocker log · milestones · task state flow

• zsk:bugfix [workflow · core] Bugfix end-to-end orchestration — triage → reproduce → RCA (5 Whys with confidence questions) → TDD fix (red first) → regression coverage → postmortem (P0/P1 mandatory). Enforces Superpowers' bug confidence questioning discipline. 触发：bug fix workflow · fix defect · RCA · 5 whys

• zsk:feature [workflow · core] Feature end-to-end orchestration across 7 SDLC stages — brainstorming → writing-plans → plan-eng-review → executing-plans+TDD → requesting/receiving-code-review → verification-before-completion → finishing-a-development-branch. 触发：new feature workflow · feature end to end · start feature · feature stages

• zsk:refactor [workflow · core] Behavior-preserving refactor discipline — Fowler catalog, characterization tests as baseline, small atomic commits, Parallel Change / Strangler Fig for large refactors. Enforces "behavior preserved" as a hard contract (any behavior change means it is not a refactor). 触发：refactor workflow · Fowler refactoring · characterization test · Parallel Change

• zsk:standard-dev-flow [workflow · core] 交互式标准开发工作流，包含 Prepare 预检 + 7 阶段 SDLC（Proposal, Spec, Design, Coding, Reviewing, Verify, Archive）。通过强门禁、可审计批次和多视角审查，保障高质量开发落地。 触发：standard dev flow · start a new feature workflow · execute enterprise workflow · 7 stage development

frontend/ — Frontend · React + Web 层实现规范 (16)

• zsk:spec-frontend [stage 2 · stage · optional] Frontend component/page spec.md authoring — adds Component Public Contract (Props / Events / TS types), UE state matrix with a11y attributes, UE/MCP reference, and the 6-category Frontend NFR (performance / a11y / security / i18n / compat / observability). Extends the generic zsk:spec framework. 触发：frontend spec · Component Public Contract · Props Event Contract · UE state matrix

• zsk:design-frontend [stage 3 · stage · optional] Frontend module design.md authoring — adds Props/state/event implementation mapping, UE-state-to-structure mapping, Figma-to-implementation mapping, performance budget (Core Web Vitals), ErrorBoundary placement. Extends the generic zsk:design framework. 触发：frontend design · Props implementation mapping · UE state to structure · Figma to implementation

• zsk:review-frontend [stage 5 · stage · optional] Frontend PR code review — frontend-specific self-checklist and reviewer checklist covering TypeScript red lines (no any / @ts-ignore), React hooks rules, dangerouslySetInnerHTML, large-list performance hazards, visual regression, i18n three-language sync, jsx-a11y. Extends zsk:reviewing generic checklist. 触发：frontend code review · React review checklist · TypeScript red lines · hooks review

• zsk:dor-dod-frontend [optional] Frontend-specific DoR/DoD for SDLC stage transitions — frontend-specific rows on top of the generic checklist. Covers UE state matrix completeness, ue-mcp.md registration, visual regression, three-language i18n sync, a11y (keyboard/aria/focus), frontend NFR (CWV) evidence. 触发：frontend DoR DoD · frontend definition of ready done · UE matrix gate · visual regression gate

• zsk:feature-tasks-frontend [optional] Frontend component/page feature task template — 7-category mandatory (事实源对齐 / Props 契约 / UE-MCP 刷新 / UE 状态 / 测试 / 视觉回归 / 质量门禁). Enforces TDD-first, contract-driven, evidence-before-assertion. 触发：frontend feature tasks · component tasks template · 7 category tasks · Props UE state visual regression

• zsk:nfr-web [optional] Web-side NFR thresholds for the 7-category framework — Core Web Vitals (LCP/INP/CLS/TTFB/TTI targets), WCAG 2.1 AA itemized rules, Web security NFR items, i18n language list + baseline + entry + RTL, browser/OS/device compatibility matrix, responsive breakpoints, observability (web-vitals + error reporting), reliability (ErrorBoundary + timeout + retry). Inherits system/nfr-baseline; modules declare deviations only. 触发：Web NFR · CWV thresholds · WCAG AA rules · browser matrix

• zsk:a11y-web [standard · optional] React/JSX accessibility implementation — label association (htmlFor/wrap), aria props usage, Modal focus trap (inert + initialFocus + restoreFocus), dialog role, live regions for async, skip link, axe-core + jsx-a11y toolchain, keyboard event handlers, prefers-reduced-motion. Implementation layer; principles (WCAG, POUR, contrast) live in quality/a11y-principles. 触发：jsx a11y · focus trap · Modal accessibility · axe-core

• zsk:api-contract-ts [standard · optional] TypeScript frontend × backend API contract — never hand-write API types, always consume from the shared types package or generated codegen. Covers source-of-truth pattern (backend-owned types), codegen workflows (OpenAPI / GraphQL / tRPC / Protobuf), breaking-change handling, version discipline, runtime validation (Zod at boundary), and service-layer shape. Pairs with typescript.md red lines. 触发：API type sync · do not hand-write API types · OpenAPI codegen · GraphQL codegen

• zsk:i18n [standard · optional] Frontend module i18n implementation — unified entry (i18n.t with mandatory fallback), key namespace structure (namespace.module.leaf_key), three-language sync rule (commit-atomic), ICU MessageFormat for plural/select, Intl.* for date/number/currency, RTL declaration, React Trans component for JSX interpolation. Replaces standards/i18n for frontend scope. 触发：i18n implementation · key namespace · fallback baseline · ICU plural

• zsk:performance-web [standard · optional] React / Web frontend performance for Core Web Vitals — CWV thresholds (LCP/INP/CLS/TTFB/TTI), React memoization discipline (when to memo vs not), virtualization for lists ≥ 200, lazy loading via React.lazy + Suspense + IntersectionObserver, bundle splitting + tree-shaking, image srcset + loading="lazy", debounce/throttle, re-render diagnosis with React DevTools Profiler. Implementation layer; budget framework in system/nfr-baseline + frontend/nfr-web. 触发：Core Web Vitals · LCP INP CLS · React memo · virtual scrolling

• zsk:react-components [standard · optional] React component API design — layering (UI/logic separation via hooks), composition vs configuration (compound components over flat-prop explosion), granularity (5-question checklist), controlled vs uncontrolled boundary, Props API design. React-specific implementation of generic component discipline. 触发：React component design · compound components · component granularity · controlled uncontrolled

• zsk:react-naming [standard · optional] React + TypeScript naming conventions — components, files, folders, variables, booleans, event handlers, event props, hooks, TS types/interfaces, constants, and i18n keys. Principles transfer to Vue/Svelte with syntax adjustments. 触发：React naming · component file naming · event handler naming · boolean naming

• zsk:security-web [standard · optional] Web frontend security — XSS (React default escape + dangerouslySetInnerHTML red line + DOMPurify exception), URL protocol whitelist, Storage red lines (no sensitive data in Local/SessionStorage), CSRF token integration, console log scrubbing for production, CSP meta/header consumption, SRI for third-party scripts, clickjacking (frame-ancestors awareness), postMessage origin checks. Frontend UI is the convenience defense; backend is final. 触发：dangerouslySetInnerHTML · XSS React · DOMPurify · LocalStorage sensitive

• zsk:styling-system [standard · optional] Frontend styling system discipline — scheme detection, naming conventions, nesting depth (≤3 layers), token usage rules (no hardcoded color/spacing), scope isolation, responsive breakpoints, and !important prohibition across Less / Sass / CSS Modules / Tailwind / CSS-in-JS. 触发：CSS scheme detection · BEM naming · Less nesting · design token

• zsk:testing-web [standard · optional] Frontend tests for React codebases — full toolchain (Jest/Vitest + React Testing Library + renderHook + user-event + MSW + Playwright + Chromatic + jest-axe), test structure (AAA/GWT), mock strategy (MSW for HTTP, manual for modules), coverage thresholds (new code / global), and the component test template. Implementation layer; cross-stack principles live in quality/testing-pyramid. 触发：Jest Vitest · React Testing Library · MSW mock service worker · Playwright

• zsk:typescript [standard · optional] TypeScript in frontend codebases — red lines (no any / as any / @ts-ignore / empty interface / Object type), must-do (explicit types for public boundaries, union literals, strict + noUncheckedIndexedAccess), API types from backend (not hand-written), type vs interface, generics discipline, unknown over any. Complements quality/code-hygiene for cross-language hygiene. 触发：TypeScript red lines · no any · strict mode · noUncheckedIndexedAccess

quality/ — Quality · 跨栈质量原则 (5)

• zsk:a11y-principles [standard · optional] Accessibility principles at the concept level — WCAG 2.1 AA baseline, POUR principles, keyboard operation matrix, focus management, aria semantics, contrast ratios, don't-rely-on-color, reduced motion. For Web/JSX implementation (axe-core, jsx-a11y, focus traps in Modal, etc.) see frontend/a11y-web.md. 触发：accessibility principles · WCAG AA · POUR · keyboard matrix

• zsk:code-hygiene [standard · optional] Code hygiene for any language — comment policy (WHY not WHAT), import ordering principle, formatter discipline, generic forbidden patterns (TODO comments, commented-out code, signature-like comments). Stack-specific rules (TypeScript red lines, React naming) are in frontend/*. 触发：code hygiene · comment policy · import order · WHY not WHAT

• zsk:release [standard · optional] Version release discipline — SemVer numbering, Keep a Changelog, Conventional Changelog auto-generation, environment promotion (dev→test→pre→prod), feature flag lifecycle, rollback strategy, hotfix process, canary monitoring. Works across language stacks; tool names are stack-specific examples. 触发：SemVer · changelog · conventional changelog · hotfix

• zsk:security-owasp [standard · optional] Cross-stack security discipline — OWASP Top 10 overview, CVE response SLAs, dependency license whitelist, supply chain hygiene, common lint red lines (eval/dynamic execution), and the "frontend UI is not the final defense" principle. Web-specific XSS/CSRF/Storage red lines are in frontend/security-web.md. 触发：OWASP Top 10 · CVE response · license whitelist · supply chain security

• zsk:testing-pyramid [standard · optional] Cross-language test strategy & discipline — test pyramid ratio (unit 70 / integration 20 / e2e 10), AAA/GWT structure, coverage targets, and the three hard principles (evidence before assertion, Red-Green-Refactor, bug confidence questioning). Stack-specific tooling (Jest/RTL/MSW/Playwright) is in frontend/testing-web.md. 触发：test pyramid · TDD discipline · test coverage target · AAA GWT structure

design-handoff/ — Design Handoff · 设计交付方法论 (5)

• zsk:figma-to-code [optional] Figma design node → production code via MCP — 7-step workflow (locate → extract structure → extract annotations → naming conversion → layout decoding → states → tokens), plus the 4-dimension "100% fidelity" verification (visual / interaction / semantic / responsive). Styling specifics live in zsk:styling-system. 触发：figma to code · 100 percent fidelity · node naming conversion · design annotations

• zsk:ue-mcp [optional] Design Source capture & MCP readout for modules with Figma/design input — Design Source (URL/node-id), MCP readout status, module-specific UE deviations from system baselines, and implementation mapping. Produces docs/{module}/ue-mcp.md + structured description.md snapshot in design-assets. Only records deviations, not duplicated baseline rules. 触发：UE MCP context · figma snapshot · design source reference · module UE deviation

• zsk:ux-wireframe [optional] UX wireframe workflow before high-fidelity design — turns spec scenarios into task flows, information architecture, low-fidelity layouts, and state coverage. Supports Pencil, Excalidraw, Mermaid, or text wireframes when Figma is not ready. 触发：wireframe · low fidelity design · Pencil design · UX flow

• zsk:design-system [standard · optional] Design system governance for Figma and frontend alignment — records tokens, component states, naming, responsive rules, accessibility baselines, and anti-generic visual constraints before high-fidelity generation or implementation. 触发：design system · design tokens · Figma variables · component variants

• zsk:figma-generate-hifi [workflow · optional] Figma high-fidelity generation workflow from spec, UX wireframes, and design-system rules — creates or updates production-oriented Figma pages with state matrices, responsive variants, annotations, and anti-generic visual checks. 触发：generate Figma · high fidelity design · figma generate design · hifi UI

system/ — System · 工程宪法级资源 (6)

• zsk:adr [optional] Cross-module long-lived architectural decision record — context, decision, rationale, alternatives considered, and consequences. Produces docs/system/adrs/ADR-NNNN-{slug}.md. Not for single-module implementation choices. 触发：architecture decision record · ADR template · MADR · cross-module decision

• zsk:agent-orchestration [core] Agent orchestration protocol for all zsk skills — assigns independent work to specialized Sub-Agents, defines main-agent ownership, role boundaries, review integration, and fallback behavior when delegation is unavailable. 触发：sub agent orchestration · parallel agents · multi agent workflow · agent responsibilities

• zsk:architecture [optional] Project system architecture documentation — C4 context diagram, tech stack baseline, module boundaries, routing, auth flow, data flow (request/state/contract), deployment topology, related ADRs. Frontend micro-frontend topology is an optional add-on section. 触发：system architecture · C4 model · tech stack baseline · module boundaries

• zsk:glossary [optional] Project Ubiquitous Language maintenance — single source for business terms, domain entities, state names, technical terms, and acronyms. Eliminates same-concept-different-names confusion across modules and backend contracts. 触发：glossary · ubiquitous language · DDD terms · business term

• zsk:nfr-baseline [optional] Project NFR baseline (inherited or established) — 7-category framework (performance / a11y / security / i18n / compatibility / observability / reliability) and the deviation-declaration discipline. Web-specific values (CWV thresholds, WCAG AA, browser matrix, 三语) live in frontend/nfr-web.md. 触发：NFR baseline · non functional requirements · quality attributes · ISO 25010

• zsk:project-constraints-template [optional] Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.md (mechanical values). 触发：project constraints · SYSTEM-SPEC · import origins · forbidden packages

meta/ — Meta · 元信息 (1)

• zsk:philosophy [meta · optional] Design rationale of the zsk skill set — LLM Wiki × Superpowers × GSD × project-adaptation synthesis. For contributors needing to understand why zsk is organized the way it is. 触发：zsk philosophy · why is zsk organized this way · design rationale · LLM wiki vs superpowers