pi-skill-search 0.1.0

package/skills/vetc-deep-interview/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: vetc-deep-interview
+description: Kích hoạt khi requirement còn mơ hồ, chưa rõ scope/actor/edge cases. Socratic clarification với ambiguity scoring. Output ra specs/interviews/{slug}.md rồi handoff vetc-ralplan hoặc vetc-analyze-ba.
+---
+
+# VETC Deep Interview — Socratic Clarification
+
+Làm rõ yêu cầu trước khi plan hoặc implement. Tránh rework từ misaligned implementation.
+
+
+
+## When to Activate
+
+- User mô tả tính năng ngắn gọn, chưa rõ scope ("thêm chức năng X", "fix vấn đề Y")
+- Requirement còn ambiguous — thiếu actor, business rules, edge cases, acceptance criteria
+- Cần validate hiểu biết với BA/PO trước khi commit vào implementation
+- Trước khi dùng `vetc-ralplan` hoặc `vetc-analyze-ba`
+- User nói: "hỏi tôi về requirement", "làm rõ trước", "deep interview"
+
+## Red Flags — Stop and Re-Evaluate
+
+These thoughts mean you are about to bypass this skill incorrectly:
+
+| Thought | Reality |
+|---------|---------|
+| "This feature is simple, no need for clarification" | "Simple" features have the worst rework rates. |
+| "I can guess what they want" | Your guess is wrong. Ask. |
+| "The user seems impatient, skip to coding" | Rework takes 10x longer than clarification. |
+| "I've seen this pattern before in VETC" | Similar ≠ same. E-Wallet vs ACS vs eKYC differ critically. |
+| "The spec will become clear during implementation" | It won't. It will become a mess. |
+| "One question is enough" | One question gives one answer. You need the full picture. |
+
+## Do NOT activate when
+
+- Đã có `raw-ba-requirements.md` rõ ràng → dùng `vetc-analyze-ba`
+- Đã có Structured Spec → dùng `vetc-ralplan` hoặc `vetc-planner`
+- User cung cấp file path / function name cụ thể → implement ngay
+
+## Recommended Pipeline
+
+```
+vetc-deep-interview → vetc-ralplan → vetc-analyze-ba (hoặc vetc-java-patterns)
+```
+
+## Ambiguity Dimensions (VETC-adapted)
+
+| Dimension | Weight (New) | Weight (Change) | Focus |
+|-----------|-------------|-----------------|-------|
+| Intent | 0.25 | 0.25 | Tại sao cần tính năng này? Business goal? |
+| Outcome | 0.20 | 0.20 | End state mong đợi là gì? |
+| Scope | 0.20 | 0.20 | Phạm vi: module nào, role nào, flow nào? |
+| Business Rules | 0.15 | 0.15 | Ràng buộc nghiệp vụ (amount limits, timing, roles) |
+| Success Criteria | 0.10 | 0.10 | Làm sao biết là xong? Test case nào? |
+| Integrations | 0.10 | 0.10 | ACS, Bank GW, eKYC, RabbitMQ ảnh hưởng gì? |
+
+**Ambiguity score** = `1 - weighted_sum_of_clarity_scores`
+
+Threshold: `<= 0.20` (Standard) | `<= 0.30` (Quick) | `<= 0.15` (Deep)
+
+## Ambiguity Taxonomy (Spec-Kit adapted)
+
+10+ category taxonomy để scan ambiguity có hệ thống:
+
+| # | Category | Probing Questions | VETC Examples |
+|---|----------|-------------------|---------------|
+| 1 | Functional Scope | Tính năng làm gì? Không làm gì? | Nạp tiền qua QR: chỉ top-up hay cả thanh toán? |
+| 2 | Domain & Data Model | Entity nào? Relationship? | Transaction có link Wallet không? Journal entry loại gì? |
+| 3 | Interaction & UX | User thấy gì? Click gì? | Confirm screen trước hay sau scan QR? |
+| 4 | Non-Functional Quality | Performance? Availability? | 100 concurrent users? 99.9% uptime? |
+| 5 | Integration | External systems? Protocols? | Bank GW đồng bộ hay async? Retry policy? |
+| 6 | Edge Cases & Error Handling | Lỗi thì sao? Recovery? | QR expired → refresh hay tạo mới? |
+| 7 | Constraints & Limits | Amount? Frequency? Timing? | Min/max top-up? Daily limit? |
+| 8 | Security & Auth | Role? Permission? Data sensitivity? | Agent top-up hộ customer được không? |
+| 9 | Terminology & Concepts | Term đồng nghĩa? Ambiguous? | "Balance" = available hay including frozen? |
+
+## Workflow
+
+### Phase 0 — Preflight
+
+1. Parse feature slug từ input (kebab-case)
+2. Kiểm tra `specs/interviews/{slug}-*.md` — nếu có, load context và resume
+3. Tạo context snapshot:
+   ```
+   specs/interviews/{slug}-{YYYYMMDD}.md
+   ├── Task statement
+   ├── Probable intent hypothesis
+   ├── Known facts
+   ├── Open questions
+   └── VETC integrations likely involved
+   ```
+4. Thông báo: ambiguity hiện tại, mode (Quick/Standard/Deep), max rounds
+
+### Phase 1 — Socratic Interview Loop
+
+**Quy tắc:**
+- Hỏi **1 câu** mỗi round — không batch
+- Ưu tiên Intent → Scope → Business Rules → Success Criteria → Integrations
+- Sau mỗi câu trả lời: pressure test (counterexample, hidden assumption, tradeoff)
+- Research codebase trước khi hỏi user về internals
+
+**Round format:**
+
+

