3 lỗi thường gặp khi sử dụng Claude Code Skills

Hầu hết người dùng Claude Code cài đặt quá nhiều skill, bỏ qua phần tùy chỉnh và nhồi nhét mọi thứ vào một file duy nhất. Dưới đây là cách xây dựng các skill thực sự hiệu quả.

Sai lầm 1: Cài đặt quá nhiều skill

Đây là sai lầm phổ biến nhất, và cũng là sai lầm khó tránh nhất. Khi bạn thiết lập một trợ lý lập trình mạnh mẽ, việc thêm nhiều khả năng hơn có vẻ như làm cho nó mạnh mẽ hơn. Trên thực tế, vượt quá một điểm nhất định, bạn thực sự đang làm cho nó tệ hơn.

Cách kiểm tra các skill đã cài đặt

Một quá trình kiểm tra tốt bắt đầu bằng một câu hỏi đơn giản cho mỗi skill đã cài đặt: Bạn đã sử dụng skill này trong hai tuần qua chưa? Nếu chưa, hãy tạm thời vô hiệu hóa nó. Bạn luôn có thể kích hoạt lại sau.

Cụ thể hơn, hãy xem xét cấu hình MCP của bạn và phân loại từng server:

Skill cốt lõi (luôn giữ hoạt động):

• Thao tác hệ thống file
• Thực thi shell
• Công cụ tìm kiếm và điều hướng code dành riêng cho hệ thống của bạn

Skill dành riêng cho dự án (kích hoạt theo dự án):

• Database connector
• Tích hợp CMS hoặc nền tảng
• API server cụ thể

Công cụ thỉnh thoảng (chỉ kích hoạt khi cần):

• Trích xuất dữ liệu web
• Tạo hình ảnh
• Công cụ giao tiếp (Slack, email)

Việc phân loại này sẽ định hướng cấu trúc cấu hình của bạn — điều này dẫn trực tiếp đến sai lầm số 3. Hiện tại, nguyên tắc là các skill đang hoạt động nên phản ánh những trường hợp sử dụng thực tế, chứ không phải các khả năng lý thuyết.

Nguyên tắc 5 công cụ

Một điểm khởi đầu thực tế: Đối với bất kỳ dự án nào, Claude Code chỉ nên có quyền truy cập vào tối đa 5-8 công cụ. Đó không phải là giới hạn cứng nhắc — một số workflow phức tạp thực sự cần nhiều skill hơn — nhưng đó là một yếu tố thúc đẩy tốt, giúp bạn phải biện minh cho mỗi lần bổ sung.

Nghiên cứu về các mô hình ngôn ngữ được hỗ trợ bởi công cụ luôn cho thấy rằng hiệu suất trên những tác vụ cụ thể thường giảm khi số lượng công cụ có sẵn tăng lên vượt quá mức cần thiết cho tác vụ đó. Claude giỏi suy luận trong điều kiện hạn chế. Cung cấp cho nó các khả năng cụ thể, và nó có xu hướng sử dụng chúng một cách hiệu quả.

Sai lầm 2: Bỏ qua việc tùy chỉnh

Sai lầm thứ hai là coi các cấu hình mặc định là tùy chọn sẵn sàng cho môi trường sản xuất. Chúng không phải vậy. Chúng chỉ là điểm khởi đầu — các thiết lập chung hoạt động “tạm ổn” trong nhiều trường hợp nhưng không được tối ưu hóa cho bất kỳ trường hợp nào.

Hầu hết các nhà phát triển cài đặt một skill, thấy rằng về mặt kỹ thuật nó hoạt động, và tiếp tục. Kết quả là một agent có thể thực hiện công việc, nhưng thực hiện một cách vụng về, không nhất quán hoặc với những thao tác qua lại không cần thiết.

Vấn đề CLAUDE.md

CLAUDE.md là một trong những tính năng mạnh mẽ nhất và ít được sử dụng nhất trong Claude Code. Đó là một file Markdown được đặt trong thư mục gốc dự án của bạn (hoặc bất kỳ thư mục con nào) mà Claude đọc khi bắt đầu mỗi phiên. Bất cứ điều gì có trong file đó, Claude đều coi đó là ngữ cảnh liên tục về dự án của bạn.

Trạng thái mặc định là không có CLAUDE.md, có nghĩa là Claude phải đoán mỗi lần:

• Bạn đang sử dụng framework nào?
• Lệnh test là gì?
• Nó nên sử dụng TypeScript hay JavaScript?
• Liệu có những quy ước lập trình nào mà nó cần tuân theo?
• Những phần nào không được phép chỉnh sửa?

