universal-dev-standards 6.6.0 → 6.7.1

package/bundled/locales/zh-TW/skills/testing-guide/SKILL.md

@@ -1,12 +1,17 @@
 ---
 source: ../../../../skills/testing-guide/SKILL.md
 source_version: 1.2.0
-translation_version: 1.2.0
-last_synced: 2026-06-02
+translation_version: 1.3.0
+last_synced: 2026-08-17
 source_hash: 49b6f9e0c6a4
 status: current
 name: testing
-description: "[UDS] 測試金字塔與 UT/IT/ST/E2E 測試撰寫標準"
+description: |
+  測試金字塔，以及 UT/IT/ST/E2E 的測試撰寫標準。
+  支援 ISTQB 與業界通行金字塔兩種框架。
+  Use when: 撰寫測試、討論測試覆蓋率、測試策略或測試命名時。
+  Not for: 驅動紅-綠-重構循環——請用 /tdd；量測實際達成的覆蓋率——請用 /coverage。
+  Keywords: test, unit, integration, e2e, coverage, mock, ISTQB, SIT, 測試, 單元測試, 整合測試, 端對端.
 ---
 
 # 測試指南

package/bundled/skills/ac-coverage/SKILL.md

@@ -2,7 +2,11 @@
 name: ac-coverage
 scope: universal
 anchor_standard: acceptance-criteria-traceability
-description: "[UDS] Analyze AC-to-test traceability and coverage"
+description: |
+  [UDS] Analyze AC-to-test traceability and generate requirement-level coverage reports.
+  Use when: auditing which acceptance criteria have tests, building a traceability matrix from a SPEC file, finding uncovered AC before release.
+  Not for: code-level line/branch/function coverage — use /coverage; writing the missing tests — use /tdd or /spec-derive.
+  Keywords: AC coverage, traceability, acceptance criteria, SPEC, traceability matrix, 驗收條件, 需求追蹤, 覆蓋率矩陣.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[spec file path | 規格檔案路徑]"
 ---

package/bundled/skills/adr-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   [UDS] Create, manage, and track Architecture Decision Records (ADR).
   Use when: architecture decisions, technology choices, design trade-offs, pattern selection.
+  Not for: decisions that do not change architecture — record them in the spec or commit; ideas not yet formed enough to decide — use /brainstorm.
   Keywords: ADR, architecture decision, decision record, trade-off.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[create | list | supersede ADR-NNN | 決策主題]"

package/bundled/skills/ai-collaboration-standards/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Prevent AI hallucination and ensure evidence-based responses when analyzing code or making suggestions.
   Use when: analyzing code, making recommendations, providing options, or when user asks about confidence/certainty.
+  Not for: authoring the AI instruction files themselves — use /ai-instruction-standards; reviewing a concrete diff — use /code-review.
   Keywords: certainty, assumption, inference, evidence, source.
 ---
 

package/bundled/skills/ai-friendly-architecture/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Design AI-friendly architecture with explicit patterns, layered documentation, and semantic boundaries.
   Use when: structuring projects for AI collaboration, optimizing codebase for AI analysis, setting up AI context.
+  Not for: writing the instruction files — use /ai-instruction-standards; language-conventional directory layout — use /project-structure-guide.
   Keywords: architecture, AI-friendly, context, modules, documentation layers, .ai-context.yaml.
 ---
 

package/bundled/skills/ai-instruction-standards/SKILL.md

@@ -4,6 +4,7 @@ scope: partial
 description: |
   Create and maintain AI instruction files (CLAUDE.md, AGENTS.md, .cursor/rules/, etc.) with proper structure.
   Use when: creating AI instruction files, separating universal vs project-specific rules, configuring AI tools.
+  Not for: shaping the codebase so AI can navigate it — use /ai-friendly-architecture; enforcing evidence-based answers — use /ai-collaboration-standards.
   Keywords: CLAUDE.md, AGENTS.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt.
 ---
 