package/skills/vetc-docgen/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: vetc-docgen
+description: PROACTIVELY activate khi implement xong API mới và trước khi merge — sinh Swagger/OpenAPI annotations, update CHANGELOG, generate technical note từ spec + code diff. Đảm bảo docs luôn đồng bộ với implementation.
+---
+
+# VETC DocGen — Keep Docs in Sync with Code
+
+Sau khi implement xong, tự động sinh Swagger annotations, CHANGELOG entry, technical notes từ spec + code diff. Không để docs drift khỏi implementation.
+
+## When to Activate
+
+- API mới implement xong, chuẩn bị merge — cần Swagger docs
+- Breaking change / API contract thay đổi — CHANGELOG entry
+- Release chuẩn bị cut — generate release notes từ commits
+- Onboarding doc cho service mới — technical overview
+- Post-implementation documentation catch-up
+
+## Do NOT Activate When
+
+- Code chưa implement xong — docs sẽ lệch
+- Pure refactor không thay signature — no new API doc needed
+- Internal helper class — không cần javadoc đầy đủ
+- Spec chưa approved — doc content sẽ thay đổi
+
+## Scope of DocGen
+
+### 1. Swagger / OpenAPI Annotations
+
+For Spring Boot Controllers:
+
+```java
+@RestController
+@RequestMapping("/wallet/v1")
+@Tag(name = "Wallet", description = "Wallet transfer and balance operations")
+public class WalletController {
+
+    @Operation(
+        summary = "Transfer money between wallets",
+        description = "Debit source wallet and credit target wallet atomically. " +
+                      "Requires Smart OTP for amounts > 500,000 VND.",
+        responses = {
+
+## [1.2.0] - 2026-04-17
+
+### Added
+- `POST /wallet/v1/transfer` — atomic transfer between wallets with idempotency (VETC-123)
+- Smart OTP integration for transfers > 500K VND (VETC-128)
+
+### Changed
+- `POST /wallet/v1/balance` response now includes `availableBalance` field (VETC-135)
+  - **Breaking for consumers** relying on exact field list — add `availableBalance` handler
+
+### Fixed
+- Race condition in `ReconcileService.matchTransactions()` when duplicate keys (VETC-142)
+
+### Security
+- Upgraded Spring Boot 3.2.0 → 3.2.4 (CVE-2024-XXXX patched)
+
+### Deprecated
+- `POST /wallet/v1/transfer-simple` — will be removed in 2.0.0. Use `/transfer` with `skipOtp=false`.
+```
+
+### 3. Technical Note (from Spec + Diff)
+
+When implementing non-trivial feature, generate:
+
+```markdown
+# Technical Note: Smart OTP for High-Value Transfers
+
+**Feature**: VETC-128
+**Author**: {dev}
+**Date**: 2026-04-17
+**Status**: Implemented
+
+## Context
+Transfer > 500K VND requires 2FA. Previous impl used SMS OTP (cost + delay).
+New: Smart OTP via app push (free, <2s delivery).
+
+## Implementation Summary
+- New `SmartOtpService` generates TOTP seed on device registration
+- Transfer endpoint validates OTP via Redis-stored challenge
+- Fallback to SMS if Smart OTP unavailable (device offline > 5min)
+
+## Key Files
+- `wallet-service/src/main/java/vn/vetc/wallet/service/SmartOtpService.java` (new)
+- `wallet-service/src/main/java/vn/vetc/wallet/controller/WalletController.java` (modified)
+- `infra-service/src/main/java/vn/vetc/infra/OtpConfig.java` (modified)
+
+## API Changes
+| Endpoint | Change | Breaking? |
+|----------|--------|-----------|
+| POST /wallet/v1/transfer | Added `otpType: SMART\|SMS` | No (default: SMART) |
+| POST /otp/v1/verify | Added `challengeId` field | No |
+
+## Database Changes
+- New table: `WALLET_OTP_CHALLENGE` (Redis-backed, TTL 300s)
+- No schema migration needed
+
+## Rollout Plan
+1. Feature flag `vetc.feature.smart-otp.enabled=false` in prod
+2. Enable for 5% users (A/B test)
+3. Monitor error rate, OTP delivery success
+4. Full rollout after 48h stable
+
+## Rollback
+- Disable feature flag → falls back to SMS OTP
+- No schema rollback needed
+```

