Skip to main content
Điểm cốt lõi của bài này
Claude Code linh hoạt, không cứng. Bạn tổ chức agent và skill theo cách hợp với bộ não của bạn — Claude theo ý định, không theo quy ước thư mục. Chúng tôi xây Lulu DocOps ở một thư mục hoàn toàn tự thiết kế, không trong .claude/agents/ hay .claude/skills/ — và nó vận hành hoàn hảo.

Mở đầu — Lật ngược mặc định

Trong tài liệu chính thức của Claude Code, bạn sẽ đọc thấy: sub-agent nằm ở .claude/agents/, skill nằm ở .claude/skills/. Nghe như quy tắc cứng. Nhưng không phải. Chúng tôi không dùng cấu trúc đó. Dự án Luklak tổ chức toàn bộ agent Lulu ở luklak-mintlify-docs/Lulu/ — một đường dẫn hoàn toàn tự chọn, tên thư mục tự đặt, hệ phân cấp tự thiết kế. Và Claude Code vẫn gọi đúng skill, đúng lúc, đúng context. Bài này kể lại cách chúng tôi làm, vì sao nó chạy được, và bạn có thể bắt chước như thế nào.

Vì sao nó vẫn chạy được?

Bốn lý do cốt lõi:
  • Bạn tham chiếu đường dẫn file → Claude đọc qua công cụ Read
  • Bạn mô tả vai trò và skill của agent trong prompt → Claude “nhập vai” agent đó cho lượt đó
  • Bạn yêu cầu “chạy skill dịch thuật” → Claude đọc file skill đó và làm theo
  • Sub-agent có thể được định nghĩa inline trong prompt, không nhất thiết trong file
Nguyên lý cốt lõi: “magic” của Claude Code không nằm ở quy ước file. Nó nằm ở chỗ Claude suy luận về ngữ cảnh bạn cung cấp. Bạn chỉ tay tới file nào, Claude đọc file đó. Bạn mô tả nhiệm vụ thế nào, Claude làm đúng thế. Quy ước .claude/agents/.claude/skills/ chỉ là đường tắt (shortcut) để Claude Code tự động phát hiện (auto-discover) agent và skill. Nếu bạn không dùng đường tắt đó, bạn chỉ cần chỉ đường thủ công — mà thủ công thì không khó, chỉ là viết đường dẫn vào prompt.

Tham quan thư mục Lulu

Cấu trúc thực tế của agent Lulu DocOps trong repo Luklak:
luklak-mintlify-docs/Lulu/
├── README.md                        # Cổng vào — ai là Lulu, ở đâu bắt đầu
├── CHANGELOG.md                     # Lịch sử phiên bản
├── 00-identity/                     # Danh tính: charter + persona framework
│   ├── lulu-charter.md
│   └── persona-framework.md
├── 01-system-prompt/                # Prompt hệ thống chính + EN + VI
│   ├── lulu-system-prompt.md
│   ├── lulu-system-prompt-en.md
│   └── lulu-system-prompt-vi.md
├── 02-skills/                       # 8 skill chuyên biệt
│   ├── skill-write-platform-article.md
│   ├── skill-write-build-playbook.md
│   ├── skill-write-user-guide.md
│   ├── skill-write-onboarding.md
│   ├── skill-translate-en-to-vi.md
│   ├── skill-generate-guidejar-tutorial.md
│   ├── skill-quality-gate-review.md
│   └── skill-glossary-lookup.md
├── 03-reference/                    # Thư viện tham chiếu
│   ├── luklak-product-knowledge.md
│   ├── docops-reference-guide.md
│   ├── portal-architecture.md
│   ├── tab-01-getting-started.md
│   ├── tab-02-core-platform.md
│   ├── ... (các tab reference khác)
│   ├── naming-convention.md
│   ├── mintlify-components.md
│   └── docs-json-pattern.md
├── 04-glossary/                     # Thuật ngữ EN↔VI
│   ├── glossary-en-vi.md
│   └── glossary-sources.md
├── 05-templates/                    # Mẫu .mdx để Lulu điền
├── 06-quality/                      # Checklist trước khi publish
└── 99-archive/                      # Tài liệu cũ giữ lại
Mỗi folder phục vụ một mục đích biên tập rõ ràng:
Charter (điều lệ) định nghĩa nhân vật: tên, sứ mệnh, giọng điệu, quyền hạn, giới hạn. Persona framework mô tả bốn chân dung người đọc (personas) P1–P4 mà Lulu cần phục vụ. Đọc hai file này, Claude hiểu nó đang “đóng vai” ai.
Prompt hệ thống (system prompt) là chỉ dẫn chính. Có bản gốc, bản EN, bản VI. Khi bắt đầu phiên làm việc, Claude đọc file này để nạp toàn bộ nguyên tắc biên tập.
Tám skill độc lập, mỗi skill là một quy trình khép kín: viết bài platform, viết playbook, dịch EN→VI, sinh guidejar tutorial, review chất lượng, tra cứu glossary… Lulu chỉ “bật” một skill khi bạn yêu cầu task tương ứng.
Kiến thức sản phẩm Luklak, kiến trúc portal, cấu trúc từng tab, quy ước đặt tên file, danh sách Mintlify components, pattern docs.json. Khi Lulu cần xác minh một thông tin, nó đọc từ đây thay vì bịa.
Bảng thuật ngữ hai chiều. Bắt buộc tra cứu trước khi dịch. Đây là thứ đảm bảo “Universal Object” luôn dịch thành “Đối tượng Phổ quát”, không phải “Vật thể Toàn cầu”.
Các template .mdx có sẵn cấu trúc frontmatter, component layout, vị trí callout. Lulu chỉ điền nội dung vào khuôn — không phải dựng lại mỗi lần.
Checklist tự kiểm trước khi publish: đã tra glossary chưa, đã kiểm link chưa, đã áp đúng persona chưa, đã review giọng điệu chưa.
Tài liệu cũ, bản nháp đã thay thế, ghi chú lịch sử. Giữ lại để tra cứu khi cần, nhưng không nạp vào context hiện tại.