package/bundled/skills/api-design-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide API design following REST, GraphQL, and gRPC best practices.
   Use when: designing APIs, reviewing endpoints, API versioning decisions.
+  Not for: verifying a running API against its consumers — use /contract-test; schema design behind the API — use /database.
   Keywords: API, REST, GraphQL, gRPC, endpoint, versioning.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[API endpoint or module | API 端點或模組]"

package/bundled/skills/atdd-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: atdd
 scope: partial
-description: "[UDS] Guide through Acceptance Test-Driven Development workflow"
+description: |
+  [UDS] Reference for Acceptance Test-Driven Development: INVEST criteria, Gherkin AC format, and Three Amigos structure.
+  Use when: defining acceptance criteria with a product owner, running a specification workshop, checking a user story against INVEST.
+  Not for: executing the ATDD lifecycle or enforcing PO sign-off gates — that moved to the adoption layer (XSPEC-095); writing unit tests — use /tdd.
+  Keywords: ATDD, acceptance test, acceptance criteria, INVEST, specification workshop, Three Amigos, 驗收測試驅動開發, 驗收條件, 規格工作坊.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature or spec | 功能或規格]"
 status: reference

package/bundled/skills/audit-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: audit
 scope: universal
-description: "[UDS] UDS Health & Feedback System"
+description: |
+  [UDS] Diagnose UDS installation health and submit structured feedback upstream.
+  Use when: .standards/ looks broken or out of sync, verifying manifest integrity, reporting friction with an existing UDS standard.
+  Not for: auditing your own application code quality — use /metrics or /code-review; dependency and secret scanning — use /scan.
+  Keywords: UDS audit, health check, manifest integrity, standards feedback, friction, 安裝健康, 標準稽核, 回饋.
 allowed-tools: Read, Grep, Glob, Bash(git log, uds audit)
 argument-hint: "[--health | --patterns | --friction | --report]"
 disable-model-invocation: true

package/bundled/skills/bdd-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: bdd
 scope: partial
-description: "[UDS] Guide through Behavior-Driven Development workflow"
+description: |
+  [UDS] Reference for Behavior-Driven Development: Gherkin Given-When-Then format and Three Amigos structure.
+  Use when: writing or reviewing .feature scenarios, choosing ubiquitous language, running a discovery conversation about behaviour.
+  Not for: executing the BDD lifecycle or RED/GREEN automation — that moved to the adoption layer (XSPEC-095); turning .feature files into E2E skeletons — use /e2e.
+  Keywords: BDD, Gherkin, Given When Then, feature file, scenario, Three Amigos, 行為驅動開發, 場景, 特性檔.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature or spec | 功能或規格]"
 status: reference

package/bundled/skills/brainstorm-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: brainstorm
 scope: universal
-description: "[UDS] Structured AI-assisted brainstorming before spec creation"
+description: |
+  [UDS] Structured multi-persona brainstorming with a scored quality gate, run before a spec exists.
+  Use when: an idea is still vague, exploring alternatives before committing to a direction, needing diversity rather than the first plausible answer.
+  Not for: planning work whose direction is already decided — use /plan or /sdd; recording a decision already made — use /adr.
+  Keywords: brainstorm, ideation, divergence, convergence, persona ensemble, devil advocate, 腦力激盪, 發想, 發散收斂.
 allowed-tools: Read, Glob, Grep, Write
 argument-hint: "[problem or feature idea | 問題或功能構想]"
 ---

package/bundled/skills/changelog-guide/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: changelog
 scope: partial
-description: "[UDS] Generate and maintain CHANGELOG.md entries"
+description: |
+  [UDS] Generate and maintain CHANGELOG.md entries in Keep a Changelog format.
+  Use when: writing changelog entries from commit history, filling the Unreleased section, categorising changes as Added/Changed/Fixed.
+  Not for: choosing the next version number or running the release — use /release; writing the commit messages themselves — use /commit.
+  Keywords: changelog, CHANGELOG.md, Keep a Changelog, release notes, unreleased, 變更日誌, 發布說明, 版本紀錄.
 allowed-tools: Read, Write, Grep, Bash(git log:*)
 disable-model-invocation: true
 ---

