Hướng dẫn toàn diện về Agent Skills trong Claude Code

Trong bài viết trước, bạn đã học cách tạo Slash Commands để đóng gói những prompt thường dùng thành các lệnh gọi nhanh. Commands hoạt động tốt cho những tác vụ đơn lẻ mà bạn chủ động kích hoạt bằng cách gõ /command. Tuy nhiên, khi làm việc với những quy trình phức tạp hơn – những thứ đòi hỏi nhiều file hướng dẫn, scripts hỗ trợ, và cần được áp dụng tự động dựa trên ngữ cảnh thì Slash Commands bắt đầu bộc lộ giới hạn.

Agent Skills trong Claude là gì?

Nếu Commands giống như những công cụ đơn lẻ mà bạn chủ động cầm lên sử dụng, thì Skills giống như những bộ kỹ năng hoàn chỉnh mà Claude có thể tự động nhận ra khi nào cần áp dụng. Một Skill không chỉ chứa một prompt đơn thuần, mà là cả một hệ thống bao gồm hướng dẫn chi tiết, tài liệu tham khảo, scripts tự động, và thậm chí cả hooks để kiểm soát hành vi trong quá trình thực thi.

Điểm khác biệt quan trọng nhất giữa Skills và Commands nằm ở cách kích hoạt. Với Commands, bạn phải gõ /command một cách chủ động. Với Skills, Claude đọc description của tất cả Skills có sẵn khi bắt đầu conversation, và tự động quyết định khi nào cần sử dụng Skill nào dựa trên yêu cầu của bạn. Bạn không cần nhớ tên Skill hay gõ lệnh gì cả — chỉ cần mô tả công việc cần làm, và Claude sẽ tự động áp dụng Skill phù hợp nếu có.

Hiểu về cơ chế hoạt động của Skills

Để sử dụng Skills hiệu quả, bạn cần hiểu cách Claude Code xử lý chúng từ lúc khởi động cho đến khi thực thi.

Khi bạn bắt đầu một phiên làm việc với Claude Code, nó sẽ quét các thư mục được quy định để tìm tất cả Skills có sẵn. Với mỗi Skill được tìm thấy, Claude Code đọc phần metadata bao gồm tên và description, và load chúng vào context window. Điều này có nghĩa là Claude “biết” về sự tồn tại của tất cả Skills ngay từ đầu conversation, nhưng nội dung chi tiết của từng Skill chỉ được load khi cần thiết.

Khi bạn gửi một yêu cầu, Claude phân tích nội dung và đối chiếu với descriptions của các Skills. Nếu yêu cầu của bạn khớp với description của một Skill nào đó, Claude sẽ kích hoạt Skill đó bằng cách đọc toàn bộ nội dung hướng dẫn và các file liên quan, sau đó thực hiện công việc theo đúng quy trình được định nghĩa trong Skill.

Skills được lưu trữ ở hai vị trí chính, tương tự như Commands. Thư mục .claude/skills/ trong project chứa các project skills — những Skills đặc thù cho dự án đó và được chia sẻ với team thông qua Git chẳng hạn. Thư mục ~/.claude/skills/ trong home directory chứa các user skills — những Skills cá nhân mà bạn muốn sử dụng xuyên suốt nhiều projects.

Cấu trúc của một Skill

Không giống như Commands chỉ là một file Markdown đơn lẻ, một Skill là một thư mục chứa nhiều files có tổ chức. Điều này cho phép bạn xây dựng những bộ hướng dẫn phức tạp với tài liệu tham khảo, ví dụ, và scripts hỗ trợ.

Cấu trúc cơ bản nhất của một Skill bao gồm một thư mục với ít nhất một file SKILL.md. File này là điểm vào chính — nơi chứa metadata và hướng dẫn cốt lõi của Skill. Tên thư mục chính là tên của Skill. Ví dụ, nếu bạn tạo thư mục .claude/skills/code-review/, thì Skill của bạn sẽ có tên là “code-review”.