So sánh: Chính thức vs Của chúng tôi

your-project/
└── .claude/
    ├── agents/
    │   └── my-agent.md
    └── skills/
        └── my-skill/
            └── SKILL.md
Claude Code tự động quét thư mục .claude/ và nạp mọi agent, skill nó tìm thấy. Bạn không phải chỉ đường — framework làm giúp.Phù hợp cho: dự án lập trình, nơi thư mục .claude/ nằm gọn cùng source code, team dev quen với convention.
Cấu trúc chính thức phù hợp với dự án lập trình. Cấu trúc của Lulu phù hợp với bộ não của editor-in-chief — các danh mục phản ánh cách một editor tư duy về công việc của mình: trước tiên là danh tính, rồi đến giọng điệu, rồi tay nghề, rồi tham chiếu, rồi chất lượng.

Một skill file trông như thế nào?

# Skill: Transcreate EN → VI

**Trigger**: When a finished (or draft) EN article needs a
Vietnamese counterpart for `mintlify-tailieuvn`.

## Inputs required

- EN source article (paste content or provide file path)
- `filename` — translate the EN slug into a clean Vietnamese
  kebab-case slug (e.g. `thiet-lap-tai-khoan`)
- `tab` — which tab (1–6), informs voice register
- `primary_persona` — check `content-plan.md` or the EN frontmatter
- Reference to the section context (what this article is about)

## Reference files to load

1. `../01-system-prompt/lulu-system-prompt-vi.md` — complete VI
   writing rules
2. `../00-identity/persona-framework.md` — P1–P4 VI voice samples
3. `../04-glossary/glossary-en-vi.md`**mandatory**, check every
   Luklak-specific term
4. `../03-reference/luklak-product-knowledge.md` — verify any
   product claims
5. `../06-quality/pre-publish-checklist.md` — section 3
   (Bilingual Standards)

## The transcreation process

### Step 1 — Scan for terms (before writing)
Before drafting, scan the EN article for every Luklak-specific
term (Object, Space, Function, Workview, UQL, Automation, etc.).
Map each one to the VI canonical term in `glossary-en-vi.md`.
Flag any term not in the glossary — **add it or ask before
proceeding**.

### Step 2 — Identify the register
| Tab | Persona | VI register |
|---|---|---|
| 1 (philosophy) | P1 / All | Strategic, brand-forward. |
| 2 (platform) | P2 | Technical-professional. |
| 3 (playbooks) | P2 | Workshop tone. Action-focused. |
Nhìn kỹ: file này là prose (văn xuôi tiếng Anh) + checklist + bảng Markdown. Không có YAML frontmatter đặc biệt, không có cú pháp framework. Chỉ là một tài liệu mô tả quy trình — đủ rõ để Claude đọc và làm theo.
Đó là bí mật: skill file chỉ là file Markdown mô tả quy trình. Không có “magic format”. Claude đọc nó như đọc một SOP (standard operating procedure) nội bộ của công ty.

Cách Lulu được “nhập vai” — sơ đồ luồng