package/bundled/skills/checkin-assistant/SKILL.md

@@ -1,10 +1,20 @@
 ---
 name: checkin
 scope: partial
-description: "[UDS] Pre-commit quality gates verification"
+description: |
+  [UDS] Reference for pre-commit quality gates: gate definitions, checklist items, and never-commit rules.
+  Use when: deciding what must pass before a commit, auditing which quality gates a project enforces, checking readiness to check in.
+  Not for: executing the gate sequence or aborting a commit — that moved to the adoption layer (XSPEC-095); finding and removing debug artifacts — use /sweep.
+  Keywords: check-in, pre-commit, quality gate, commit readiness, never commit, 簽入, 提交前檢查, 品質關卡.
 allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git status:*), Bash(npm test:*), Bash(npm run lint:*)
-disable-model-invocation: true
 status: reference
+# 2026-08-17: `disable-model-invocation: true` removed. It was applied by d415937e
+# alongside the description rewrite, and followed no stateable rule — of the six
+# skills carrying `status: reference`, four (tdd, bdd, atdd, pr-automation) were
+# never disabled despite the identical XSPEC-095 relocation. Same category,
+# opposite treatment. The rule is now stateable: a reference is model-invocable.
+# pr-automation-assistant routes "the substance of the review itself" to
+# /code-review, and that referral was unreachable while this flag was set.
 ---
 <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
   Checkin workflow orchestration (gate execution sequence, abort logic) relocated to adoption layer

package/bundled/skills/ci-cd-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide CI/CD pipeline design, configuration, and optimization.
   Use when: setting up pipelines, optimizing build times, configuring deployment stages.
+  Not for: deploying without a CI/CD platform — use /deploy; version bumps and promotion — use /release.
   Keywords: CI/CD, pipeline, GitHub Actions, deployment, build.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[pipeline config or stage | Pipeline 配置或階段]"

package/bundled/skills/code-review-assistant/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: code-review
 scope: universal
-description: "[UDS] Perform systematic code review with checklist"
+description: |
+  [UDS] Reference for systematic code review: eight review categories and BLOCKING/IMPORTANT/SUGGESTION comment prefixes.
+  Use when: reviewing a pull request or diff, deciding how to phrase and prioritise review comments, agreeing review scope with a team.
+  Not for: executing a gated review workflow — that moved to the adoption layer (XSPEC-095); pre-commit gate verification — use /checkin.
+  Keywords: code review, pull request review, review checklist, BLOCKING, comment prefix, 程式碼審查, 審查類別, 評論前綴.
 allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), Bash(git show:*)
 argument-hint: "[file path or branch | 檔案路徑或分支名稱]"
-disable-model-invocation: true
 status: reference
+# 2026-08-17: `disable-model-invocation: true` removed. It was applied by d415937e
+# alongside the description rewrite, and followed no stateable rule — of the six
+# skills carrying `status: reference`, four (tdd, bdd, atdd, pr-automation) were
+# never disabled despite the identical XSPEC-095 relocation. Same category,
+# opposite treatment. The rule is now stateable: a reference is model-invocable.
+# pr-automation-assistant routes "the substance of the review itself" to
+# /code-review, and that referral was unreachable while this flag was set.
 ---
 <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
   Code review workflow orchestration (4-step sequence, outcome gating) relocated to adoption layer

package/bundled/skills/commit-standards/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: commit
 scope: universal
-description: "[UDS] Generate commit messages following Conventional Commits standard"
+description: |
+  [UDS] Generate commit messages that follow Conventional Commits, including the bilingual format.
+  Use when: writing a commit message for staged changes, choosing a type and scope, producing a bilingual English and 中文 subject and body.
+  Not for: deciding whether the change is ready to commit — use /checkin; aggregating commits into release notes — use /changelog.
+  Keywords: commit message, Conventional Commits, feat, fix, refactor, scope, bilingual, 提交訊息, 雙語 commit, 提交規範.
 allowed-tools: Read, Grep, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git add:*), Bash(git commit:*)
 argument-hint: "[description of changes | 變更描述]"
 disable-model-invocation: true