package/skills/vetc-frontend-patterns/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vetc-frontend-patterns
+description: PROACTIVELY activate khi implement React/TypeScript feature, thêm page/component/API module, hoặc fix TS error. Auto-detect version từ package.json. Bao gồm Axios interceptor, Redux, Ant Design/MUI patterns.
+---
+
+# VETC Frontend Patterns
+
+React/TypeScript implementation patterns cho VETC frontend apps.
+
+## When to Activate
+
+- Implement React/TypeScript feature cho agency portal hoặc ops-ui
+- Thêm page, component, API module, Redux slice
+- Fix TypeScript error hoặc React warning
+
+## Do NOT Activate When
+
+- Đang làm backend/Java/Spring Boot work (dùng `vetc-java-patterns`)
+- Chỉ làm database work — schema, migration, query (dùng `vetc-oracle-patterns`)
+- Chỉ viết API contract/design (dùng `vetc-api-design`)
+
+## Gotchas — Frontend Traps
+
+1. **Raw `axios` thay vì `axiosInstance`** → Bypass interceptor (auth token, refresh token). Luôn import từ `AxiosInterceptor`.
+
+2. **`useEffect` thiếu dependency** → Stale closure bug. React strict mode sẽ catch nhưng production thì không. Luôn check deps.
+
+3. **`any` type leakage** → TypeScript mất giá trị. Dùng `unknown` + type guard thay vì `any`.
+
+4. **Token trong localStorage** → XSS có thể steal. Dùng httpOnly cookie hoặc in-memory storage.
+
+5. **`console.log` với sensitive data** → Token, balance, CCCD lọt vào browser console. Remove tất cả debug logs trước ship.
+
+6. **Base64 encode nhầm encrypt** → `btoa(customerId)` chỉ encoding, không bảo mật. Không dùng thay thế encryption.
+
+7. **`useAppSelector` vs `useSelector`** → Phải dùng typed hooks từ store, không dùng raw Redux hooks. Mất type safety.
+
+## Step 0 — Auto-Detect Stack (luôn làm trước)
+
+```bash
+# Detect versions
+cat package.json | grep -E '"react"|"typescript"|"@reduxjs|"react-query"|"antd"|"@mui|"vite"'
+
+# Detect build tool (CRA vs Vite)
+ls vite.config.* package.json
+
+# Read 2-3 nearby files để mirror exact style
+```
+
+Xác định:
+- React version → hooks patterns, concurrent features
+- Build tool: CRA (`react-scripts`) hay Vite
+- UI lib: Ant Design v4/v5 hay MUI v5
+- State: Redux Toolkit, Zustand hay Context
+- Query: react-query v3, TanStack v4/v5 hay SWR
+
+## TypeScript Conventions (official)
+
+**Naming conventions:**
+```typescript
+// Interface/Type/Class/Enum: PascalCase
+interface CustomerData { id: number; name: string }
+type ApiResponse<T> = { code: string; data: T; message: string }
+enum TransactionStatus { PENDING = 'PENDING', SUCCESS = 'SUCCESS' }
+
+// Variable/Function: camelCase
+const customerData = fetchCustomer(id);
+
+// Component: PascalCase matching filename
+const CustomerDetailPage: React.FC = ({ id }) => { };
+
+## API Module Pattern
+
+PASS: Use shared axiosInstance with interceptors (auth token, refresh):
+```typescript
+import axiosInstance from '../../config/AxiosInterceptor';
+
+// Sensitive params: base64 encode (custId, custNo, mobiNumber, walletId, accountNo)
+export const getWallet = async (custId: number) => {
+  const { data } = await axiosInstance.get(`/api/v1/wallet/${btoa(String(custId))}`);
+  return data;
+};
+```
+
+FAIL: Raw axios bypasses auth interceptor:
+```typescript
+
+## React Query — Version-Adaptive
+
+```typescript
+// v3: useQuery(['key', id], () => fn(id))
+// v4/v5 TanStack: useQuery({ queryKey: ['key', id], queryFn: () => fn(id) })
+
+// Invalidate cache sau mutation:
+const client = useQueryClient();
+useMutation(createFn, {
+  onSuccess: () => client.invalidateQueries(['list-key'])
+});
+```