Hãy xem xét cấu trúc của một Skill hoàn chỉnh cho việc review code:

.claude/skills/code-review/
├── SKILL.md              # File chính - metadata và hướng dẫn tổng quan
├── SECURITY.md           # Checklist bảo mật chi tiết
├── PERFORMANCE.md        # Hướng dẫn về performance patterns
├── STYLE.md              # Quy tắc coding style
├── examples/
│   ├── good-code.ts      # Ví dụ code tốt
│   └── bad-code.ts       # Ví dụ code cần tránh
└── scripts/
    └── run-linters.sh    # Script chạy linters tự động

Khi Skill được kích hoạt, Claude sẽ đọc SKILL.md trước. Trong file này, bạn có thể hướng dẫn Claude đọc thêm các file khác khi cần. Ví dụ, nếu việc review liên quan đến security, Claude sẽ đọc SECURITY.md để có checklist chi tiết. Cách tổ chức này giúp giữ cho context gọn gàng — Claude chỉ load những gì thực sự cần thiết cho từng tình huống cụ thể.

Viết file SKILL.md

File SKILL.md là trái tim của mọi Skill. Nó bao gồm hai phần chính: phần frontmatter chứa metadata được viết theo định dạng YAML, và phần body chứa nội dung hướng dẫn chi tiết.

Frontmatter được đặt ở đầu file, nằm giữa hai dòng ---. Đây là nơi bạn định nghĩa các thông tin quan trọng mà Claude Code cần để quản lý và kích hoạt Skill đúng cách.

---
name: code-review
description: Comprehensive code review following team standards. Analyzes code for security vulnerabilities, performance issues, and style violations. Use this skill when reviewing pull requests or examining code changes.
---

Hai trường bắt buộc trong frontmatter là name và description. Trường name là identifier của Skill, nên ngắn gọn, dùng chữ viết thường (lowercase) và dấu gạch ngang (-). Trường description cực kỳ quan trọng vì đây chính là thông tin mà Claude dùng để quyết định khi nào kích hoạt Skill. Một description tốt cần trả lời hai câu hỏi: Skill này làm gì? Và khi nào nên sử dụng nó?

Phần body bên dưới frontmatter chứa hướng dẫn chi tiết cho Claude. Đây là nơi bạn mô tả quy trình làm việc, các bước cần thực hiện, và bất kỳ context nào Claude cần biết. Bạn viết bằng Markdown thông thường và có thể tham chiếu đến các file khác trong cùng thư mục Skill.

Dưới đây là ví dụ đầy đủ về file SKILL.md cho một Skill review code viết bằng tiếng Việt:

---
name: code-review
description: Comprehensive code review following team standards. Analyzes security, performance, and code style. Automatically triggered when user asks to review code, check pull requests, or examine code changes.
---
# Code Review Skill
Bạn là một senior developer đang thực hiện code review. Hãy tiếp cận việc review một cách systematic và constructive.
## Quy trình Review
Khi nhận được yêu cầu review code, hãy thực hiện theo thứ tự sau:
### 1. Hiểu Context
Trước tiên, hãy hiểu mục đích của code changes. Nếu chưa rõ, hãy hỏi người dùng về:
- Mục tiêu của thay đổi này là gì?
- Có requirements hoặc constraints đặc biệt nào không?
### 2. Security Review
Đọc file SECURITY.md trong thư mục này để có checklist bảo mật chi tiết. Kiểm tra các issues phổ biến như injection, authentication bypass, và data exposure.
### 3. Performance Review
Tham khảo PERFORMANCE.md để đánh giá:
- Độ phức tạp thuật toán
- Database queries hiệu quả
- Memory management
### 4. Style và Maintainability
Dựa trên STYLE.md, kiểm tra:
- Naming conventions
- Code organization
- Documentation đầy đủ
## Output Format
Trình bày kết quả review theo cấu trúc:
1. **Summary**: Tổng quan ngắn gọn về code quality
2. **Critical Issues**: Những vấn đề cần fix ngay (blocking)
3. **Suggestions**: Những cải thiện nên làm (non-blocking)
4. **Positives**: Những điểm tốt đáng khen (quan trọng cho morale)
Hãy constructive và specific. Thay vì nói "code này không tốt", hãy giải thích tại sao và đề xuất cách cải thiện cụ thể.