package/bundled/skills/contract-test-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   [UDS] Guide contract testing strategy for APIs and microservices.
   Use when: API contracts, microservices, consumer-driven testing, provider verification.
+  Not for: designing the API surface in the first place — use /api-design; user-visible flows through a UI — use /e2e.
   Keywords: contract test, Pact, OpenAPI, consumer-driven, provider.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[verify | consumer | provider | 策略選擇]"

package/bundled/skills/database-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide database design, migration, and query optimization.
   Use when: schema design, migration planning, query optimization, index strategy.
+  Not for: application code migration or framework upgrades — use /migrate; the API contract over the data — use /api-design.
   Keywords: database, schema, migration, SQL, index, query.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[schema or migration to review | 要審查的 schema 或遷移]"

package/bundled/skills/deploy-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide reliable deployments without CI/CD platforms (GitHub Actions / GitLab CI).
   Use when: deploying to VPS, air-gapped servers, or environments without CI/CD infrastructure.
+  Not for: pipelines on GitHub Actions or GitLab CI — use /ci-cd; version bumps and release promotion — use /release.
   Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback.
 allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
 argument-hint: "[project type | 專案類型: node/python/docker/go]"

package/bundled/skills/dev-methodology/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: methodology
 scope: partial
-description: "[UDS] Manage development methodology workflow"
+description: |
+  [UDS] Select and track the active development methodology (SDD, BDD, TDD) for a project.
+  Use when: deciding which methodology a project should follow, switching methodology, checking which phase the current methodology is in.
+  Not for: finding which command to run at a given development stage — use /dev-workflow; executing a methodology itself — use /sdd, /bdd, or /tdd.
+  Keywords: methodology, SDD, BDD, TDD, phase tracking, methodology selection, 方法論, 開發方法選擇, 階段追蹤.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[action] [argument]"
 ---

package/bundled/skills/dev-workflow-guide/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: dev-workflow
 scope: universal
-description: "[UDS] Guide for mapping software development phases to UDS commands and features"
+description: |
+  [UDS] Map the current software development phase to the right UDS commands and skills.
+  Use when: unsure which UDS command fits the task at hand, onboarding to UDS, walking a feature from planning through release.
+  Not for: choosing or switching a methodology — use /methodology; doing the actual work of a phase — use that phase own skill.
+  Keywords: workflow, development phase, command routing, which command, UDS guide, 開發階段, 指令對照, 流程指南.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[phase name | scenario | 階段名稱 | 場景]"
 ---

package/bundled/skills/docs-generator/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: docgen
 scope: universal
-description: "[UDS] Generate usage documentation from project sources"
+description: |
+  [UDS] Generate usage documentation (cheatsheets, references, guides) from project sources.
+  Use when: producing a cheatsheet or feature reference from CLI and skill definitions, regenerating docs after commands change, checking generated docs are current.
+  Not for: deciding what documentation a project needs or writing prose by hand — use /documentation-guide; changelog entries — use /changelog.
+  Keywords: docgen, usage docs, cheatsheet, feature reference, generated documentation, 使用文件, 速查表, 文件產生.
 allowed-tools: Read, Write, Grep, Glob, Bash(*)
 argument-hint: "[config file | 設定檔]"
 disable-model-invocation: true

package/bundled/skills/documentation-guide/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide documentation structure, content requirements, and project documentation best practices.
   Use when: creating README, documentation, docs folder, project setup, technical docs.
+  Not for: generating docs mechanically from source — use /docgen; changelog entries — use /changelog.
   Keywords: README, docs, documentation, CONTRIBUTING, CHANGELOG, ARCHITECTURE, API docs.
 ---
 