package/skills/vetc-iterative-retrieval/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: vetc-iterative-retrieval
+description: PROACTIVELY activate khi subagent cần progressive context refinement — khi kết quả ban đầu không đủ thông tin, cần tìm kiếm sâu hơn. 4-phase DISPATCH→EVALUATE→REFINE→LOOP pattern cho high-quality context retrieval.
+---
+
+# VETC Iterative Retrieval
+
+Structured pattern cho progressive context refinement trong subagents. Thay vì tìm kiếm 1 lần và chấp nhận kết quả, iterative retrieval cho phép refine queries dựa trên kết quả trước.
+
+## When to Activate
+
+- Subagent trả về kết quả surface-level, cần deep-dive
+- Research task cần cross-reference multiple sources
+- Code search trả về quá nhiều hoặc quá ít kết quả
+- Cần verify thông tin từ nhiều góc độ
+- Agent nhận được kết quả nhưng relevance thấp
+
+## Do NOT Activate When
+
+- Single search đã trả về kết quả chính xác → không cần iterative loop
+- Đã biết chính xác file/function cần xem → đọc trực tiếp
+- Task không liên quan research/explore (code implementation, bug fix)
+- Timeline gấp, không có thời gian cho multi-pass retrieval
+
+## Core Pattern: DISPATCH → EVALUATE → REFINE → LOOP
+
+### Phase 1: DISPATCH
+
+Gửi initial query đến data source (code search, web search, file read).
+
+```
+Input: { query, sources, context }
+Output: { rawResults, metadata }
+```
+
+**Rules:**
+- Query phải specific, include context về WHY cần thông tin
+- Chỉ định sources rõ ràng: `codebase`, `web`, `docs`, `memory`
+- Include rejection criteria: kết quả nào KHÔNG chấp nhận được
+
+### Phase 2: EVALUATE
+
+Đánh giá relevance của kết quả từ Phase 1.
+
+```
+Scoring:
+  1.0  = Exactly what needed, complete answer
+  0.7+ = Good match, partial answer, need minor bổ sung
+  0.4+ = Related but tangential, need to narrow focus
+  <0.4 = Not relevant, need completely different query
+```
+
+**Evaluation Criteria:**
+- [ ] Kết quả trả lời trực tiếp câu hỏi?
+- [ ] Code examples (nếu cần) present và runnable?
+
+### Phase 3: REFINE
+
+Nếu EVALUATE score < 0.7, refine query.
+
+**Refinement Strategies:**
+
+| Strategy | Khi nào dùng | Ví dụ |
+|----------|-------------|-------|
+| **Narrow** | Quá nhiều kết quả | "Spring Boot 3.2 JWT filter" → "Spring Boot 3.2 JwtAuthenticationFilter OncePerRequestFilter" |
+| **Broaden** | Quá ít kết quả | "Oracle NVARCHAR2 @Nationalized VETC" → "Oracle NVARCHAR2 Hibernate annotation" |
+| **Reframe** | Sai góc nhìn | "How to fix Feign 503" → "Feign client circuit breaker configuration" |
+| **Decompose** | Query quá complex | "Implement payment reconciliation" → "1) Batch processing pattern 2) Mismatch detection 3) Settlement logic" |
+| **Cross-ref** | Cần verify | Tìm trong codebase X, verify bằng docs Y |
+
+### Phase 4: LOOP
+
+Quay lại Phase 1 với refined query.
+
+**Rules:**
+- **Max 3 cycles** — sau 3 lần vẫn score < 0.7 → accept best result + flag gaps
+- Mỗi cycle PHẢI thay đổi query — KHÔNG retry identical query
+- Mỗi cycle ghi nhận: what changed, why, expected improvement
+
+## Anti-Patterns (KHÔNG LÀM)
+
+| Anti-Pattern | Tại sao sai | Thay thế |
+|-------------|-------------|----------|
+| Infinite loop | Waste tokens, no progress | Max 3 cycles |
+| Same query retry | Won't produce different result | REFINE before re-dispatch |
+| Accept first result blindly | Miss better answers | Always EVALUATE |
+| Over-refine | Chase perfection | 0.7+ is good enough |
+| Skip evaluation | Don't know if results help | Score every result |
+
+## Agent Integration
+
+### Khi spawn subagent cho research
+
+```markdown
+## Task
+{mô tả task}
+
+## Retrieval Protocol
+Use iterative retrieval (max 3 cycles):
+1. DISPATCH: search with specific query
+2. EVALUATE: score results 0-1 (need 0.7+)
+3. REFINE: adjust query if < 0.7
+4. LOOP: retry with refined query
+
+## Rejection Criteria
+- Generic advice without VETC context
+- Outdated patterns (pre-2024)
+- No code examples for implementation tasks
+- Only theoretical without practical application
+```

