Cơ chế Skill — 4 Lớp cấu trúc

ClaudeKit được xây dựng từ 4 lớp (layers), mỗi lớp có vai trò riêng. Hiểu cơ chế này giúp bạn tùy chỉnh và mở rộng skills theo nhu cầu.

Tổng quan 4 Lớp

Layer 4: hooks/*.cjs          ← Tự động chạy trước/sau events (git, build, deploy)
Layer 3: agents/*.md           ← Định nghĩa agents chuyên biệt (AI workers)
Layer 2: commands/*.md         ← Slash commands (/plan, /cook, /fix) — giao diện người dùng
Layer 1: skills/*/SKILL.md     ← Logic chính của skill — "bộ não"

Luồng hoạt động: Người dùng gõ command (Layer 2) → command gọi skill (Layer 1) → skill có thể delegate cho agent (Layer 3) → hooks (Layer 4) tự động chạy trước/sau events.

Luồng hoạt động chi tiết

Khi bạn gõ /cook "add auth", đây là những gì diễn ra qua 4 layers:

Layer 2 — Command nhận input

File .claude/commands/cook.md nhận $ARGUMENTS = “add auth”. Command chứa instructions gọi skill + workflow logic.

Layer 1 — Skill xử lý logic chính

File .claude/skills/cook/SKILL.md được kích hoạt. Skill đọc instructions, detect mode, bắt đầu workflow 7 bước. Skill có thể đọc thêm references/*.md (lazy-load khi cần).

Layer 3 — Agents được delegate tasks

Skill spawn agents qua Task tool:

researcher → tìm hiểu codebase (chạy song song)
planner → tạo plan
coder → viết code
tester → viết + chạy tests
code-reviewer → review code Mỗi agent có .claude/agents/ten-agent.md định nghĩa role + tools.

Layer 4 — Hooks chạy tự động

Trước khi Write file → PreToolUse hook chạy (check rules). Sau khi Bash → PostToolUse hook chạy (log, format). Config trong .claude/settings.json.

Layer 1: SKILL.md — Bộ não của skill

File chính định nghĩa logic của skill. Đường dẫn thực tế:

~/.claude/skills/ck-plan/SKILL.md      # Plan skill (global)
~/.claude/skills/cook/SKILL.md         # Cook skill (global)
~/.claude/skills/fix/SKILL.md          # Fix skill (global)
~/.claude/skills/code-review/SKILL.md  # Code Review skill (global)
~/.claude/skills/ck-debug/SKILL.md     # Debug skill (global)
~/.claude/skills/ck-scenario/SKILL.md  # Scenario skill (global)
~/.claude/skills/qa-full/SKILL.md      # QA Full skill (global)

Cấu trúc file SKILL.md

---
name: ck:cook
description: "ALWAYS activate this skill before implementing EVERY feature"
argument-hint: "[task|plan-path] [--interactive|--fast|--parallel]"
metadata:
  author: claudekit
  version: "2.1.1"
---

# Cook - Smart Feature Implementation

## HARD-GATE
Do NOT write code until a plan exists and has been reviewed.

## Process Flow (Authoritative)
[Mermaid diagram — đây là workflow chính thức]

## Workflow Overview
[Chi tiết từng bước]

## References
- references/intent-detection.md
- references/workflow-steps.md
[Load khi cần, không load tất cả]

Đặc điểm quan trọng

Thành phần	Vai trò
Frontmatter	Metadata: `name`, `description`, `version`, `argument-hint`
Body	Instructions chi tiết — Claude đọc và làm theo
HARD-GATE	Điều kiện bắt buộc: không code nếu chưa plan
Process Flow	Mermaid diagram là workflow chính thức
References	Lazy-load files bổ sung khi cần

Ví dụ cấu trúc thư mục skill

.claude/skills/cook/
├── SKILL.md                        # Logic chính
├── references/
│   ├── intent-detection.md         # Rules detect mode
│   ├── workflow-steps.md           # Chi tiết từng bước
│   ├── review-cycle.md             # Logic review (auto vs HITL)
│   └── subagent-patterns.md        # Cách spawn subagents
└── templates/
    └── report-template.md          # Template output

Layer 2: Commands — Giao diện người dùng

Định nghĩa slash commands mà người dùng gõ trực tiếp. Đường dẫn thực tế:

~/.claude/commands/
├── prd.md                  # → /prd (custom PrimeCommerce command)
├── code-review.md          # → /code-review
├── deploy.md               # → /deploy
├── qa-full/                # → nhóm /qa-full:*
│   ├── verify-issue.md     # → /qa-full:verify-issue
│   ├── check.md            # → /qa-full:check
│   ├── audit.md            # → /qa-full:audit
│   ├── full.md             # → /qa-full:full
│   ├── accept.md           # → /qa-full:accept
│   ├── regression.md       # → /qa-full:regression
│   └── tdd/verify.md       # → /qa-full:tdd:verify
├── docs-project/           # → nhóm /docs-project:*
│   ├── prd.md              # → /docs-project:prd
│   ├── ui.md               # → /docs-project:ui
│   ├── qa.md               # → /docs-project:qa
│   ├── full.md             # → /docs-project:full
│   └── guide.md            # → /docs-project:guide
├── ckm/                    # → nhóm /ckm:* (marketing)
│   ├── plan/               # → /ckm:plan:*
│   ├── write/              # → /ckm:write:*
│   ├── skill/              # → /ckm:skill:*
│   ├── docs/               # → /ckm:docs:*
│   └── ... (nhiều sub-groups)
├── huashu-design/          # → nhóm /huashu-design:*
│   ├── prototype.md, animation.md, deck.md, ...
└── ...

Quy tắc đặt tên — rất quan trọng

Thư mục = nhóm lệnh (ví dụ: qa-full/, fix/)
File = tên lệnh (ví dụ: verify-issue.md, fast.md)
Slash command = /{thư-mục}:{file} (ví dụ: /qa-full:verify-issue)
Thư mục lồng = sub-group (ví dụ: ckm/seo/ → /ckm:seo:*)

Layer 3: Agents — AI Workers chuyên biệt

Định nghĩa agents chuyên biệt. Đường dẫn thực tế:

~/.claude/agents/
├── planner.md              # Lập kế hoạch
├── researcher.md           # Tìm hiểu codebase
├── coder.md                # Viết code
├── tester.md               # Viết + chạy tests
├── code-reviewer.md        # Review code
├── qa-engineer.md          # QA chuyên biệt
├── docs-manager.md         # Cập nhật docs
├── project-manager.md      # Tổng hợp kết quả
└── git-manager.md          # Git operations

Cách agents phối hợp

Đặc điểm:

Agents có thể chạy song song (researchers) hoặc tuần tự (coder → tester)
Mỗi agent có tool access riêng (coder có write, tester có bash)
Agent có thể delegate cho agent khác (nesting)
project-manager tổng hợp kết quả cuối cùng

Agents trong ClaudeKit Engineer

Agent	Vai trò	Chạy khi
`planner`	Lập kế hoạch	`/plan`, `/cook`, `/vibe`
`researcher`	Tìm hiểu codebase (chạy parallel)	`/plan`, `/research`
`coder`	Viết code production	`/cook`, `/vibe`
`fullstack-developer`	Full-stack (FE + BE)	`/cook --auto`, `/vibe`
`tester`	Viết & chạy tests	`/cook`, `/test`, `/verify`
`qa-engineer`	QA chuyên biệt	`/qa-full:*`, `/qa-pro-max`
`code-reviewer`	Review code quality	`/code-review`, `/review-pr`, `/review`
`debugger`	Debug systematic	`/investigate`, `/ck-debug`
`docs-manager`	Cập nhật tài liệu	`/cook` (auto), `/docs`
`project-manager`	Tổng hợp kết quả	`/cook` (auto), `/vibe`

Layer 4: Hooks — Tự động hóa

Tự động chạy trước/sau các events. Đường dẫn thực tế:

~/Claude Code/.claude/hooks/
├── privacy-block.cjs       # Block leak secrets/PII
├── dev-rules-reminder.cjs  # Nhắc tuân thủ coding standards
└── lark-notify.cjs         # Gửi notification qua Lark

Cấu hình trong settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/dev-rules-reminder.cjs"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/post-write-check.cjs"
          }
        ]
      }
    ]
  }
}

Sơ đồ thời điểm Hook chạy

User gõ lệnh
│
├─ PreToolUse hook chạy TRƯỚC mỗi tool call
│   ├── Trước Bash → dev-rules-reminder.cjs
│   ├── Trước Write → privacy-block.cjs (check secrets)
│   └── Hook có thể BLOCK tool call (trả about "deny")
│
├─ Tool thực thi
│
└─ PostToolUse hook chạy SAU mỗi tool call
    ├── Sau Write → format check
    ├── Sau Bash → log output
    └── Hook KHÔNG thể undo tool call

Các event phổ biến

Event	Thời điểm	Use case
`PreToolUse`	Trước khi dùng tool	Validate input, check permissions
`PostToolUse`	Sau khi dùng tool	Log, notify, auto-format
`Notification`	Khi có notification	Gửi Lark message, email

Cách skill gọi skill (Skill Chaining)

Skill có thể gọi skills khác để tạo workflow phức tạp:

# Trong verify-issue.md:

### Bước 3: Gap Analysis
Invoke Skill: ck-scenario
→ Phân tích 12 chiều để tìm edge cases

### Bước 4: Verify
Invoke Skill: ck:test
→ Chạy tests

### Bước 5 (nếu fail):
Invoke Skill: fix:test
→ Tự động fix

Khi instruction nói “Invoke Skill” → PHẢI gọi skill bằng Skill tool. KHÔNG tự làm thay. Đây là quy tắc nghiêm ngặt.

Ví dụ skill chaining phức tạp

/cook "thêm tính năng auth"
│
├── Invoke: plan (tạo kế hoạch)
│   ├── Invoke: researcher (tìm hiểu auth patterns)
│   └── Invoke: researcher (scan existing code)
│
├── Invoke: code (viết code theo plan)
│   ├── Invoke: coder (implement)
│   └── Invoke: database-admin (migration)
│
├── Invoke: test (viết tests)
│   ├── Invoke: tester (unit tests)
│   └── Invoke: qa-engineer (integration tests)
│
└── Invoke: code-review (review)
    └── Invoke: security-auditor (kiểm tra auth security)

Ví dụ skill chaining trong QA

/qa-full:verify-issue #66
│
├── Bước 3: Invoke ck-scenario
│   → Phân tích 12 dimensions, tạo TC mới
│
├── Bước 4: Invoke ck:test (nếu có unit tests)
│   → Chạy tests cho TC-IDs
│
└── Bước 5 (nếu fail): Invoke fix:test
    → Tự động fix failing tests

Tùy chỉnh & mở rộng

Thêm skill mới

/skill:create "tên-skill-mới"

Cập nhật skill hiện có

/skill:update tên-skill

Tối ưu skill

/skill:optimize tên-skill

Thêm reference files cho skill

/skill:add tên-skill

Best practices khi tạo skill:

Mỗi skill làm 1 việc rõ ràng (Single Responsibility)
Viết instructions cụ thể, không mơ hồ
Thêm ví dụ input/output trong SKILL.md
Dùng skill chaining thay vì tạo skill quá lớn
Luôn test skill trước khi share cho team
Dùng references/ folder cho lazy-load content

​Cơ chế Skill — 4 Lớp cấu trúc

​Tổng quan 4 Lớp

​Luồng hoạt động chi tiết

​Layer 1: SKILL.md — Bộ não của skill

​Cấu trúc file SKILL.md

​Đặc điểm quan trọng

​Ví dụ cấu trúc thư mục skill

​Layer 2: Commands — Giao diện người dùng

​Quy tắc đặt tên — rất quan trọng

​Layer 3: Agents — AI Workers chuyên biệt

​Cách agents phối hợp

​Agents trong ClaudeKit Engineer

​Layer 4: Hooks — Tự động hóa

​Cấu hình trong settings.json

​Sơ đồ thời điểm Hook chạy

​Các event phổ biến

​Cách skill gọi skill (Skill Chaining)

​Ví dụ skill chaining phức tạp

​Ví dụ skill chaining trong QA

​Tùy chỉnh & mở rộng

​Thêm skill mới

​Cập nhật skill hiện có

​Tối ưu skill

​Thêm reference files cho skill

Cơ chế Skill — 4 Lớp cấu trúc

Tổng quan 4 Lớp

Luồng hoạt động chi tiết

Layer 1: SKILL.md — Bộ não của skill

Cấu trúc file SKILL.md

Đặc điểm quan trọng

Ví dụ cấu trúc thư mục skill

Layer 2: Commands — Giao diện người dùng

Quy tắc đặt tên — rất quan trọng

Layer 3: Agents — AI Workers chuyên biệt

Cách agents phối hợp

Agents trong ClaudeKit Engineer

Layer 4: Hooks — Tự động hóa

Cấu hình trong settings.json

Sơ đồ thời điểm Hook chạy

Các event phổ biến

Cách skill gọi skill (Skill Chaining)

Ví dụ skill chaining phức tạp

Ví dụ skill chaining trong QA

Tùy chỉnh & mở rộng

Thêm skill mới

Cập nhật skill hiện có

Tối ưu skill

Thêm reference files cho skill