package/bundled/skills/durable-execution-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: durable
 scope: partial
-description: "[UDS] Guide workflow failure recovery with checkpoints, retries, and rollback"
+description: |
+  [UDS] Guide fault-tolerant workflow design with checkpoints, retry policies, and rollback plans.
+  Use when: a long-running workflow keeps failing partway, designing checkpoint granularity, choosing a retry or backoff strategy.
+  Not for: responding to a production incident already in progress — use /incident; deployment rollback mechanics — use /deploy.
+  Keywords: durable execution, checkpoint, retry, backoff, idempotency, rollback, 持久執行, 檢查點, 重試策略.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[workflow name or failure context | 工作流名稱或失敗情境]"
 ---

package/bundled/skills/e2e-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: e2e
 scope: partial
-description: "[UDS] Generate E2E test skeletons from BDD scenarios"
+description: |
+  [UDS] Generate E2E test skeletons from BDD .feature scenarios, with framework detection and coverage gap analysis.
+  Use when: turning finished .feature scenarios into runnable E2E skeletons, detecting the project E2E framework, finding AC with no E2E coverage.
+  Not for: multi-story journeys with shared state — use the journey-test skill; writing the .feature scenarios themselves — use /bdd.
+  Keywords: E2E, end-to-end test, feature file, test skeleton, framework detection, 端對端測試, 測試骨架, 場景轉測試.
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*)
 argument-hint: "[feature file or --analyze | .feature 檔案或 --analyze]"
 status: experimental

package/bundled/skills/error-code-guide/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Design consistent error codes following the PREFIX_CATEGORY_NUMBER format.
   Use when: defining error codes, creating error handling, designing APIs.
+  Not for: log format and levels — use /logging-guide; handling errors that already reached production — use /incident.
   Keywords: error code, error handling, error format, API errors.
 ---
 

package/bundled/skills/git-workflow-guide/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide Git branching strategies, branch naming, and merge operations.
   Use when: creating branches, merging, pull requests, Git workflow questions.
+  Not for: composing the commit message — use /commit; the safety checks around pushing — use /push.
   Keywords: branch, merge, PR, pull request, GitFlow, GitHub Flow.
 ---
 

package/bundled/skills/incident-response-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide incident response, root cause analysis, and post-mortem documentation.
   Use when: production incident, outage response, post-mortem writing, RCA.
+  Not for: designing retries and checkpoints before failure — use /durable; setting alert thresholds and Error Budget policy — use /slo.
   Keywords: incident, outage, post-mortem, RCA, root cause.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[incident description or severity | 事故描述或嚴重程度]"

package/bundled/skills/journey-test-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: journey-test-assistant
 scope: partial
-description: "[UDS] Generate coherent user journey test plans (TESTPLAN) and E2E skeletons from project description."
+description: |
+  [UDS] Generate coherent user-journey test plans (TESTPLAN) and journey E2E skeletons from a project description.
+  Use when: a new project needs a test journey from day one, testing state carried across multiple stories, building persona-driven journey plans.
+  Not for: isolated per-AC E2E skeletons — use /e2e; measuring achieved code coverage — use /coverage.
+  Keywords: user journey, TESTPLAN, journey test, persona, cross-story state, 使用者旅程, 旅程測試, 測試計畫.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[project description | --analyze | --archetype A1|A2|A3]"
 status: stable

package/bundled/skills/knowledge-graph/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: knowledge-graph
 scope: partial
-description: "[UDS] Trace spec/decision/code impact chains via a knowledge graph (engine or Markdown fallback)"
+description: |
+  [UDS] Trace impact chains across specs, decisions, and code via a knowledge graph, with a Markdown fallback when no engine is present.
+  Use when: asking what a spec or decision affects, finding which code implements an artifact, tracing dependencies between specs, ADRs, and modules.
+  Not for: plain text search with no spec or decision anchor — use Grep; authoring the spec itself — use /sdd.
+  Keywords: knowledge graph, impact chain, traceability, spec impact, decision graph, 知識圖, 影響鏈, 規格追蹤.
 allowed-tools: Read, Glob, Grep, Bash(curl:*)
 argument-hint: "[artifact id, e.g. XSPEC-205 | 產物 id]"
 ---

