​
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:
1

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.
2

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).
3

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.
4

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ầnVai trò
FrontmatterMetadata: name, description, version, argument-hint
BodyInstructions 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 FlowMermaid diagram là workflow chính thức
ReferencesLazy-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/
├── plan.md                 # → /plan
├── cook.md                 # → /cook
├── fix.md                  # → /fix
├── fix/                    # → nhóm /fix:*
│   ├── fast.md             # → /fix:fast
│   ├── hard.md             # → /fix:hard
│   ├── test.md             # → /fix:test
│   ├── ci.md               # → /fix:ci
│   ├── types.md            # → /fix:types
│   └── ui.md               # → /fix:ui
├── 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
│   ├── tdd.md              # → /qa-full:tdd
│   └── regression.md       # → /qa-full:regression
└── scout.md                # → /scout

​
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

AgentVai tròChạy khi
plannerLập kế hoạch/plan, /cook
researcherTìm hiểu codebase (chạy parallel)/plan, /plan:hard
coderViết code production/cook, /code
fullstack-developerFull-stack (FE + BE)/cook:auto:parallel
testerViết & chạy tests/cook, /test
qa-engineerQA chuyên biệt/qa-full:*
code-reviewerReview code quality/code-review, /review
docs-managerCập nhật tài liệu/cook (auto)
project-managerTổng hợp kết quả/cook (auto)

​
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

EventThời điểmUse case
PreToolUseTrước khi dùng toolValidate input, check permissions
PostToolUseSau khi dùng toolLog, notify, auto-format
NotificationKhi có notificationGử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