Mọi lỗ hổng trong kiến ​​thức của Claude về dự án của bạn đều là cơ hội để nó đưa ra giả định sai. Và bởi vì Claude Code hoạt động tự động — chạy lệnh, chỉnh sửa file — những giả định sai có thể dẫn đến hậu quả nghiêm trọng.

Một file CLAUDE.md được viết tốt sẽ loại bỏ hầu hết những lỗ hổng đó. Đây là ví dụ về một file CLAUDE.md tối thiểu nhưng hữu ích:

# Project Context

## Stack
- Next.js 14, TypeScript, Tailwind CSS
- PostgreSQL with Prisma ORM
- Tests with Vitest and Playwright

## Commands
- `npm run dev` — start dev server
- `npm run test` — run unit tests
- `npm run test:e2e` — run Playwright tests
- `npm run build` — production build

## Conventions
- Components go in `/src/components`, one file per component
- Server actions in `/src/actions`
- Always write JSDoc for exported functions
- Use named exports, not default exports

## Do not modify
- `/src/generated/` — auto-generated Prisma files
- `.env` — managed separately, never edit directly

## Branch strategy
- Feature branches from `main`
- PRs require at least one passing test run

Chỉ khoảng 20 dòng code thôi. Nó thay đổi đáng kể cách Claude hoạt động trong dự án này — nó ngừng hỏi các câu hỏi làm rõ, đưa ra quyết định tốt hơn về vị trí file, chạy đúng các lệnh và tôn trọng những giới hạn bạn đã đặt ra.

Tùy chỉnh hành vi MCP server

Hầu hết các MCP server đều cung cấp các tùy chọn cấu hình mà người dùng không bao giờ động đến. Chúng thường nằm trong file cấu hình Claude Code của bạn (~/.claude/config.json hoặc tương đương) hoặc trong cấu hình riêng của MCP server.

Các tùy chỉnh phổ biến đáng thực hiện:

• Công cụ tìm kiếm: Đặt công cụ tìm kiếm ưa thích của bạn, cấu hình số lượng kết quả trả về, giới hạn ở các domain cụ thể nếu workflow của bạn là dành riêng cho domain đó.
• Công cụ hệ thống file: Cấu hình rõ ràng các đường dẫn được cho phép và không được phép. Không cho phép Claude truy cập vào những thư mục mà nó không có quyền truy cập.
• Database connector: Đặt chế độ chỉ đọc nếu bạn đang thực hiện công việc phân tích. Cấu hình thời gian chờ kết nối phù hợp với kích thước cơ sở dữ liệu của bạn. Chỉ định schema hoặc bảng nào có liên quan.
• Công cụ tích hợp API: Xác thực một lần và lưu trữ thông tin đăng nhập đúng cách. Cấu hình hành vi thử lại. Đặt ngưỡng giới hạn tỷ lệ phù hợp với cấp độ API của bạn.

Nguyên tắc cơ bản: Mỗi MCP server đều có các thiết lập mặc định được điều chỉnh cho trường hợp sử dụng trung bình. Trường hợp sử dụng của bạn có thể không phải là trung bình. Mười phút dành để đọc tài liệu cấu hình của server thường giúp bạn tiết kiệm hàng giờ giải quyết vấn đề sau này.

Tùy chỉnh lệnh Slash cho workflow của bạn

Các lệnh slash mặc định trong Claude Code rất hữu ích, nhưng giá trị thực sự đến từ những lệnh bạn tự xây dựng. Các lệnh slash tùy chỉnh cho phép bạn mã hóa workflow của nhóm mình thành những prompt nhất quán, có thể tái sử dụng.

Thay vì gõ cùng một prompt dài mỗi khi bạn muốn Claude xem xét yêu cầu kéo, bạn tạo /review-pr bao gồm các tiêu chí xem xét cụ thể của nhóm mình:

Check this diff for:
- Logic errors and edge cases
- Missing error handling
- N+1 query patterns in database calls
- Any hardcoded values that should be config
- Test coverage gaps

For each issue found, provide: location, severity (critical/warning/suggestion), and recommended fix.

Hãy kiểm tra sự khác biệt này để tìm:
- Lỗi logic và các trường hợp ngoại lệ
- Thiếu xử lý lỗi
- Mẫu truy vấn N+1 trong các lệnh gọi database
- Bất kỳ giá trị được hardcode nào cần được cấu hình
- Khoảng trống trong phạm vi kiểm thử

Đối với mỗi vấn đề được tìm thấy, hãy cung cấp: vị trí, mức độ nghiêm trọng (nghiêm trọng/cảnh báo/đề xuất) và giải pháp được đề xuất.