package/bundled/skills/logging-guide/SKILL.md

@@ -5,6 +5,7 @@ anchor_standard: logging-standards
 description: |
   Implement structured logging with proper log levels and sensitive data handling.
   Use when: adding logging, debugging, setting up observability.
+  Not for: metrics, traces, and alerting design — use /observability; error code taxonomy — use /error-code-guide.
   Keywords: logging, log level, structured logging, observability.
 ---
 

package/bundled/skills/metrics-dashboard-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: metrics
 scope: universal
-description: "[UDS] Track development metrics, code quality indicators, and project health"
+description: |
+  [UDS] Track development metrics, code quality indicators, and technical debt over time.
+  Use when: assessing ongoing project health, classifying and trending technical debt, reporting code quality to a team.
+  Not for: first-time assessment of an unfamiliar codebase — use /discover; test coverage specifically — use /coverage or /ac-coverage.
+  Keywords: metrics, code quality, technical debt, project health, debt trend, 開發指標, 技術債, 專案健康度.
 allowed-tools: Read, Grep, Glob, Bash(npm:*, git:log)
 argument-hint: "[metric type or module | 指標類型或模組]"
 ---

package/bundled/skills/migration-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: migrate
 scope: universal
-description: "[UDS] Guide code migration, framework upgrades, and technology modernization"
+description: |
+  [UDS] Guide systematic code migration, framework upgrades, and technology modernization.
+  Use when: planning a framework or major-version upgrade, assessing migration risk, capturing contract-test fixtures before an API migration.
+  Not for: in-place improvement that keeps the same framework — use /refactor; database schema design — use /database.
+  Keywords: migration, framework upgrade, modernization, breaking change, dependency upgrade, 遷移, 升級, 技術現代化.
 allowed-tools: Read, Grep, Glob, Bash(npm:*, git:*)
 argument-hint: "[migration target or framework | 遷移目標或框架]"
 ---

package/bundled/skills/observability-assistant/SKILL.md

@@ -5,6 +5,7 @@ anchor_standard: observability-standards
 description: |
   Guide observability setup, metrics design, and alerting configuration.
   Use when: new service instrumentation, SLO definition, alert design, maturity assessment.
+  Not for: setting numeric targets and Error Budget policy — use /slo; log format and levels — use /logging-guide.
   Keywords: observability, metrics, traces, golden signals, alerting, SLO.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[service name or observability topic | 服務名稱或可觀測性主題]"

package/bundled/skills/orchestrate/SKILL.md

@@ -5,6 +5,7 @@ scope: universal
 description: |
   Orchestrate multi-task execution plans using Claude's native Agent tool (DAG-based, no external engine).
   Use when: executing a plan.json file with parallel/sequential task dependencies.
+  Not for: producing the plan in the first place — use /plan; single tasks with no dependencies between them.
   Keywords: orchestrate, plan, execute, DAG, task plan.
 argument-hint: "<plan.json> [--dry-run]"
 ---

package/bundled/skills/plan/SKILL.md

@@ -5,6 +5,7 @@ scope: universal
 description: |
   Generate plan.json from Spec documents, OpenSpec changes, or free-text requirements.
   Use when: converting specifications into executable task plans for /orchestrate.
+  Not for: executing the resulting plan — use /orchestrate; deciding whether the idea is worth doing — use /brainstorm.
   Keywords: plan, spec, task plan, plan.json, DAG.
 argument-hint: "[spec-file.md | openspec-dir/ | \"requirement text\" | (interactive)]"
 ---

package/bundled/skills/pr-automation-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide pull request creation, review automation, and merge strategies.
   Use when: creating PRs, automating reviews, configuring merge policies.