Các trường frontmatter nâng cao

Ngoài name và description, Claude Code hỗ trợ nhiều trường frontmatter khác giúp bạn kiểm soát hành vi của Skill một cách tinh vi hơn.

Trường tools cho phép bạn giới hạn những tools mà Skill được phép sử dụng. Mặc định, một Skill có quyền truy cập tất cả tools mà Claude Code có. Tuy nhiên, trong một số trường hợp, bạn muốn giới hạn để đảm bảo an toàn. Ví dụ, một Skill chỉ dành cho việc phân tích code có thể được giới hạn chỉ dùng tools read-only:

---
name: code-analyzer
description: Analyzes code structure and patterns without making changes
tools: Read, Grep, Glob
---

Trường user-invocable kiểm soát việc Skill có xuất hiện trong menu slash commands hay không. Mặc định, Skills từ thư mục /skills/ sẽ hiển thị trong menu / để người dùng có thể gọi trực tiếp. Nếu bạn muốn một Skill chỉ được Claude tự động kích hoạt mà không cho phép gọi manual, hãy đặt giá trị này thành false:

---
name: internal-standards
description: Apply internal coding standards during development
user-invocable: false
---

Trường disable-model-invocation ngăn Claude tự động kích hoạt Skill. Điều này nghe có vẻ mâu thuẫn với mục đích của Skills, nhưng hữu ích khi bạn muốn một Skill chỉ được gọi khi người dùng chủ động yêu cầu. Đặt thành true nếu bạn muốn Skill hoạt động giống như một Command — chỉ kích hoạt khi được gọi explicit:

---
name: dangerous-operation
description: Performs potentially destructive operations
disable-model-invocation: true
---

Tham chiếu giữa các files trong Skill

Một trong những điểm mạnh của Skills là khả năng tổ chức thông tin thành nhiều files và tham chiếu giữa chúng một cách có tổ chức. Thay vì nhồi nhét mọi thứ vào một file dài, bạn có thể phân tách thành các modules chuyên biệt.

Trong file SKILL.md, bạn có thể hướng dẫn Claude đọc các file khác khi cần. Cách đơn giản nhất là mention trực tiếp trong hướng dẫn. Ví dụ, bạn có thể viết: “Khi review về security, hãy đọc và áp dụng checklist từ file SECURITY.md trong thư mục này.” Claude sẽ hiểu và tự động đọc file đó khi cần thiết.

Một pattern phổ biến là tạo các file chuyên biệt cho từng khía cạnh của quy trình. Trong ví dụ về code review skill, bạn có thể có:

File SECURITY.md chứa checklist bảo mật chi tiết:

# Security Checklist
## Input Validation
- [ ] Tất cả user inputs được validate
- [ ] Sử dụng parameterized queries cho database
- [ ] Escape output khi render HTML
## Authentication & Authorization
- [ ] Kiểm tra authentication ở mọi protected endpoints
- [ ] Verify authorization cho mỗi action
- [ ] Session management an toàn
## Data Protection
- [ ] Sensitive data được encrypt
- [ ] Không log sensitive information
- [ ] Secure headers được set đúng

File PERFORMANCE.md chứa hướng dẫn về performance:

# Performance Guidelines
## Database Queries
- Tránh N+1 queries — sử dụng eager loading khi cần
- Index cho các columns thường xuyên query
- Limit và paginate kết quả lớn
## Caching Strategy
- Cache expensive computations
- Sử dụng appropriate TTL
- Invalidate cache đúng cách khi data thay đổi
## Code Patterns
- Lazy loading cho heavy resources
- Avoid blocking operations trong main thread
- Sử dụng connection pooling

