solmate-skills 2.0.11 → 2.0.12

package/AGENTS.md

@@ -160,3 +160,5 @@ AI 에이전트는 사용자가 스킬을 호출하지 않아도, 아래 상황
 
 ## 6. 최종 약속
 AI 에이전트는 본 **AGENTS.md**를 모든 판단의 최우선 근거로 삼는다. 문서에 정의되지 않은 작업을 수행할 경우 반드시 사용자에게 구현 전 문서 업데이트 필요성을 먼저 확인한다.
+
+**사람용 스킬 사용법** (상황별 선택, 26개 카탈로그, Gate 상세): 프로젝트 루트 `USAGE.md` — 영문 기본, 하단 한국어 (`npx solmate-skills install` 시 복사).

package/CLAUDE.md

@@ -23,7 +23,7 @@ There are no build, test, or lint scripts in this repo (`"test": "echo \"Error:
 
 ## Installing Skills via Symlink (Dev)
 
-`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, and links `AGENTS.md` to the project root. Run it from inside the target project:
+`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, and links `AGENTS.md` and `USAGE.md` to the project root. Run it from inside the target project:
 
 ```bash
 bash /Users/namhyeongseog/Documents/solmate-skills/init-skills.sh

package/README.md

@@ -24,7 +24,9 @@ npx solmate-skills@latest install rules-product
 npx solmate-skills@latest install hooks
 ```
 
-The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project.
+The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project and copies [USAGE.md](./USAGE.md) to the project root.
+
+**Detailed usage:** see `USAGE.md` at the project root (English default, Korean below) for the situation-to-skill cheat sheet, orchestrator map, full skill catalog (26 skills), gate details, and recommended prompts.
 
 ## What You Get
 
@@ -37,6 +39,15 @@ The installer copies each selected skill folder into `.agent/skills/<skill-name>
 - **Implementation workflow**: `/rules-workflow` keeps coding work tied to approved documents, preconditions, and acceptance criteria.
 - **Release verification**: `/verify-implementation` runs the verification family for docs, UI, code, security, performance, DB schema, and skill package readiness.
 
+## What's New in 2.0.12
+
+`solmate-skills@2.0.12` adds a bilingual usage guide and copies it into every target project on install.
+
+- [USAGE.md](./USAGE.md) documents all 26 skills in English (default) with Korean below: cheat sheet, orchestrator map, gates, and prompts.
+- `npx solmate-skills install` (single skill, `all`, or `hooks`) now copies `USAGE.md` to the project root.
+- [README.md](./README.md) is trimmed to a 5-minute start; detailed usage lives in `USAGE.md`.
+- `init-skills.sh` symlinks `USAGE.md` alongside `AGENTS.md` for local development.
+
 ## What's New in 2.0.11
 
 `solmate-skills@2.0.11` adds a Component & Library Planning Gate so React implementation starts from approved UI context and an explicit component/library plan.
@@ -81,24 +92,33 @@ Recent workflow guardrails:
 
 ## Quick Start
 
-설치 후 상황에 맞는 스킬을 하나 실행하는 것으로 시작합니다.
+Install skills, then invoke one command based on your situation.
 
-| 상황 | 시작 명령 | 설명 |
+| Situation | Start with | Notes |
 |:---|:---|:---|
-| 신규 프로젝트 — 아무것도 없을 때 | `/rules-product` | 현재 단계를 자동 진단하고 Phase 1부터 순서대로 안내 |
-| 기획은 있고 코드를 작성하려 할 때 | `/rules-dev` | 커밋 형식, 환경변수, TypeScript 기준 등 컨벤션 먼저 정립 |
-| 기능 하나를 구현하려 할 때 | `/rules-product` → `/rules-workflow` | 현재 Phase를 먼저 진단한 뒤 계획 수립부터 PR까지 진행 |
-| PR 전 최종 점검 | `/verify-implementation` | 모든 `verify-*` 스킬을 순차 실행하여 통합 보고 |
+| New project or "where do I start?" | `/rules-product` | Diagnoses phase and delegates to the right skill |
+| Implement one feature | `/rules-product` then `/rules-workflow` | Gates must pass before coding |
+| Pre-PR / pre-release check | `/verify-implementation` | Runs the verify-* family in order |
 
-**가장 권장하는 시작 한 줄:**
+**Recommended first line:**
 
-```
+```text
 /rules-product
 ```
 
-`rules-product`는 프로젝트 상태를 스스로 진단해 현재 어느 단계인지 파악하고, 해당 단계의 올바른 스킬로 위임하는 오케스트레이터입니다. 새 프로젝트든 재개 중인 프로젝트든 동일하게 사용할 수 있습니다.
+### Orchestrator map
+
+```text
+rules-product  →  diagnose phase, check gates, delegate
+rules-workflow →  plan → implement → verify → PR (18 steps)
+verify-implementation →  run verify-* skills and report
+```
+
+Full pipeline, gates, backlog template, and all 26 skill entries: **[USAGE.md](./USAGE.md)**
+
+### Flow Status Block
 
-`rules-product` and `rules-workflow` should show a short Flow Status Block at the start of work, before implementation, before verification, and at handoff:
+`rules-product` and `rules-workflow` report progress in this format:
 
 ```text
 [Flow]
@@ -110,301 +130,44 @@ Gate: UI-First Gate 진행 중
 권장 스킬: /docs-plan
 ```
 
-### Using Skills in an Existing Project
+### Existing projects
 
-이미 진행 중인 프로젝트에도 최신 `solmate-skills`를 다시 설치해서 사용할 수 있습니다. 사용 방식은 신규 프로젝트와 같지만, 시작점은 항상 현재 프로젝트 상태를 먼저 진단하는 것입니다.
-
-**Update or reinstall skills from the project root:**
+Reinstall from the project root, then diagnose — do not restart from Phase 1 by default.
 
 ```bash
 npx solmate-skills@latest install all
 npx solmate-skills@latest install hooks
 ```
 
-**Recommended first prompt:**
-
-```text
-/rules-product를 사용해서 이 프로젝트의 현재 진행 상태를 진단하고, 다음 작업을 Flow Status Block 기준으로 안내해줘.
-```
-
-**When starting implementation work:**
-
-```text
-/rules-workflow를 사용해서 현재 기능 작업을 진행해줘. 먼저 Flow Status Block으로 현재 위치를 알려주고, UI-First 흐름에 맞춰 진행해줘.
-```
-
-**When verifying finished work:**
-
-```text
-/verify-implementation으로 현재 변경사항을 전체 검증해줘. Flow Status Block을 포함해서 보고해줘.
-```
-
-진행 중인 프로젝트에서는 Phase 1부터 강제로 다시 시작하지 않습니다. `/rules-product`가 기존 문서, 코드, 백로그, 변경사항을 보고 현재 위치를 진단한 뒤, 이어서 진행할 Phase와 필요한 Gate를 제안해야 합니다.
+Example prompts: [USAGE.md §9 Recommended Prompts](./USAGE.md#9-recommended-prompts) (EN) · [§9 권장 프롬프트](./USAGE.md#9-권장-프롬프트-모음) (KO)
 
 ---
 
-## Available Skills
+## Skills at a Glance
 
-Skills are organized into five categories.
+26 installable skills plus `hooks`. Category summary:
 
-### Governance
-
-| Skill | Description |
+| Category | Skills |
 |:---|:---|
-| `role-team-lead` | Team lead protocols: branch protection, PR review, DB migration, deployment. |
-| `role-team-member` | Team member protocols: branching, Conventional Commits (Korean), PR creation. |
-
-### Rules
-
-| Skill | Description |
-|:---|:---|
-| `rules-docs` | Master documentation rules and 365 Principle governance. |
-| `rules-dev` | Enforce development setup, coding conventions, and quality rules. |
-| `rules-react` | Create modular, premium React components and pages. |
-| `rules-workflow` | Full 18-step implementation and execution lifecycle. |
-| `rules-product` | Orchestrate the full product development pipeline. |
-| `manage-collaboration` | Enforce AI-Human collaboration standards. |
-| `manage-decisions` | Question-driven decision making for tech, DB, API, UX, and architecture choices. |
-| `manage-skills` | Detect and fix drift between verify skills and changed code. |
-
-### Documentation
-
-| Skill | Description |
-|:---|:---|
-| `docs-plan` | Create and manage **planning documents** (Layer 1-2: vision, UI screens). |
-| `docs-dev` | Create and manage **development documents** (Layer 3-5: specs, logic, QA). |
-| `docs-pitch` | Create pitch decks for investors, hackathons, and demo days. |
-| `docs-business` | Generate professional business plans for funding or partnerships. |
-| `verify-docs` | Audit documentation structure and metadata standards. |
-
-### Special Tools
-
-| Skill | Description |
-|:---|:---|
-| `tools-shadcn` | Expert guidance for shadcn/ui components. |
-| `tools-obsidian` | Sync documentation with an Obsidian vault. |
-
-### External Extensions
-
-| Skill | Description |
-|:---|:---|
-| `ext-awesome-design` | Premium design system and markdown templates. |
-| `ext-k-skill` | Collection of specialized Korean tools and services. |
-
-### Quality & Automation
-
-| Skill | Description |
-|:---|:---|
-| `verify-implementation` | Dynamically discover and run all `verify-*` skills. |
-| `verify-drizzle-schema` | Verify Drizzle ORM schema matches architecture specs. |
-| `verify-security` | Check for security vulnerabilities based on OWASP Top 10. |
-| `verify-performance` | Lighthouse & Core Web Vitals check. |
-| `verify-code` | Comprehensive pre-PR code quality review. |
-| `verify-ui` | Verify implemented UI against screen docs, HTML previews, and user flows. |
-| `verify-skills` | Verify skill package metadata, CLI output, and release readiness. |
-
----
-
-## Usage Guide
-
-### Documentation System
-
-The documentation system follows the **365 Principle** (3 Investor Lenses, 6 Rubrics, 5 Documentation Layers) and is split across two skills based on the type of document.
-
-**Which skill to use:**
-
-```
-Product vision, Lean Canvas, UI design  →  docs-plan
-DB schema, API specs, roadmap, QA       →  docs-dev
-Unsure which layer?                     →  rules-docs
-```
-
-**5-Layer structure:**
-
-```
-docs/
-├── 01_Concept_Design/   ← docs-plan
-├── 02_UI_Screens/       ← docs-plan
-├── 03_Technical_Specs/  ← docs-dev
-├── 04_Logic_Progress/   ← docs-dev
-└── 05_QA_Validation/    ← docs-dev
-```
-
-**Typical workflow:**
-
-```
-1. /docs-plan    → Write VISION_CORE.md, LEAN_CANVAS.md, PRODUCT_SPECS.md
-2. /docs-plan    → Write SCREEN_FLOW.md, UI_DESIGN.md, and HTML UI previews
-3. HTML UI Preview Gate → Show browser-viewable HTML screens and capture user feedback
-4. UI-First Gate → Confirm screens, user paths, data flow, and UI states before coding
-5. Pre-Code Technical Brief → Confirm data sources, API shape, state strategy, and acceptance criteria
-6. Component & Library Planning Gate → Confirm shadcn components, custom components, reused components, and libraries
-7. /docs-dev     → Write DEVELOPMENT_PRINCIPLES.md, DB_SCHEMA.md, API_SPECS.md
-8. /docs-dev     → Write ROADMAP.md, BACKLOG.md with mandatory related document links
-9. /rules-workflow → Implement each backlog item only after reading linked docs and passing UI-First and Component & Library gates
-10. /verify-implementation  → Audit docs, UI, code, security, performance, DB, and skill package changes
-```
-
-Backlog items are intentionally document-linked. Each task in `docs/04_Logic_Progress/00_BACKLOG.md` must include related Concept, UI, Technical Spec, and QA documents, plus implementation preconditions, acceptance criteria, and a document sync check. If a related document does not exist, the item must say `N/A - 사유`; implementation should pause when the missing document is required for a safe decision.
-
-### Backlog Context Lock
-
-Backlog Context Lock makes `docs/04_Logic_Progress/00_BACKLOG.md` act as a bridge between planning documents and implementation. A backlog item is not considered ready for coding until it names the documents that define why the task exists, how the UI should behave, what technical constraints apply, and how the work will be verified.
-
-### UI-First Gate
-
-UI-First Gate prevents implementation from starting before the team has reviewed the actual screens and the user's path through them. Before coding, confirm the core screen structure, user entry and exit paths, CTAs, screen-by-screen data flow, loading states, empty states, and error states. If these are missing, update `docs/02_UI_Screens/`, its HTML previews, or the backlog first.
+| Orchestration | `rules-product`, `rules-workflow` |
+| Rules | `rules-docs`, `rules-dev`, `rules-react`, `manage-collaboration`, `manage-decisions`, `manage-skills` |
+| Documentation | `docs-plan`, `docs-dev`, `docs-pitch`, `docs-business` |
+| Verification | `verify-implementation`, `verify-docs`, `verify-ui`, `verify-code`, `verify-security`, `verify-performance`, `verify-drizzle-schema`, `verify-skills` |
+| Roles | `role-team-lead`, `role-team-member` |
+| Tools | `tools-shadcn`, `tools-obsidian` |
+| External | `ext-awesome-design`, `ext-k-skill` |
 
-### HTML UI Preview Gate
-
-UI planning documents are not complete with Markdown alone. For every major screen or user flow, create a browser-viewable HTML preview and store it under:
-
-```text
-docs/02_UI_Screens/previews/
-```
-
-Recommended naming:
-
-```text
-docs/02_UI_Screens/previews/01_main_flow_preview.html
-docs/02_UI_Screens/previews/02_dashboard_preview.html
-```
-
-Each related UI document must link to the HTML file with a relative path. The preview must be shown to the user before implementation, and feedback must be captured in `XX_PROTOTYPE_REVIEW.md`, `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, or the related backlog item.
-
-### Component & Library Planning Gate
-
-React implementation should not begin until the team has listed the UI building blocks and library choices. Record the shadcn/ui components to add, custom components to create, existing components to reuse, libraries to install, libraries intentionally not added, and whether the project needs `init --preset`, `apply --preset`, `apply --only theme`, or `N/A - reason`.
-
-Required fields for every backlog item:
-
-- `Related Concept Docs`
-- `Related UI Docs`
-- `Related HTML Preview`
-- `Related Technical Docs`
-- `Related QA Docs`
-- `Implementation Preconditions`
-- `Component & Library Plan`
-- `Acceptance Criteria`
-- `Document Sync Check`
-
-If a related document does not exist, write `N/A - 사유`. Do not leave the field blank. If the missing document is required to make a safe implementation decision, pause implementation and write or update the document first.
-
-**Backlog item template:**
-
-```markdown
-### [ ] TASK-000: Implement feature name
-
-- Status: ToDo
-- Related Concept Docs:
-  - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
-- Related UI Docs:
-  - [Screen Flow](../02_UI_Screens/00_SCREEN_FLOW.md) - target screen and interaction flow
-- Related HTML Preview:
-  - [Main Flow Preview](../02_UI_Screens/previews/01_main_flow_preview.html) - browser-viewable UI for user review
-- Related Technical Docs:
-  - [API Specs](../03_Technical_Specs/02_API_SPECS.md) - endpoint and data contract
-- Related QA Docs:
-  - [QA Checklist](../05_QA_Validation/02_QA_CHECKLIST.md) - acceptance and release criteria
-- Implementation Preconditions:
-  - [ ] Read all related documents before coding
-  - [ ] Confirm screen/UI before coding
-  - [ ] Show the HTML UI preview to the user and capture feedback
-  - [ ] Confirm user path and screen-by-screen data flow
-  - [ ] Confirm loading, empty, and error states
-  - [ ] Confirm implementation scope does not conflict with documented intent
-- Component & Library Plan:
-  - shadcn/ui components: button, card, form, or `N/A - reason`
-  - Custom components: feature-specific components or `N/A - reason`
-  - Reused components: existing paths or `N/A - reason`
-  - New libraries: package names and reasons or `N/A - reason`
-  - Libraries intentionally not added: rejected options and reasons or `N/A - reason`
-  - shadcn preset action: init --preset / apply --preset / apply --only theme / N/A - reason
-- Acceptance Criteria:
-  - [ ] Feature follows the confirmed screen structure and user path
-  - [ ] Feature behavior matches linked Concept/UI/Technical docs
-  - [ ] QA criteria are testable and satisfied
-- Document Sync Check:
-  - [ ] No mismatch between implementation and linked documents
-  - [ ] Update related documents if implementation changes the agreed behavior
-```
+**Situation cheat sheet, per-skill when/prerequisites/outputs/next:** [USAGE.md](./USAGE.md)
 
 ---
 
-### Pitch Deck
-
-Create a pitch deck from existing `docs-plan` documents.
+## Hooks (optional)
 
-**Prerequisites:** `docs-plan` Layer 1 documents (VISION_CORE, LEAN_CANVAS, PRODUCT_SPECS) should exist first.
-
-**Output modes:**
-
-| Mode | When to use | Output |
-|:---|:---|:---|
-| Markdown | Content-first, will export to Notion/Slides | `docs/01_Concept_Design/XX_PITCH_DECK.md` |
-| Reveal.js HTML | Present directly in browser, deploy to GitHub Pages | `pitch/index.html` |
-
-**Typical workflow:**
-
-```
-1. /docs-plan    → Ensure VISION_CORE, LEAN_CANVAS, PRODUCT_SPECS exist
-2. /docs-pitch   → Select output mode → Answer Phase 0-2 questions → Generate deck
-```
-
----
-
-### Development Workflow
-
-**Typical workflow:**
-
-```
-1. /rules-dev                → Review conventions before writing code
-2. /rules-product            → Orchestrate the development pipeline
-3. /verify-implementation    → Run all verify-* skills before PR
-4. /manage-collaboration     → Check branch naming, PR format, and workflow status
-```
-
----
-
-### Governance
-
-**Role-based skills** define protocols for team lead and team member roles:
-
-```
-/role-team-lead    → Branch protection, PR review, DB migration, deployment
-/role-team-member  → Branching, commits (Conventional Commits in Korean), PR creation
-```
-
----
-
-### Proactive Skill Suggestions (Hooks)
-
-Install hook scripts so Claude **automatically suggests** the right skill as you work — without needing to invoke them manually.
-
-**Two layers work together:**
-
-| Layer | Mechanism | Trigger |
-|:---|:---|:---|
-| Method 1 | AGENTS.md rules | Claude judges context and suggests skills by reasoning |
-| Method 2 | Hook scripts | Keyword/file-pattern matching fires on every prompt or file edit |
-
-**Install hooks into your project:**
+For Claude Code, install hooks to get keyword and file-pattern skill suggestions:
 
 ```bash
-# 1. Install the hooks skill first (if not already installed)
-npx solmate-skills install hooks
-
-# 2. Run the installer from your project root
+npx solmate-skills@latest install hooks
 bash .agent/skills/hooks/install.sh
 ```
 
-This copies two scripts to `.claude/hooks/` and merges the hook config into `.claude/settings.json`:
-
-| Script | Event | What it detects |
-|:---|:---|:---|
-| `solmate-suggest.sh` | UserPromptSubmit | Keywords: 결정/설계, 보안, 성능, PR, 코드리뷰, 문서, 기능구현, 피치덱, 새 프로젝트 |
-| `solmate-watch.sh` | PreToolUse | File patterns: `schema.ts`, `.env*`, `SKILL.md`, `page.tsx`, `api/route.ts`, `auth.ts`, `AGENTS.md` |
-
-**To review or disable hooks:** open `/hooks` in Claude Code.
-
-**To uninstall:** remove `.claude/hooks/` and the `hooks` section from `.claude/settings.json`.
+Details: [USAGE.md §8 Hooks](./USAGE.md#8-hooks-claude-code-suggestions) (EN) · [§8 Hooks 한국어](./USAGE.md#8-hooks-claude-code-자동-제안) (KO)

package/USAGE.md

@@ -0,0 +1,787 @@
+# solmate-skills Usage Guide
+
+<a id="solmate-skills-usage-guide"></a>
+
+Created Date: 2026-06-25 03:00  
+Last Updated Date: 2026-06-29 15:20
+
+**Language:** English (default) · [Korean version below](#solmate-skills-usage-guide-korean)
+
+This is a **human-readable** guide for choosing and invoking skills.  
+Agent execution rules live in each `SKILL.md` and the installed `AGENTS.md`.
+
+---
+
+## 1. How to Invoke Skills
+
+### Cursor / Claude Code (recommended)
+
+Use slash commands or natural language in chat:
+
+```text
+/rules-product
+Use /rules-workflow to implement this feature
+Run /verify-implementation on the current changes
+```
+
+### Install locations
+
+```bash
+npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
+npx solmate-skills@latest install hooks    # Claude Code suggestions (optional) + ./USAGE.md
+```
+
+Every `install` command (single skill, `all`, or `hooks`) copies `USAGE.md` to the **project root**.
+
+### Local development (symlink)
+
+When hacking on the `solmate-skills` repo itself:
+
+```bash
+# Run from the target project root
+bash /path/to/solmate-skills/init-skills.sh
+```
+
+This symlinks `.agent/skills/` to the repo and links `AGENTS.md` and `USAGE.md` at the project root.
+
+---
+
+## 2. Situation Cheat Sheet
+
+| You say / situation | Skill | Notes |
+|:---|:---|:---|
+| "Where do I start?" / new project | `rules-product` | **Recommended entry point** |
+| "Where are we?" / resume work | `rules-product` | Phase diagnosis, then delegate |
+| Vision, Lean Canvas, UI docs | `docs-plan` | Layers 1–2 |
+| DB, API, backlog, QA docs | `docs-dev` | Layers 3–5 |
+| Unsure which doc layer | `rules-docs` | 5-layer and gate rules |
+| Implement a feature / pre-commit·PR | `rules-workflow` | 18-step workflow |
+| React screens / components | `rules-react` | Component & Library Plan first |
+| shadcn/ui setup / customization | `tools-shadcn` | preset init/apply |
+| Coding conventions / overengineering | `rules-dev` | YAGNI/KISS/DRY **canonical source** |
+| "Which tech should we use?" | `manage-decisions` | 6 decision-type templates |
+| Full check before PR | `verify-implementation` | Runs verify-* in order |
+| Docs only | `verify-docs` | Backlog, gates, metadata |
+| UI vs docs | `verify-ui` | HTML Preview, flows, states |
+| Code quality only | `verify-code` | Pre-PR review |
+| Security | `verify-security` | OWASP Top 10 |
+| Performance / Lighthouse | `verify-performance` | Core Web Vitals |
+| Drizzle schema | `verify-drizzle-schema` | After schema changes |
+| solmate-skills package changes | `verify-skills` | Pre-publish metadata |
+| Pitch deck | `docs-pitch` | Layer 1 docs first |
+| Business plan | `docs-business` | Grants, investment, partnerships |
+| Branch / commit / PR (member) | `role-team-member` | |
+| Deploy / DB / PR review (lead) | `role-team-lead` | |
+| AI–human collaboration | `manage-collaboration` | |
+| Skill package maintenance | `manage-skills` | Detect missing verify skills |
+| Obsidian sync | `tools-obsidian` | |
+| Premium design reference | `ext-awesome-design` | DESIGN.md templates |
+| Korea-specific services | `ext-k-skill` | Law, delivery, transit, etc. |
+
+---
+
+## 3. Core Orchestrators
+
+```text
+                    ┌─────────────────────┐
+                    │   rules-product     │
+                    │ (entry · phase diag)│
+                    └──────────┬──────────┘
+                               │ delegates
+           ┌───────────────────┼───────────────────┐
+           ▼                   ▼                   ▼
+    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+    │  docs-plan  │    │rules-workflow│   │ verify-impl │
+    │  docs-dev   │    │ (18 steps)   │   │ (master QA) │
+    │ rules-react │    └──────┬──────┘    └──────┬──────┘
+    └─────────────┘           │                   │
+                              │                   ▼
+                              │            verify-docs … verify-skills
+                              ▼
+                         commit / PR
+```
+
+| Skill | Role | When to use alone |
+|:---|:---|:---|
+| `rules-product` | Diagnose phase, check gates, delegate | **Default first step** |
+| `rules-workflow` | Plan → implement → cleanup → PR (18 steps) | Feature work, commit/PR prep |
+| `verify-implementation` | Run verify-* by changed files, unified report | Pre-PR / pre-release |
+
+### Individual verify-* vs master
+
+| Situation | Use |
+|:---|:---|
+| Full pre-PR / pre-release | `verify-implementation` |
+| Docs only changed | `verify-docs` |
+| TSX screens only | `verify-ui` |
+| API / auth / env changed | `verify-security` (+ `verify-code` if needed) |
+| Schema only | `verify-drizzle-schema` |
+| solmate-skills repo itself | `verify-skills` |
+
+---
+
+## 4. Full Pipeline (with Gates)
+
+```text
+Phase 1  Planning docs       → docs-plan (01_Concept_Design)
+Phase 2  UI design docs      → docs-plan (02_UI_Screens)
+         HTML UI Preview Gate → previews/ HTML + user feedback
+         UI-First Gate        → screens, flows, data, states
+         Pre-Code Technical Brief → API, state, acceptance criteria
+         Component & Library Planning Gate → shadcn, custom, reuse, libraries
+Phase 3  React implementation → rules-react (+ tools-shadcn)
+Phase 4  Dev docs              → docs-dev (03–05)
+Phase 5  Quality verification  → verify-implementation
+Phase 6  Deliverables (opt.)   → docs-pitch / docs-business
+```
+
+Implementation detail: `rules-workflow` (18 steps).  
+YAGNI/KISS/DRY canonical rules: `rules-dev`.
+
+### Flow Status Block
+
+Agents report progress in this format (field labels may appear in Korean in project docs):
+
+```text
+[Flow]
+현재: Phase 2 — UI 설계
+Gate: UI-First Gate 진행 중
+완료: Phase 1 — Concept
+다음: Pre-Code Technical Brief
+필요 확인: 화면별 오류 상태
+권장 스킬: /docs-plan
+```
+
+---
+
+## 5. Skill Catalog (26 skills)
+
+Each entry: **When** / **Prerequisites** / **Invoke** / **Outputs** / **Next**
+
+### 5.1. Governance & operations
+
+#### `rules-product`
+
+- **When:** New project, resume, "what should I do next?"
+- **Prerequisites:** None
+- **Invoke:** `/rules-product` — diagnose current progress
+- **Outputs:** Flow Status Block, next skill, gate pass/fail
+- **Next:** `docs-plan`, `docs-dev`, `rules-react`, `rules-workflow`, or `verify-implementation` by phase
+
+#### `rules-workflow`
+
+- **When:** Feature implementation, planning, commit/PR (18 steps)
+- **Prerequisites:** HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan (non-prototype)
+- **Invoke:** `/rules-workflow` — implement this backlog item
+- **Outputs:** Plan review, implementation, self-check, PR readiness
+- **Next:** `verify-implementation`
+
+#### `rules-dev`
+
+- **When:** Conventions, env setup, avoid overengineering
+- **Prerequisites:** Project `AGENTS.md` or `DEVELOPMENT_PRINCIPLES.md`
+- **Invoke:** `/rules-dev` — is this minimal implementation?
+- **Outputs:** YAGNI/KISS/DRY gate verdict, coding standards
+- **Next:** `rules-workflow` when coding
+
+#### `rules-docs`
+
+- **When:** Doc structure, metadata, gates; unsure which layer
+- **Prerequisites:** None
+- **Invoke:** `/rules-docs` — is this doc in the right layer?
+- **Outputs:** 5-layer placement, Related Documents, gate requirements
+- **Next:** `docs-plan` or `docs-dev`
+
+#### `manage-collaboration`
+
+- **When:** Branch/PR/approval flow, AI–human standards
+- **Prerequisites:** Team role agreed (`role-team-lead` / `role-team-member`)
+- **Invoke:** `/manage-collaboration` — does this PR flow match standards?
+- **Outputs:** Collaboration checklist
+- **Next:** `role-team-member` or `role-team-lead`
+
+#### `manage-decisions`
+
+- **When:** Stack, DB, API, UX, architecture decisions
+- **Prerequisites:** None (conversation-driven)
+- **Invoke:** `/manage-decisions` — guide DB design decision
+- **Outputs:** Typed questions, decision record
+- **Next:** `docs-dev` or `rules-workflow`
+
+#### `manage-skills`
+
+- **When:** After adding/editing skills in solmate-skills repo
+- **Prerequisites:** Skill file changes in session
+- **Invoke:** `/manage-skills` — any missing verify skills?
+- **Outputs:** Gap list, update suggestions
+- **Next:** `verify-skills`
+
+#### `role-team-lead`
+
+- **When:** Lead — onboarding, branch protection, PR review, DB, deploy
+- **Prerequisites:** Lead role agreed
+- **Invoke:** `/role-team-lead` — pre-deploy checklist
+- **Outputs:** Lead responsibility checklist
+- **Next:** `verify-implementation`, `manage-collaboration`
+
+#### `role-team-member`
+
+- **When:** Member — branch, Conventional Commits (Korean), PR
+- **Prerequisites:** Member role agreed
+- **Invoke:** `/role-team-member` — review commit message
+- **Outputs:** Branch/commit/PR guide
+- **Next:** `rules-workflow`, `verify-code`
+
+### 5.2. Documentation
+
+#### `docs-plan`
+
+- **When:** Vision, Lean Canvas, specs, UI design, HTML previews
+- **Prerequisites:** Ask before Write
+- **Invoke:** `/docs-plan` — draft Layer 1 planning docs
+- **Outputs:** `docs/01_*`, `docs/02_*`, `previews/*.html`
+- **Next:** `verify-docs`, then `docs-dev` or `rules-react`
+
+#### `docs-dev`
+
+- **When:** DB schema, API, backlog, roadmap, QA, component/library plans
+- **Prerequisites:** Related Concept/UI docs; backlog needs Related Docs
+- **Invoke:** `/docs-dev` — write API spec and backlog
+- **Outputs:** `docs/03_*`, `docs/04_*`, `docs/05_*`
+- **Next:** `rules-workflow`, `verify-docs`
+
+#### `docs-pitch`
+
+- **When:** Investor, hackathon, demo day deck
+- **Prerequisites:** Layer 1 (`VISION_CORE`, `LEAN_CANVAS`, `PRODUCT_SPECS`)
+- **Invoke:** `/docs-pitch` — Reveal.js HTML deck
+- **Outputs:** Markdown or `pitch/index.html`
+- **Next:** `verify-docs` (optional)
+
+#### `docs-business`
+
+- **When:** Grants, investment, partnership business plan
+- **Prerequisites:** Layer 1 planning docs
+- **Invoke:** `/docs-business` — draft business plan
+- **Outputs:** Structured business plan Markdown
+- **Next:** Standalone deliverable
+
+### 5.3. Development & UI
+
+#### `rules-react`
+
+- **When:** React pages, components, refactor
+- **Prerequisites:** UI docs, HTML Preview confirmed, Component & Library Plan
+- **Invoke:** `/rules-react` — implement this screen
+- **Outputs:** React code under `src/`
+- **Next:** `verify-ui`, `verify-code`
+
+#### `tools-shadcn`
+
+- **When:** shadcn/ui init, add components, theme/preset
+- **Prerequisites:** Component & Library Plan preset action
+- **Invoke:** `/tools-shadcn` — add button, form to project
+- **Outputs:** shadcn components, preset commands
+- **Next:** `rules-react`
+
+#### `tools-obsidian`
+
+- **When:** Sync project docs with Obsidian vault
+- **Prerequisites:** Vault path
+- **Invoke:** `/tools-obsidian` — check sync status
+- **Outputs:** Link status, metadata compatibility
+- **Next:** None
+
+### 5.4. Verification (verify-*)
+
+#### `verify-implementation`
+
+- **When:** Pre-PR unified check (**default**)
+- **Prerequisites:** Changes to verify
+- **Invoke:** `/verify-implementation` — full verification
+- **Outputs:** Pass/Fail report incl. YAGNI/KISS/DRY Gate
+- **Next:** Fix and re-run, or scoped verify-* skills
+
+#### `verify-docs`
+
+- **When:** After doc edits; backlog/gate alignment
+- **Prerequisites:** `docs/` changes
+- **Invoke:** `/verify-docs` — validate backlog Related Docs
+- **Outputs:** Layer/metadata/gate violations
+- **Next:** `docs-plan` / `docs-dev`
+
+#### `verify-ui`
+
+- **When:** After React/TSX UI work
+- **Prerequisites:** `docs/02_UI_Screens/`, HTML Preview
+- **Invoke:** `/verify-ui` — does UI match docs?
+- **Outputs:** Screen/flow/state mismatches
+- **Next:** `rules-react`
+
+#### `verify-code`
+
+- **When:** Pre-PR code quality, overengineering
+- **Prerequisites:** Code changes
+- **Invoke:** `/verify-code` — pre-PR review
+- **Outputs:** Issue table (YAGNI/KISS/DRY tags)
+- **Next:** Fix or `verify-implementation`
+
+#### `verify-security`
+
+- **When:** auth, API, middleware, env, DB changes
+- **Prerequisites:** Security-sensitive changes
+- **Invoke:** `/verify-security` — OWASP check
+- **Outputs:** Vulnerabilities, auth, secrets
+- **Next:** Fix and re-run
+
+#### `verify-performance`
+
+- **When:** Page, layout, images, bundle; pre-deploy
+- **Prerequisites:** Frontend performance impact
+- **Invoke:** `/verify-performance` — Lighthouse check
+- **Outputs:** LCP, CLS, bundle, image issues
+- **Next:** Fix and re-run
+
+#### `verify-drizzle-schema`
+
+- **When:** Drizzle schema/migration changes
+- **Prerequisites:** `DB_SCHEMA.md` or equivalent
+- **Invoke:** `/verify-drizzle-schema` — schema alignment
+- **Outputs:** Schema/doc mismatches
+- **Next:** `docs-dev`
+
+#### `verify-skills`
+
+- **When:** solmate-skills package edit, pre-publish
+- **Prerequisites:** `SKILL.md`, `package.json`, `README.md`, `AGENTS.md` changes
+- **Invoke:** `/verify-skills` — release readiness
+- **Outputs:** CLI, frontmatter, version sync, npm pack
+- **Next:** `npm publish`
+
+### 5.5. External extensions
+
+#### `ext-awesome-design`
+
+- **When:** Premium design tokens, DESIGN.md, brand UI styles
+- **Prerequisites:** None (reference library)
+- **Invoke:** Reference stripe DESIGN.md from ext-awesome-design
+- **Outputs:** Design reference, DESIGN.md draft
+- **Next:** `docs-plan`, `rules-react`
+
+#### `ext-k-skill`
+
+- **When:** Korea-specific data (law, delivery, KTX, fine dust, etc.)
+- **Prerequisites:** Per-feature setup in ext-k-skill package
+- **Invoke:** See ext-k-skill README and feature guides
+- **Outputs:** Feature-specific API results
+- **Next:** None (tooling)
+
+> `ext-k-skill` is separate from the core Solmate workflow. Run `k-skill-setup` and per-feature docs after install.
+
+---
+
+## 6. Documentation System
+
+### Which skill writes which docs
+
+```text
+Product vision, Lean Canvas, UI design  →  docs-plan
+DB schema, API specs, roadmap, QA       →  docs-dev
+Unsure which layer?                     →  rules-docs
+```
+
+### 5-Layer structure
+
+```text
+docs/
+├── 01_Concept_Design/   ← docs-plan
+├── 02_UI_Screens/       ← docs-plan (+ previews/)
+├── 03_Technical_Specs/  ← docs-dev
+├── 04_Logic_Progress/   ← docs-dev
+└── 05_QA_Validation/    ← docs-dev
+```
+
+---
+
+## 7. Gates (detail)
+
+### HTML UI Preview Gate
+
+- Path: `docs/02_UI_Screens/previews/`
+- Link from UI docs with relative paths
+- Show HTML to user before implementation; record feedback
+
+### UI-First Gate
+
+- Screen structure, user paths, CTAs, data flow
+- Loading, empty, error states before coding
+
+### Component & Library Planning Gate
+
+- shadcn/ui, custom, reused components
+- Libraries to add/avoid, preset action (`init --preset`, `apply --preset`, etc.)
+- Record in backlog `Component & Library Plan`
+
+### Backlog Context Lock
+
+Required fields per item in `docs/04_Logic_Progress/00_BACKLOG.md`:
+
+- `Related Concept Docs`, `Related UI Docs`, `Related HTML Preview`
+- `Related Technical Docs`, `Related QA Docs`
+- `Implementation Preconditions`, `Component & Library Plan`
+- `Acceptance Criteria`, `Document Sync Check`
+
+Use `N/A - reason` when a doc does not exist. Pause implementation if a missing doc blocks a safe decision.
+
+### YAGNI/KISS/DRY Gate
+
+- **Canonical:** `rules-dev` § Minimal Implementation Gate
+- Referenced by `rules-workflow`, `verify-code` Area 3, `verify-implementation` report
+- Prototype/spike: advisory only; do not drop security, validation, or error handling for "simplicity"
+
+### Backlog item template
+
+<a id="backlog-item-template"></a>
+
+```markdown
+### [ ] TASK-000: Implement feature name
+
+- Status: ToDo
+- Related Concept Docs:
+  - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
+- Related UI Docs:
+  - [Screen Flow](../02_UI_Screens/00_SCREEN_FLOW.md) - target screen and interaction flow
+- Related HTML Preview:
+  - [Main Flow Preview](../02_UI_Screens/previews/01_main_flow_preview.html) - browser-viewable UI for user review
+- Related Technical Docs:
+  - [API Specs](../03_Technical_Specs/02_API_SPECS.md) - endpoint and data contract
+- Related QA Docs:
+  - [QA Checklist](../05_QA_Validation/02_QA_CHECKLIST.md) - acceptance and release criteria
+- Implementation Preconditions:
+  - [ ] Read all related documents before coding
+  - [ ] Confirm screen/UI before coding
+  - [ ] Show the HTML UI preview to the user and capture feedback
+  - [ ] Confirm user path and screen-by-screen data flow
+  - [ ] Confirm loading, empty, and error states
+  - [ ] Confirm implementation scope does not conflict with documented intent
+- Component & Library Plan:
+  - shadcn/ui components: button, card, form, or `N/A - reason`
+  - Custom components: feature-specific components or `N/A - reason`
+  - Reused components: existing paths or `N/A - reason`
+  - New libraries: package names and reasons or `N/A - reason`
+  - Libraries intentionally not added: rejected options and reasons or `N/A - reason`
+  - shadcn preset action: init --preset / apply --preset / apply --only theme / N/A - reason
+- Acceptance Criteria:
+  - [ ] Feature follows the confirmed screen structure and user path
+  - [ ] Feature behavior matches linked Concept/UI/Technical docs
+  - [ ] QA criteria are testable and satisfied
+- Document Sync Check:
+  - [ ] No mismatch between implementation and linked documents
+  - [ ] Update related documents if implementation changes the agreed behavior
+```
+
+---
+
+## 8. Hooks (Claude Code suggestions)
+
+Keyword and file-pattern **suggestions** (not forced runs):
+
+```bash
+npx solmate-skills@latest install hooks
+bash .agent/skills/hooks/install.sh
+```
+
+| Script | Event | Examples |
+|:---|:---|:---|
+| `solmate-suggest.sh` | UserPromptSubmit | decisions, security, performance, PR, docs |
+| `solmate-watch.sh` | PreToolUse (Write/Edit) | `schema.ts`, `page.tsx`, `SKILL.md`, `AGENTS.md` |
+
+Re-run `install hooks` to pick up 2.0.10 false-positive fixes on existing projects.
+
+---
+
+## 9. Recommended Prompts
+
+**Project diagnosis (new or resume)**
+
+```text
+Use /rules-product to diagnose this project's current progress and recommend next steps with a Flow Status Block.
+```
+
+**Feature implementation**
+
+```text
+Use /rules-workflow for this feature. Start with a Flow Status Block and follow the UI-First flow.
+```
+
+**Pre-PR verification**
+
+```text
+Run /verify-implementation on current changes. Include a Flow Status Block in the report.
+```
+
+---
+
+## 10. Related Documents
+
+| Document | Audience | Content |
+|:---|:---|:---|
+| [README.md](./README.md) | First-time installers | Install, 5-minute start, changelog |
+| [USAGE.md](./USAGE.md) (this file) | Daily users | Cheat sheet, catalog, gates (EN + KO) |
+| `AGENTS.md` | Installed project AI | Global rules, skill table, suggestions |
+| `<skill>/SKILL.md` | AI agents | Per-skill execution spec |
+
+---
+
+# solmate-skills Usage Guide (Korean)
+
+<a id="solmate-skills-usage-guide-korean"></a>
+
+**언어:** [English (default)](#solmate-skills-usage-guide) · 한국어 (아래)
+
+사람이 읽기 위한 스킬 사용법 가이드입니다.  
+에이전트 실행 규칙의 정본은 각 `SKILL.md`와 프로젝트에 설치된 `AGENTS.md`입니다.
+
+---
+
+## 1. 스킬 호출 방법
+
+### Cursor / Claude Code (권장)
+
+채팅에서 슬래시 명령 또는 자연어로 호출합니다.
+
+```text
+/rules-product
+/rules-workflow를 사용해서 이 기능 구현을 진행해줘
+/verify-implementation으로 현재 변경사항을 검증해줘
+```
+
+### 설치 위치
+
+```bash
+npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
+npx solmate-skills@latest install hooks    # Claude Code 자동 제안 (별도) + ./USAGE.md
+```
+
+모든 `install` 명령(단일 스킬, `all`, `hooks`)은 `USAGE.md`를 **프로젝트 루트**에 복사합니다.
+
+### 로컬 개발 (symlink)
+
+`solmate-skills` 저장소를 직접 수정하며 테스트할 때:
+
+```bash
+# 대상 프로젝트 루트에서 실행
+bash /path/to/solmate-skills/init-skills.sh
+```
+
+`.agent/skills/`가 저장소로 symlink되고, `AGENTS.md`와 `USAGE.md`가 루트에 링크됩니다.
+
+---
+
+## 2. 상황별 스킬 선택 (치트시트)
+
+| 사용자가 말하는 것 | 추천 스킬 | 비고 |
+|:---|:---|:---|
+| "뭐부터 해야 해?" / 신규 프로젝트 | `rules-product` | **가장 권장하는 시작점** |
+| "지금 어디까지 왔지?" / 작업 재개 | `rules-product` | Phase 진단 후 다음 스킬 위임 |
+| 비전·린캔버스·화면 설계 문서 | `docs-plan` | Layer 1-2 |
+| DB·API·백로그·QA 문서 | `docs-dev` | Layer 3-5 |
+| 문서 구조가 맞는지 모르겠음 | `rules-docs` | 5레이어·게이트 규칙 정본 |
+| 기능 하나 구현 / 커밋·PR 전 | `rules-workflow` | 18단계 구현 워크플로 |
+| React 화면·컴포넌트 구현 | `rules-react` | Component & Library Plan 선행 |
+| shadcn/ui 설치·커스터마이징 | `tools-shadcn` | preset init/apply 포함 |
+| 코딩 컨벤션·과잉 구현 방지 | `rules-dev` | YAGNI/KISS/DRY **정본** |
+| "이거 어떤 기술 쓸까?" / 설계 결정 | `manage-decisions` | 6개 결정 유형 질문 템플릿 |
+| PR 전 **전체** 점검 | `verify-implementation` | verify-* 통합 실행 |
+| 문서만 점검 | `verify-docs` | 백로그·게이트·메타데이터 |
+| UI가 문서와 맞는지 | `verify-ui` | HTML Preview·동선·상태 |
+| 코드 품질·과잉 구현만 | `verify-code` | PR 전 코드 리뷰 |
+| 보안 점검 | `verify-security` | OWASP Top 10 |
+| 성능·Lighthouse | `verify-performance` | Core Web Vitals |
+| Drizzle 스키마 | `verify-drizzle-schema` | 스키마 변경 시 |
+| solmate-skills 패키지 수정 후 | `verify-skills` | 배포 전 메타데이터 검증 |
+| 피치덱 | `docs-pitch` | Layer 1 문서 선행 |
+| 사업계획서 | `docs-business` | 정부 지원·투자 심사용 |
+| 브랜치·커밋·PR 규칙 (팀원) | `role-team-member` | |
+| 배포·DB·PR 리뷰 (팀장) | `role-team-lead` | |
+| AI-인간 협업 표준 | `manage-collaboration` | |
+| 스킬 패키지 유지보수 | `manage-skills` | verify 스킬 누락 탐지 |
+| Obsidian 동기화 | `tools-obsidian` | |
+| 프리미엄 디자인 참고 | `ext-awesome-design` | DESIGN.md 템플릿 |
+| 한국 특화 서비스 조회 | `ext-k-skill` | 법률·배송·교통 등 |
+
+---
+
+## 3. 핵심 오케스트레이터 관계
+
+| 스킬 | 역할 | 단독 사용 시점 |
+|:---|:---|:---|
+| `rules-product` | 프로젝트 Phase 진단, Gate 확인, 하위 스킬 위임 | **항상 첫 진입점**으로 권장 |
+| `rules-workflow` | 승인된 문서 기준으로 계획→구현→정리→PR (18단계) | 기능 구현·커밋·PR 직전 |
+| `verify-implementation` | 변경 파일에 맞춰 verify-* 순차 실행·통합 보고 | PR·배포 전 최종 점검 |
+
+### verify-* 개별 vs 통합
+
+| 상황 | 사용 |
+|:---|:---|
+| PR·배포 전 전체 점검 | `verify-implementation` |
+| 문서만 수정함 | `verify-docs` |
+| TSX 화면만 수정함 | `verify-ui` |
+| API·auth·env 수정함 | `verify-security` (+ 필요 시 `verify-code`) |
+| 스키마만 수정함 | `verify-drizzle-schema` |
+| solmate-skills 저장소 자체 수정 | `verify-skills` |
+
+---
+
+## 4. 전체 파이프라인 (Gate 포함)
+
+```text
+Phase 1  기획문서          → docs-plan (01_Concept_Design)
+Phase 2  UI 설계 문서     → docs-plan (02_UI_Screens)
+         HTML UI Preview Gate   → previews/ HTML + 사용자 피드백
+         UI-First Gate          → 화면·동선·데이터 흐름·상태 확인
+         Pre-Code Technical Brief → API·상태·acceptance criteria 합의
+         Component & Library Planning Gate → shadcn·커스텀·재사용·라이브러리 계획
+Phase 3  React 구현       → rules-react (+ tools-shadcn)
+Phase 4  개발문서         → docs-dev (03~05)
+Phase 5  품질 검증        → verify-implementation
+Phase 6  전달물 (선택)    → docs-pitch / docs-business
+```
+
+구현 상세: `rules-workflow` (18단계). YAGNI/KISS/DRY **정본**: `rules-dev`.
+
+### Flow Status Block
+
+```text
+[Flow]
+현재: Phase 2 — UI 설계
+Gate: UI-First Gate 진행 중
+완료: Phase 1 — Concept
+다음: Pre-Code Technical Brief
+필요 확인: 화면별 오류 상태
+권장 스킬: /docs-plan
+```
+
+---
+
+## 5. 스킬 카탈로그 (26개)
+
+각 항목: **언제** / **선행 조건** / **호출 예** / **산출물** / **다음 스킬**  
+(스킬 이름·구조는 영문 섹션 [§5](#5-skill-catalog-26-skills)과 동일합니다.)
+
+### 5.1. 운영 및 거버넌스
+
+| 스킬 | 언제 | 다음 스킬 |
+|:---|:---|:---|
+| `rules-product` | 신규·재개·"뭘 해야 하지?" | Phase별 위임 |
+| `rules-workflow` | 기능 구현·18단계·PR 전 | `verify-implementation` |
+| `rules-dev` | 컨벤션·과잉 구현 방지 | `rules-workflow` |
+| `rules-docs` | 문서 레이어·게이트 확인 | `docs-plan` / `docs-dev` |
+| `manage-collaboration` | 브랜치·PR·협업 표준 | role 스킬 |
+| `manage-decisions` | 기술·DB·API·UX 결정 | `docs-dev` / `rules-workflow` |
+| `manage-skills` | 스킬 패키지 수정 후 | `verify-skills` |
+| `role-team-lead` | 팀장 책임·배포 | `verify-implementation` |
+| `role-team-member` | 팀원·커밋·PR | `rules-workflow` |
+
+### 5.2. 문서 작성
+
+| 스킬 | 언제 | 산출물 |
+|:---|:---|:---|
+| `docs-plan` | Layer 1-2, HTML Preview | `01_*`, `02_*`, `previews/` |
+| `docs-dev` | Layer 3-5, 백로그 | `03_*` ~ `05_*` |
+| `docs-pitch` | 피치덱 | MD 또는 Reveal HTML |
+| `docs-business` | 사업계획서 | 사업계획서 MD |
+
+### 5.3. 개발 및 UI
+
+| 스킬 | 언제 | 선행 조건 |
+|:---|:---|:---|
+| `rules-react` | React 구현 | UI 문서·Preview·Component Plan |
+| `tools-shadcn` | shadcn/ui | preset action |
+| `tools-obsidian` | Obsidian 동기화 | 볼트 경로 |
+
+### 5.4. 품질 검증
+
+| 스킬 | 언제 |
+|:---|:---|
+| `verify-implementation` | PR 전 통합 (**기본**) |
+| `verify-docs` | 문서·백로그·게이트 |
+| `verify-ui` | UI vs 문서 |
+| `verify-code` | 코드·과잉 구현 |
+| `verify-security` | OWASP |
+| `verify-performance` | Lighthouse·CWV |
+| `verify-drizzle-schema` | Drizzle 스키마 |
+| `verify-skills` | 패키지 배포 전 |
+
+### 5.5. 외부 확장
+
+| 스킬 | 언제 |
+|:---|:---|
+| `ext-awesome-design` | DESIGN.md·디자인 참고 |
+| `ext-k-skill` | 한국 특화 API (코어 워크플로와 별도) |
+
+---
+
+## 6. 문서 시스템 요약
+
+```text
+기획·UI 문서  → docs-plan (01, 02)
+기술·진행·QA  → docs-dev (03, 04, 05)
+레이어 불명   → rules-docs
+```
+
+---
+
+## 7. Gate 상세
+
+- **HTML UI Preview Gate:** `docs/02_UI_Screens/previews/`, UI 문서 링크, 사용자 피드백
+- **UI-First Gate:** 화면·동선·CTA·데이터 흐름·로딩/빈/오류 상태
+- **Component & Library Planning Gate:** shadcn·커스텀·재사용·라이브러리·preset
+- **Backlog Context Lock:** Related Docs, Preconditions, Component Plan, Acceptance, Sync Check
+- **YAGNI/KISS/DRY Gate:** `rules-dev` 정본; 프로토타입은 기록성 체크
+
+백로그 템플릿: [영문 §7 Backlog item template](#backlog-item-template) (필드명은 영문 유지)
+
+---
+
+## 8. Hooks (Claude Code 자동 제안)
+
+```bash
+npx solmate-skills@latest install hooks
+bash .agent/skills/hooks/install.sh
+```
+
+키워드·파일 패턴에 맞춰 스킬을 **제안**합니다 (강제 실행 아님). 2.0.10 false-positive 수정은 hooks 재설치로 반영.
+
+---
+
+## 9. 권장 프롬프트 모음
+
+**프로젝트 진단**
+
+```text
+/rules-product를 사용해서 이 프로젝트의 현재 진행 상태를 진단하고, 다음 작업을 Flow Status Block 기준으로 안내해줘.
+```
+
+**기능 구현**
+
+```text
+/rules-workflow를 사용해서 현재 기능 작업을 진행해줘. 먼저 Flow Status Block으로 현재 위치를 알려주고, UI-First 흐름에 맞춰 진행해줘.
+```
+
+**PR 전 검증**
+
+```text
+/verify-implementation으로 현재 변경사항을 전체 검증해줘. Flow Status Block을 포함해서 보고해줘.
+```
+
+---
+
+## 10. 관련 문서
+
+| 문서 | 대상 | 내용 |
+|:---|:---|:---|
+| [README.md](./README.md) | 처음 설치 | 설치, Quick Start |
+| [USAGE.md](./USAGE.md) | 일상 사용자 | 영문(기본) + 한국어 |
+| `AGENTS.md` | AI | 전역 규칙 |
+| `<skill>/SKILL.md` | AI | 스킬별 실행 정본 |

package/bin/cli.js

@@ -7,6 +7,9 @@ const { execSync } = require('child_process');
 const IGNORED_FOLDERS = ['bin', 'node_modules', '.git', '.github', '.gemini', '.agent'];
 const IGNORED_FILES = ['package.json', 'package-lock.json', 'AGENTS.md', 'SKILL.md', 'init-skills.sh', 'README.md', '.DS_Store', 'old_AGENTS.md'];
 
+// Root-level docs copied to the target project on every install.
+const PACKAGE_DOC_FILES = ['USAGE.md'];
+
 // Skills that require a post-install script to be executed after copying.
 // Key: skill name, Value: path relative to the skill folder.
 const POST_INSTALL_SCRIPTS = {
@@ -28,6 +31,21 @@ function getAvailableSkills() {
         .map(dirent => dirent.name);
 }
 
+function installPackageDocs() {
+    for (const fileName of PACKAGE_DOC_FILES) {
+        const sourcePath = path.join(packageRoot, fileName);
+        const destPath = path.join(targetProjectRoot, fileName);
+
+        if (!fs.existsSync(sourcePath)) {
+            console.warn(`Warning: ${fileName} not found in package; skipping.`);
+            continue;
+        }
+
+        fs.copyFileSync(sourcePath, destPath);
+        console.log(`Installed ${fileName} to project root`);
+    }
+}
+
 function copyFolderSync(from, to) {
     if (!fs.existsSync(to)) {
         fs.mkdirSync(to, { recursive: true });
@@ -64,6 +82,7 @@ function installHooks() {
     console.log('Installing hooks utility...');
     copyFolderSync(sourcePath, destPath);
     console.log('Successfully installed hooks utility to .agent/skills/hooks');
+    installPackageDocs();
 
     const scriptPath = path.join(destPath, 'install.sh');
     if (fs.existsSync(scriptPath)) {
@@ -76,12 +95,14 @@ function installHooks() {
     }
 }
 
-function installSkill(skillName) {
+function installSkill(skillName, options = {}) {
+    const { deferPackageDocs = false } = options;
     const skills = getAvailableSkills();
 
     if (skillName === 'install-all') {
         console.log('Installing all skills...');
-        skills.forEach(s => installSkill(s));
+        skills.forEach(s => installSkill(s, { deferPackageDocs: true }));
+        installPackageDocs();
         return;
     }
 
@@ -114,6 +135,10 @@ function installSkill(skillName) {
             }
         }
     }
+
+    if (!deferPackageDocs) {
+        installPackageDocs();
+    }
 }
 
 const args = process.argv.slice(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solmate-skills",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "description": "AI workflow skills for UI-first planning, YAGNI/KISS/DRY gates, docs, QA, and Solmate projects",
   "main": "bin/cli.js",
   "bin": {

package/rules-product/SKILL.md

@@ -5,6 +5,13 @@ description: Orchestrates the full product development pipeline from planning to
 
 # Product Workflow Orchestrator
 
+> **Human Quick Reference**
+> - **When**: New project, resume work, or "what should I do next?"
+> - **Invoke**: `/rules-product` or ask for a Flow Status Block diagnosis
+> - **Prerequisites**: None — starts by scanning the repo
+> - **Next**: `docs-plan`, `docs-dev`, `rules-react`, `rules-workflow`, or `verify-implementation` by phase
+> - **Guide**: project root `USAGE.md` (English default, Korean below; copied on install)
+
 You are a **workflow lead** who guides the user through the full product development pipeline. You do not do the work yourself — you diagnose the current phase, verify gate conditions, and direct the user to the right sub-skill at each step.
 
 ## Pipeline Overview

package/rules-workflow/SKILL.md

@@ -5,6 +5,13 @@ description: Guides the full implementation lifecycle from planning through PR.
 
 # Implementation & Execution Workflow (18 Steps)
 
+> **Human Quick Reference**
+> - **When**: Feature implementation, commit/PR prep, 18-step workflow
+> - **Invoke**: `/rules-workflow` after gates and backlog links are ready
+> - **Prerequisites**: HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan
+> - **Next**: `verify-implementation` before PR
+> - **Guide**: project root `USAGE.md` (English default, Korean below; copied on install)
+
 Follow this workflow for feature implementation and significant code changes. Complete each phase before advancing; use the checklists to avoid skipping steps.
 
 ---

package/verify-implementation/SKILL.md

@@ -7,6 +7,13 @@ argument-hint: "[선택사항: 특정 verify 스킬 이름]"
 
 # 구현 검증 (Master)
 
+> **Human Quick Reference**
+> - **When**: Pre-PR or pre-release full check (default verify entry point)
+> - **Invoke**: `/verify-implementation`
+> - **Prerequisites**: Changes to verify; runs verify-* skills based on `git diff`
+> - **Next**: Fix failures, then re-run; use individual verify-* skills for scoped checks
+> - **Guide**: project root `USAGE.md` (English default, Korean below; copied on install)
+
 ## 목적
 
 프로젝트에 존재하는 모든 `verify-*` 스킬을 동적으로 탐색하여 순차적으로 실행하고 통합 검증을 수행합니다. 기본 순서를 따르되, 변경 파일과 프로젝트 특성에 따라 해당 없는 스킬은 `N/A - 사유`로 기록합니다. 코드 변경이 있으면 YAGNI/KISS/DRY Gate 통과 여부를 통합 보고서에 반드시 포함합니다.

package/verify-skills/SKILL.md

@@ -109,20 +109,26 @@ print("metadata ok" if not bad else "\n".join(bad))'
 
 ---
 
-## Check 4: README, AGENTS, package 버전 동기화
+## Check 4: README, AGENTS, USAGE, package 버전 동기화
 
 - `package.json` 버전과 README의 최신 버전 문구가 일치하는지 확인한다.
+- README가 `USAGE.md`를 링크하는지 확인한다.
+- `bin/cli.js`가 `USAGE.md`를 프로젝트 루트로 복사하는지 확인한다.
 - README와 AGENTS의 verify 목록이 실제 `verify-*` 디렉터리와 맞는지 확인한다.
 
 ```bash
 node -p "require('./package.json').version"
 grep -n "What's New in" README.md
+grep -n "USAGE.md" README.md AGENTS.md
+grep -n "PACKAGE_DOC_FILES\\|installPackageDocs" bin/cli.js
 find . -maxdepth 1 -type d -name 'verify-*' -exec basename {} \; | sort
 grep -n "verify-" README.md AGENTS.md
 ```
 
 - 체크:
   - [ ] README 최신 버전 문구가 `package.json`과 일치하는가?
+  - [ ] README·AGENTS가 `USAGE.md`를 참조하는가?
+  - [ ] CLI `install`이 `USAGE.md`를 프로젝트 루트로 복사하는가?
   - [ ] README Available Skills에 새 스킬이 반영되었는가?
   - [ ] AGENTS.md 품질 검증 목록에 새 verify 스킬이 반영되었는가?