+  Not for: the substance of the review itself — use /code-review; branch naming and merge strategy — use /git-workflow-guide.
   Keywords: pull request, PR, merge, review, GitHub, GitLab.
 allowed-tools: Read, Grep, Glob, Bash(git:*, gh:*)
 argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"

package/bundled/skills/project-discovery/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: discover
 scope: universal
-description: "[UDS] Assess project health, architecture, and risks before adding features"
+description: |
+  [UDS] Assess project health, architecture, and risks before adding features to an existing codebase.
+  Use when: onboarding to an unfamiliar or legacy project, sizing risk before starting a feature, building a risk register.
+  Not for: ongoing metric tracking on a codebase you already know — use /metrics; recovering specs from code — use /reverse.
+  Keywords: discovery, project assessment, legacy onboarding, risk register, technical debt, 現況評估, 專案盤點, 風險登記簿.
 allowed-tools: Read, Grep, Glob, Bash(npm test:*), Bash(npm audit:*), Bash(npm outdated:*)
 argument-hint: "[feature area | 功能範圍]"
 disable-model-invocation: true

package/bundled/skills/project-structure-guide/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide for organizing project directories following language-specific best practices.
   Use when: creating projects, reorganizing structure, adding modules, setting up builds, deciding file placement.
+  Not for: structuring specifically for AI navigation — use /ai-friendly-architecture; restructuring existing code in place — use /refactor.
   Keywords: project, structure, directory, layout, gitignore, scaffold, file placement, utils, helpers, shared, where to put.
 ---
 

package/bundled/skills/push/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   AI-assisted safety layer for git push operations with quality gates and collaboration guardrails.
   Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
+  Not for: composing the commit — use /commit; branch and merge strategy decisions — use /git-workflow-guide.
   Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation.
 allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(bun:*)
 argument-hint: "[--force] [--target <branch>] [--skip-gates] [--no-pr]"

package/bundled/skills/refactoring-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: refactor
 scope: universal
-description: "[UDS] Guide refactoring decisions and strategy selection"
+description: |
+  [UDS] Guide refactoring decisions and strategy selection, including the refactor-versus-rewrite call.
+  Use when: code has become hard to change, choosing between tactical and architectural refactoring, working safely inside legacy code.
+  Not for: moving to a different framework or major version — use /migrate; clearing debug artifacts and dead code — use /sweep.
+  Keywords: refactor, rewrite, strangler, legacy code, technical debt, code smell, 重構, 重寫, 技術債.
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
 argument-hint: "[file or module | 檔案或模組]"
 ---

package/bundled/skills/release-standards/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: release
 scope: universal
-description: "[UDS] Guide release process and changelogs"
+description: |
+  [UDS] Guide the release process — semantic versioning, release modes, and the start/finish/promote/deploy sequence.
+  Use when: cutting a release, deciding a semantic version bump, promoting a release candidate to stable, recording a deployment.
+  Not for: writing the changelog entries themselves — use /changelog; the deployment mechanics — use /deploy.
+  Keywords: release, semantic versioning, version bump, release candidate, promote, 發布, 語意化版本, 發版流程.
 allowed-tools: Read, Write, Grep, Bash(git:*), Bash(npm version:*)
 argument-hint: "[version]"
 prerequisites: ["release-check"]

package/bundled/skills/requirement-assistant/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: requirement
 scope: universal
-description: "[UDS] Write user stories and requirements following INVEST criteria"
+description: |
+  [UDS] Write user stories and requirements that satisfy the INVEST criteria.
+  Use when: turning a feature idea into a user story, defining testable acceptance criteria, checking a backlog item for quality.
+  Not for: full specification documents with design and delta operations — use /sdd; deciding whether the idea is right at all — use /brainstorm.
+  Keywords: requirement, user story, INVEST, acceptance criteria, backlog refinement, 需求, 使用者故事, 驗收條件.
 allowed-tools: Read, Write, Grep
 argument-hint: "[feature description | 功能描述]"
 ---