Khi Claude thực hiện review, nó sẽ đọc SKILL.md trước để hiểu quy trình tổng thể, sau đó đọc các file chuyên biệt khi đi vào từng khía cạnh cụ thể. Cách này giữ cho context được kiểm soát và có tổ chức.

Hooks trong Skills

Hooks là một tính năng nâng cao cho phép bạn chạy các shell commands tự động tại những thời điểm cụ thể trong lifecycle của Skill. Nếu bạn muốn đảm bảo một số hành động luôn xảy ra khi Skill được sử dụng – thay vì phụ thuộc vào việc Claude “nhớ” làm điều đó — hooks là giải pháp.

Hooks được định nghĩa trong frontmatter của SKILL.md và hỗ trợ ba events chính: PreToolUse chạy trước khi Claude sử dụng một tool, PostToolUse chạy sau khi tool hoàn thành, và Stop chạy khi Skill kết thúc.

Một use case phổ biến là tự động chạy linter sau mỗi lần Claude edit file:

---
name: code-editor
description: Edit code with automatic linting and formatting
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "npm run lint:fix"
---

Trong ví dụ trên, mỗi khi Claude sử dụng tool Edit hoặc Write (match bằng regex), hook sẽ tự động chạy npm run lint:fix. Điều này đảm bảo code luôn được format đúng chuẩn mà không cần Claude phải nhớ chạy linter.

Một ví dụ khác là chạy security check trước khi thực thi các bash commands:

---
name: secure-operations
description: Perform operations with security validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

Option once: true đảm bảo hook chỉ chạy một lần trong session, hữu ích khi bạn không muốn security check lặp lại cho mỗi command.

Kiểm tra và debug Skills

Sau khi tạo một Skill, bạn sẽ muốn verify rằng nó được load đúng cách và Claude có thể sử dụng nó. Claude Code cung cấp một số cách để kiểm tra.

Cách đơn giản nhất là hỏi Claude trực tiếp: “What Skills are available?” hoặc “Những Skills nào đang có sẵn?“. Claude sẽ liệt kê tất cả Skills mà nó có access, bao gồm tên và description. Nếu Skill của bạn không xuất hiện trong danh sách, có thể có vấn đề với cấu trúc thư mục hoặc syntax của frontmatter.

Để xem chi tiết hơn về những gì đang được load, bạn có thể sử dụng command /context. Command này hiển thị breakdown của context window, bao gồm cả phần dành cho Skills. Bạn sẽ thấy có bao nhiêu tokens được sử dụng cho metadata của Skills.

Nếu muốn debug sâu hơn, chạy Claude Code với flag --debug:

claude --debug

Mode này sẽ hiển thị thông tin chi tiết về quá trình load Skills, bao gồm cả những lỗi nếu có. Đây là cách tốt nhất để troubleshoot khi Skill không hoạt động như mong đợi.

Để test một Skill cụ thể, bạn có hai cách. Cách thứ nhất là gọi trực tiếp bằng slash command nếu Skill có user-invocable: true (mặc định). Cách thứ hai là đưa ra một yêu cầu mà bạn chắc chắn sẽ trigger Skill đó. Ví dụ, nếu Skill có description “Reviews pull requests for code quality”, hãy nói với Claude “Review the changes in my current branch” và xem Claude có tự động áp dụng Skill không.

Viết description hiệu quả

Description là yếu tố quan trọng nhất quyết định liệu Claude có sử dụng Skill của bạn đúng lúc hay không. Một description mơ hồ như “Helps with documents” không cung cấp đủ thông tin để Claude match với requests cụ thể. Ngược lại, một description quá hẹp có thể khiến Skill không được trigger trong những tình huống phù hợp.