package/skills/vetc-java-patterns/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: vetc-java-patterns
+description: PROACTIVELY activate khi implement backend Java/Spring Boot, thêm endpoint/service/entity, hoặc code review Java. Auto-detect version từ pom.xml. Bao gồm Controller/Service/Repository/Entity/Exception/Cache/RabbitMQ patterns.
+---
+
+# VETC Java Patterns
+
+Java/Spring Boot implementation patterns cho VETC E-Wallet.
+
+## When to Activate
+
+- Implement backend Java/Spring Boot feature
+- Thêm endpoint, service, entity, repository
+- Tích hợp external service (ACS, Bank GW, eKYC)
+- Fix Java compile error hoặc logic bug
+- Code review Java code
+
+## Do NOT Activate When
+
+- Đang làm việc trên code không phải Java (frontend, script, config file)
+- Chỉ làm frontend React/TypeScript work (dùng `vetc-frontend-patterns`)
+- Chỉ viết test, không implement business logic
+
+## Step 0 — Auto-Detect Stack (luôn làm trước)
+
+```bash
+# Detect Java version và Spring Boot version
+grep -E "<java.version>|<spring-boot.version>" pom.xml
+
+# Detect dependencies
+grep -E "springfox|springdoc|junit|lombok|mapstruct" pom.xml
+
+# Read 2-3 nearby implementation files để mirror style
+```
+
+Kết quả → xác định:
+- `javax.*` (Spring Boot 2.x) hay `jakarta.*` (Spring Boot 3.x)
+- JUnit 4 hay JUnit 5
+- Springfox (Swagger 2) hay springdoc (OpenAPI 3)
+- Field injection (`@Autowired`) hay constructor injection
+
+## Core Patterns
+
+### Layered Architecture (bất biến)
+```
+Controller (thin: validate → delegate → return)
+    ↓
+Service (business logic + @Transactional)
+    ↓
+Repository (data access only)
+    ↓
+Entity (JPA mapping to Oracle)
+```
+
+### Controller
+```java
+@RestController
+@RequestMapping("api/v{N}/{domain}")
+public class XxxController extends ControllerBase {
+    @Autowired  // hoặc constructor inject — mirror nearby code
+    private XxxService service;
+
+    @PostMapping("/endpoint")
+    public ResultResp<?> create(
+            @AuthenticationPrincipal Jwt token,
+            @Valid @RequestBody XxxRequest request) {
+        return ResultResp.success(service.create(request));
+    }
+}
+```
+
+### Service
+```java
+@Service
+@Slf4j
+public class XxxServiceImpl implements XxxService {
+    @Override
+    @Transactional  // chỉ ở service layer
+    public XxxResponse create(XxxRequest request) {
+        // 1. Business validation → throw CustomizeException
+        // 2. Business logic
+        // 3. Save entity
+        // 4. Publish event (RabbitMQ nếu cần)
+        // 5. Return DTO — không expose entity
+    }
+}
+```
+
+### Entity — Oracle Conventions
+```java
+@Builder @AllArgsConstructor @NoArgsConstructor @Getter @Setter
+@Entity(name = "TABLE_NAME")  // UPPERCASE
+public class Xxx {
+    @Id
+    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "TABLE_NAME_SEQ")
+    @SequenceGenerator(name = "TABLE_NAME_SEQ", allocationSize = 1)
+    @Column(name = "AUTOID")
+    private Long id;
+
+    @Column(name = "AMOUNT", precision = 20, scale = 4)
+    private BigDecimal amount;  // KHÔNG dùng double/float cho tiền
+
+    @Nationalized  // NVARCHAR2 — tiếng Việt
+
+### Repository — Parameterized queries ONLY
+
+FAIL: SQL injection via string concatenation:
+```java
+// KHÔNG BAO GIỜ làm thế này
+@Query(nativeQuery = true, value =
+    "SELECT * FROM TABLE WHERE STATUS = '" + status + "'")
+
+