Các nhóm xây dựng được ít nhất 3-4 lệnh slash tốt sẽ báo cáo kết quả đầu ra của Claude nhất quán hơn đáng kể — bởi vì chất lượng prompt không còn thay đổi dựa trên việc người gõ lệnh có vội vàng hay mệt mỏi hay không.

Sai lầm thứ 3: Nhồi nhét mọi thứ vào một file duy nhất

Sai lầm thứ ba liên quan đến tổ chức, nhưng tác hại của nó cũng nghiêm trọng không kém hai sai lầm đầu tiên. Điều này xảy ra khi các nhà phát triển coi CLAUDE.md — hoặc bất kỳ file cấu hình nào khác — như một nơi chứa đựng mọi hướng dẫn, quy ước, tùy chọn và ghi chú mà họ muốn Claude có.

Kết quả là một file CLAUDE.md dài 500 dòng mà không ai bảo trì, trở nên mâu thuẫn theo thời gian và làm cho ngữ cảnh của Claude trở nên nặng nề một cách không cần thiết trong mỗi yêu cầu.

Mẫu CLAUDE.md cấp thư mục

Claude Code hỗ trợ các file CLAUDE.md ở nhiều cấp độ trong cấu trúc phân cấp dự án của bạn. Một file trong thư mục con sẽ được ưu tiên hơn (hoặc bổ sung) cho file cấp gốc đối với các yêu cầu liên quan đến thư mục đó.

Điều này có nghĩa là bạn có thể — và nên — phân phối các chỉ thị của mình:

project-root/
├── CLAUDE.md              # Các quy ước, mệnh lệnh và giới hạn chung của dự án
├── src/
│   ├── CLAUDE.md          # Các quy ước Frontend, những mẫu thành phần
│   ├── api/
│   │   └── CLAUDE.md      # Các quy ước API, những mẫu endpoint
│   └── db/
│       └── CLAUDE.md      # Các quy ước về cơ sở dữ liệu, quy trình di chuyển
└── tests/
    └── CLAUDE.md          # Các mẫu thử nghiệm, kỳ vọng về phạm vi bao phủ

Mỗi file đều tập trung, nhỏ gọn và phù hợp với ngữ cảnh mà Claude sẽ đọc. Khi Claude làm việc trong thư mục src/db/, nó đọc các hướng dẫn dành riêng cho cơ sở dữ liệu. Khi ở trong thư mục src/api/, nó đọc các quy ước API. Nó không cần phải mang theo tất cả mọi thứ mọi lúc.

Tách biệt cấu hình và hướng dẫn

Một sự tách biệt khác đáng thực hiện: Giữ cấu hình Claude Code của bạn (cài đặt MCP server, biến môi trường, xác thực) hoàn toàn tách biệt với các file hướng dẫn.

Cấu hình nằm trong:

• ~/.claude/config.json — cài đặt toàn cục
• Thư mục .claude/ trong dự án của bạn — ghi đè cấu hình cấp dự án

Hướng dẫn nằm trong:

• Các file CLAUDE.md ở các cấp độ thích hợp

Không nhúng các snippet cấu hình vào CLAUDE.md của bạn và không viết hướng dẫn trong những file cấu hình. Chúng phục vụ các mục đích khác nhau và thay đổi vì những lý do khác nhau. Việc trộn lẫn chúng sẽ gây nhầm lẫn về nơi cần tìm khi cần thay đổi điều gì đó.

Tổ chức cấu hình MCP server

File cấu hình MCP của bạn cũng có thể trở nên khó quản lý nhanh chóng. Một vài thói quen cấu trúc sẽ giúp ích:

• Nhóm các server theo danh mục bằng cách sử dụng comment. Hầu hết các định dạng cấu hình đều hỗ trợ comment. Sử dụng chúng để đánh dấu server nào là cốt lõi so với server dành riêng cho dự án.
• Giữ thông tin đăng nhập khỏi file cấu hình. Sử dụng các biến môi trường và tham chiếu chúng từ cấu hình. Điều này cũng giúp dễ dàng chia sẻ các file cấu hình trong kho lưu trữ được kiểm soát phiên bản mà không làm lộ thông tin bí mật.
• Tách biệt cấu hình toàn hệ thống và cấu hình dự án. Claude Code hỗ trợ cả ~/.claude/config.json (toàn hệ thống) và .claude/config.json (cấp dự án). Các công cụ phát triển cốt lõi áp dụng ở mọi nơi sẽ được đặt ở cấp toàn hệ thống. Các tích hợp dành riêng cho dự án sẽ được đặt ở cấp cục bộ.