Một description tốt nên bao gồm ba thành phần. Thứ nhất là what – Skill này làm gì một cách cụ thể. Thứ hai là when – những tình huống nào nên trigger Skill này. Thứ ba là keywords – những từ khóa mà người dùng có thể sử dụng khi cần Skill này.

Hãy so sánh hai descriptions cho cùng một Skill:

Description kém:

description: Helps with code review

Description tốt:

description: Comprehensive code review analyzing security vulnerabilities, performance bottlenecks, and style violations. Automatically applies team coding standards. Trigger when user asks to review code, check pull requests, examine changes, or audit code quality.

Description thứ hai cung cấp đủ context để Claude biết chính xác khi nào nên sử dụng Skill. Nó liệt kê các khía cạnh cụ thể (security, performance, style), mention output (team coding standards), và cung cấp các trigger phrases phổ biến.

Skills vs Commands: Khi nào dùng cái nào?

Một câu hỏi phổ biến là khi nào nên tạo Skill và khi nào Command là đủ. Dưới đây là một số guidelines để giúp bạn quyết định.

Hãy sử dụng Commands khi bạn có một prompt đơn giản mà bạn muốn gọi chủ động với một lệnh cụ thể. Commands phù hợp cho những tác vụ mà bạn biết chính xác khi nào cần thực hiện và muốn control explicit việc kích hoạt. Ví dụ: /commit để tạo commit message, /explain để giải thích đoạn code.

Hãy sử dụng Skills khi bạn có một quy trình phức tạp cần nhiều files hướng dẫn, hoặc khi bạn muốn Claude tự động áp dụng mà không cần bạn phải nhớ gọi. Skills cũng phù hợp khi bạn cần hooks để đảm bảo một số hành động luôn xảy ra, hoặc khi bạn muốn giới hạn tools mà Claude có thể sử dụng trong một context cụ thể.

Một pattern hữu ích là bắt đầu với Command cho một workflow mới. Khi bạn thấy workflow đó trở nên phức tạp hơn – cần thêm tài liệu tham khảo, cần tự động hóa một số bước, hoặc bạn muốn Claude tự động áp dụng – đó là lúc chuyển đổi thành Skill.

Cả Commands và Skills có thể cùng tồn tại và bổ sung cho nhau. Bạn có thể có một Command /quick-review cho việc review nhanh những thay đổi nhỏ, và một Skill “comprehensive-review” tự động kích hoạt khi Claude nhận ra cần review sâu hơn.

Chia sẻ Skills với team

Một trong những giá trị lớn nhất của Skills là khả năng chia sẻ và chuẩn hóa workflow trong team. Khi bạn đặt Skills trong thư mục .claude/skills/ và commit vào version control, mọi thành viên trong team sẽ tự động có access đến những Skills đó khi họ clone hoặc pull repository.

Điều này tạo ra sự nhất quán đáng kể. Thay vì mỗi người có cách review code riêng, cả team sử dụng cùng một Skill với cùng một quy trình và checklist. Khi standards thay đổi, bạn chỉ cần cập nhật Skill và mọi người sẽ có phiên bản mới khi pull code.

Khi chia sẻ Skills, hãy cân nhắc thêm README trong thư mục .claude/skills/ để giải thích cho team members mới về những Skills có sẵn và cách sử dụng chúng. Bạn cũng nên document trong CLAUDE.md của project về những conventions và workflows mà Skills enforce.

Một số ví dụ Skills thực tế

Để giúp bạn hình dung rõ hơn về cách áp dụng Skills trong thực tế, dưới đây là một số ví dụ từ những use cases phổ biến.

Skill cho việc tạo API endpoints:

---
name: api-builder
description: Creates RESTful API endpoints following team conventions. Includes validation, error handling, and documentation. Trigger when user asks to create endpoint, add API, or build route.
tools: Read, Write, Edit, Bash
---
# API Builder Skill
Khi tạo API endpoint mới, hãy tuân theo quy trình sau:
## 1. Gather Requirements
Hỏi user về:
- HTTP method và path
- Request body schema (nếu có)
- Response format mong muốn
- Authentication requirements
## 2. Implementation
Tạo endpoint với structure:
- Input validation sử dụng Zod/Joi
- Error handling với appropriate status codes
- Response formatting nhất quán
Tham khảo file CONVENTIONS.md để biết chi tiết về naming và structure.
## 3. Documentation
Tự động tạo OpenAPI/Swagger documentation cho endpoint mới.
## 4. Testing
Tạo test cases cơ bản covering:
- Happy path
- Validation errors
- Authentication failures

Skill cho database migrations:

---
name: db-migration
description: Creates and manages database migrations safely. Includes rollback planning and data integrity checks. Use when adding tables, modifying schemas, or changing database structure.
tools: Read, Write, Edit, Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/check-migration-safety.sh"
---
# Database Migration Skill
## Safety First
Trước khi tạo migration, luôn verify:
- Có rollback plan không?
- Migration có thể chạy trong production với zero downtime không?
- Data integrity được đảm bảo không?
## Migration Checklist
Đọc file MIGRATION_CHECKLIST.md để có danh sách đầy đủ các items cần kiểm tra.
## Naming Convention
Migration files: `YYYYMMDD_HHMMSS_description.sql`
Ví dụ: `20240115_143022_add_users_email_index.sql`

Những lưu ý quan trọng

Qua quá trình sử dụng Skills, có một số điểm bạn nên ghi nhớ để tránh những vấn đề phổ biến.

Đầu tiên, hãy cẩn thận với việc load quá nhiều thông tin vào context. Mặc dù Skills cho phép bạn tổ chức nhiều files, điều đó không có nghĩa là bạn nên nhồi nhét mọi thứ. Mỗi file được đọc sẽ chiếm tokens trong context window. Hãy thiết kế Skills sao cho Claude chỉ đọc những gì thực sự cần thiết cho từng tình huống cụ thể.

Thứ hai, description quá rộng có thể gây ra false positives — Claude kích hoạt Skill trong những tình huống không phù hợp. Ngược lại, description quá hẹp có thể khiến Skill không bao giờ được trigger. Hãy test kỹ với nhiều scenarios khác nhau để tìm điểm cân bằng.

Thứ ba, hooks chạy với quyền của user hiện tại và có thể thực thi bất kỳ shell command nào. Điều này rất powerful nhưng cũng tiềm ẩn rủi ro. Hãy review kỹ các hooks trước khi sử dụng, đặc biệt là khi nhận Skills từ nguồn bên ngoài.

Cuối cùng, Skills được load khi session bắt đầu. Nếu bạn thêm hoặc sửa Skill trong khi đang có session, bạn cần restart Claude Code để changes có hiệu lực.

Lời kết

Agent Skills là bước tiến lớn từ Slash Commands, cho phép bạn xây dựng những bộ hướng dẫn phức tạp mà Claude có thể tự động áp dụng dựa trên ngữ cảnh. Với khả năng tổ chức nhiều files, định nghĩa hooks, và giới hạn tools, Skills mở ra khả năng tùy biến Claude Code theo đúng workflow của bạn và team.

Tuy nhiên, cả Commands và Skills đều có một giới hạn chung: chúng chạy trong cùng context window với conversation chính. Khi bạn cần thực hiện những tác vụ phức tạp mà output có thể rất dài, hoặc cần isolation hoàn toàn để tránh “ô nhiễm” context chính, thì bạn cần một công cụ mạnh mẽ hơn.

Đó là lý do bài viết tiếp theo trong series sẽ giới thiệu về Subagents — những AI assistants chuyên biệt chạy trong context riêng biệt, có thể được delegate các tác vụ phức tạp và trả về kết quả mà không làm đầy conversation chính của bạn. Subagents là mảnh ghép cuối cùng trong bộ ba công cụ customization của Claude Code.