package/skills/vetc-meta-skill-creator/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vetc-meta-skill-creator
+description: PROACTIVELY activate khi user muốn tạo skill mới, distill pattern từ session, hoặc promote instinct thành skill. Scaffold skill với YAML frontmatter chuẩn, references folder, và integration checklist.
+---
+
+# VETC Meta Skill Creator
+
+Skill để tạo skill mới. Inspired by superpowers `create-skill` pattern. Giúp maintain consistency + quality cho toàn bộ skill library.
+
+## When to Activate
+
+- User muốn tạo skill mới: "tạo skill vetc-xxx", "make a skill for yyy"
+- Distill pattern từ session hiện tại thành reusable skill
+- Promote instinct có confidence cao thành formal skill
+- `/vetc-learn` detected pattern đủ mature để skill-ize
+- User nói: "this should be a skill", "convert this to skill"
+
+## Do NOT Activate When
+
+- Skill tương đương đã tồn tại — search trước khi tạo
+- Pattern chỉ áp dụng 1 lần — instinct đủ rồi, không cần skill
+- User muốn sửa skill hiện có → dùng Edit trực tiếp
+- Generic best practice đã có trong `rules/*.md`
+
+## Skill Quality Criteria
+
+Skill MỚI chỉ nên tạo khi thỏa mãn:
+
+- [ ] **Specific**: có trigger rõ ràng, không overlap skill khác
+- [ ] **Actionable**: user follow được từ trigger đến output
+- [ ] **Reusable**: áp dụng cho >= 3 scenarios khác nhau
+- [ ] **VETC-flavored**: có VETC domain context (không generic)
+- [ ] **Testable**: output có thể verify
+- [ ] **Non-duplicate**: không trùng với 32 skills hiện có
+
+## Workflow
+
+### Step 1 — Validate Proposal
+
+Trước khi tạo file:
+
+```
+Search existing skills for similar scope:
+- grep -r "{keyword}" skills/*/SKILL.md
+- List overlapping skills, justify differentiation
+- Check rules/*.md — không duplicate generic rule
+```
+
+Nếu overlap > 70% → DO NOT CREATE, recommend extend existing skill.
+
+### Step 2 — Define Skill Metadata
+
+```yaml
+---
+name: vetc-{kebab-case-name}
+description: PROACTIVELY activate khi {specific trigger}. {What it does in 1 sentence.}
+effort: low | medium | high
+allowed-tools: # optional - restrict tools if needed
+paths: # optional - auto-activate when working in these paths
+---
+```
+
+**Naming rules:**
+- Prefix `vetc-` mandatory
+- Kebab-case, all lowercase
+
+### Step 3 — Scaffold Skill Files
+
+```bash
+# Create skill directory
+mkdir -p skills/vetc-{name}/references/
+
+# Create SKILL.md with template
+# (use content from Step 4 below)
+
+# Create first reference file if needed
+touch skills/vetc-{name}/(see docs)
+```
+
+### Step 4 — SKILL.md Structure
+
+See full template: `./(see docs)`
+
+Quick rules:
+- **Naming**: `vetc-{verb}-{noun}` hoặc `vetc-{domain}`, 10-40 chars, prefix `vetc-` mandatory
+- **Description**: Start with "PROACTIVELY activate khi...", 1-2 sentences, unique
+- **Effort**: `low` (<5min), `medium` (10-30min), `high` (30+ min)
+
+### Step 5 — Optional: Create Reference Files
+
+For progressive disclosure (from superpowers pattern):
+
+```
+skills/vetc-{name}/references/
+├── code-snippets.md    ← Language-specific examples (PASS/FAIL pattern)
+├── checklist.md        ← Step-by-step validation checklist
+├── anti-patterns.md    ← Detailed anti-patterns with examples
+└── advanced.md         ← Expert-level usage
+```