Không có “magic registration”. Claude chỉ đọc đúng file theo thứ tự bạn chỉ dẫn, rồi thực thi với toàn bộ ngữ cảnh đã nạp. Đây là lý do cấu trúc Lulu hoạt động — mỗi folder có trách nhiệm rõ ràng, mỗi skill tự khép kín.

Cách Lulu được “nhập vai” — các bước cụ thể

Khi bắt đầu một phiên làm việc, bạn không cần “khởi động Lulu” đặc biệt. Chỉ cần:
1

Mở Claude Code trong thư mục dự án

mintlify-tailieuvn hoặc luklak-mintlify-docs — nơi có folder Lulu/.
2

Ra lệnh chỉ đường rõ ràng

Ví dụ: “Đọc Lulu charter ở Lulu/00-identity/lulu-charter.md, sau đó làm theo Lulu/02-skills/skill-translate-en-to-vi.md cho file X.”
3

Claude tự nhập vai

  • Dùng tool Read đọc charter → hiểu danh tính Lulu, giọng điệu, nguyên tắc
  • Dùng tool Read đọc skill file → hiểu các bước cần theo
  • Áp dụng đúng style, thuật ngữ, quy trình vào task
Không cần YAML frontmatter đặc biệt. Không cần registration. Không cần setup tool.

Kết quả thực tế

Với cấu trúc tự thiết kế này, Luklak đã:
  • Dịch thành công 14+ trang tiếng Việt với giọng điệu nhất quán
  • Chạy 7 agent song song dịch toàn bộ LAIKA flagship case study trong 5 phút
  • Duy trì chất lượng biên tập giữa các phiên làm việc khác nhau, ngay cả khi người chạy Claude Code thay đổi
  • Onboard thành viên mới vào workflow chỉ bằng câu: “đọc Lulu folder”
Điểm quan trọng: không phải công cụ quyết định kết quả — mà là cách bạn tổ chức ngữ cảnh. Cấu trúc Lulu tự thiết kế giúp một biên tập viên người thật hiểu hệ thống trong 15 phút, và giúp Claude nhập vai đúng trong một câu lệnh.

Tự kiểm tra

Không. Claude Code theo ý định, không theo quy ước thư mục. Đặt bất kỳ đâu, đặt tên bất kỳ — chỉ cần prompt chỉ đúng đường dẫn. Thư mục .claude/agents/ chỉ là đường tắt để auto-discover; nếu không dùng, bạn chỉ việc nêu đường dẫn trong prompt.
Có, thậm chí nên. Nhưng đừng copy nguyên si — thiết kế lại theo cách bạn tư duy. Agent Finance, HR, Sales sẽ có cấu trúc khác: Finance có thể cần 04-policies/, HR có thể cần 04-templates-letters/, Sales có thể cần 04-playbooks-by-stage/. Hãy lấy nguyên lý phân chia, đừng lấy tên folder.
Trong cấu trúc tự thiết kế: không. Bạn phải chỉ đường. Nhưng đó không phải vấn đề — bạn chỉ cần viết trong README.md hoặc CLAUDE.md ở gốc dự án: “Agent X ở đường dẫn Y, khởi động bằng prompt Z.” Claude sẽ đọc CLAUDE.md đầu mỗi phiên và biết đường tìm.

Bài tập

1

Chọn một vai trò trong công ty bạn

Finance analyst, HR coordinator, Customer Support lead — bất kỳ vai trò nào có công việc lặp đi lặp lại.
2

Liệt kê 3-5 task chính vai trò đó làm hàng ngày

Ví dụ Finance: review hóa đơn, làm báo cáo tuần, đối chiếu ngân hàng, duyệt đề nghị thanh toán.
3

Đặt tên skill cho mỗi task

Mỗi task có thể trở thành 1 skill. Ví dụ: skill-review-invoice.md, skill-draft-offer-letter.md, skill-weekly-revenue-report.md.
4

Phác thảo cấu trúc folder cho agent của bạn

Không copy Lulu. Tổ chức theo cách bạn tư duy về công việc. Có thể: 00-identity/, 01-policies/, 02-skills/, 03-data-sources/, 04-templates/, 05-review-gates/.
5

Viết một file charter.md ngắn

5-10 dòng định nghĩa agent: tên, vai trò, giọng điệu, quyền hạn, giới hạn. Đây là “CMND” của agent.
6

Thử bằng Claude Code

Mở thư mục của bạn, yêu cầu Claude đọc charter rồi làm 1 task theo 1 skill. Quan sát: Claude có nhập vai đúng không? Kết quả có đúng giọng điệu không?

Tiếp theo?