package/bundled/skills/retrospective-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   [UDS] Guide structured team retrospectives for Sprint and Release cycles.
   Use when: sprint end, release post-mortem, iteration review, process improvement.
+  Not for: post-mortems for a production incident — use /incident; tracking metric trends between retros — use /metrics.
   Keywords: retrospective, retro, sprint review, lessons learned, action items.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[sprint | release | actions | --technique starfish]"

package/bundled/skills/reverse-engineer/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: reverse
 scope: partial
-description: "[UDS] System archeology - reverse engineer code across Logic, Data, and Runtime dimensions"
+description: |
+  [UDS] System archeology — reverse engineer an existing system across the Logic, Data, and Runtime dimensions.
+  Use when: documenting an undocumented system, recovering specifications from existing code, mapping an unknown data model or runtime topology.
+  Not for: assessing health and risk before a feature — use /discover; deriving tests forward from an approved spec — use /spec-derive.
+  Keywords: reverse engineering, system archeology, legacy code, spec extraction, data model, runtime, 反向工程, 系統考古, 規格提取.
 allowed-tools: Read, Grep, Glob, Bash(pg_dump:*), Bash(mysql:*), Bash(sqlite3:*), Bash(npm run:*), Bash(cat:*), Bash(docker:*)
 argument-hint: "[spec|data|runtime|bdd|tdd] <input>"
 disable-model-invocation: true

package/bundled/skills/runbook-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide runbook creation, maintenance, and drill exercises.
   Use when: writing runbooks, planning drills, auditing runbook coverage, post-incident runbook updates.
+  Not for: responding to an incident already in progress — use /incident; the deployment procedure itself — use /deploy.
   Keywords: runbook, operations, drill, on-call, procedure.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[create|drill|coverage] [alert name or type | 告警名稱或類型]"

package/bundled/skills/security-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide security review and vulnerability assessment following OWASP standards.
   Use when: security audit, vulnerability check, secure coding review, threat modeling.
+  Not for: automated dependency, CVE, and secret scanning — use /scan; handling a breach in progress — use /incident.
   Keywords: security, OWASP, vulnerability, authentication, authorization.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[module or file to audit | 要審計的模組或檔案]"

package/bundled/skills/security-scan-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide automated security scanning, dependency auditing, and secret detection.
   Use when: dependency audit, CVE scanning, secret detection, license compliance.
+  Not for: manual threat modeling and secure design review — use /security; general code cleanliness — use /sweep.
   Keywords: scan, audit, CVE, dependency, secret, SBOM, vulnerability.
 allowed-tools: Read, Grep, Glob, Bash(npm:audit, npx:*)
 argument-hint: "[scan type or target | 掃描類型或目標]"

package/bundled/skills/skill-builder/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: skill-builder
 scope: universal
-description: "[UDS] Identify repeated processes and build Skills with the right development depth"
+description: |
+  [UDS] Turn a repeated manual process into a properly scoped Skill, with the right amount of process along the way.
+  Use when: the same multi-step sequence has been done manually three or more times, formalising an ad-hoc Skill, deciding where a Skill belongs.
+  Not for: recording historical facts or project state — that belongs in memory, not a Skill; one-off tasks that will not recur.
+  Keywords: skill, skill builder, process knowledge, repeated process, automation, 技能建立, 流程知識, 自動化.
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash
 argument-hint: "[process description | 流程描述]"
 ---

package/bundled/skills/slo-assistant/SKILL.md

@@ -4,6 +4,7 @@ scope: universal
 description: |
   Guide SLI selection, SLO setting, and Error Budget management.
   Use when: defining service quality targets, setting up SLO-based alerting, Error Budget policy.
+  Not for: instrumentation and metric collection — use /observability; responding to an active breach of the target — use /incident.
   Keywords: SLI, SLO, SLA, Error Budget, burn rate, service level.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[create|review|budget] [service name | 服務名稱]"