Introduction to Agent Skills

#Skill là gì

Skill là folder chứa chỉ dẫn và resource mà Claude Code có thể discover (khám phá) rồi dùng để xử lý tác vụ chính xác hơn. Mỗi skill sống trong một file SKILL.md, có name và description trong frontmatter:

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

Dưới frontmatter là chỉ dẫn thật: checklist review, format ưa dùng, hoặc bất cứ gì Claude cần biết cho tác vụ đó.

#Description quyết định skill có được dùng

description là cách Claude quyết định có dùng skill hay không — không phải mô tả suông cho người đọc. Khi người dùng nhờ review một PR, Claude đọc yêu cầu, so với description của mọi skill khả dụng, rồi activate những cái khớp.

Nói cách khác: description là cơ chế routing. Skill không được gọi như mong đợi → chỗ cần sửa đầu tiên chính là nó.

#Skill lưu ở đâu

Tuỳ ai cần dùng:

Trên Windows, personal skill nằm ở C:/Users/<user>/.claude/skills.

Project skill được commit vào version control cùng code, nên cả team dùng chung.

#Skill vs CLAUDE.md vs Slash command

Claude Code có nhiều cách tuỳ biến hành vi. Skill đặc biệt ở chỗ nó tự động và gắn với tác vụ:

Chi tiết quan trọng: ban đầu Claude chỉ nạp name và description, không nạp cả nội dung skill → skill không lấp đầy context window. Khớp rồi mới nạp phần thân. Khi một skill được match, có thể thấy nó load ngay trên terminal.

#Tạo một skill từ đầu

Ví dụ: một personal skill dạy Claude viết PR description theo format nhất quán. Vì là personal skill, nó nằm ở home directory và dùng được ở mọi project.

Bước 1 — tạo directory trong thư mục skills. Tên directory khớp tên skill:

mkdir -p ~/.claude/skills/pr-description

Bước 2 — tạo file SKILL.md bên trong directory đó. File gồm hai phần, ngăn nhau bởi dấu gạch frontmatter:

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

• name — định danh skill.
• description — nói cho Claude biết khi nào dùng skill; đây chính là matching criteria.
• Mọi thứ sau dấu gạch thứ hai — chỉ dẫn Claude làm theo khi skill được activate.

#Test skill

Claude Code nạp skill lúc startup, nên phải restart session sau khi tạo. Kiểm tra bằng cách xem danh sách skill khả dụng — skill mới phải có trong đó.

Test thật: sửa vài chỗ trên một branch rồi nói "write a PR description for my changes". Claude sẽ báo là đang dùng pr-description skill, chạy git diff và viết description đúng template — mỗi lần đều giống nhau.

#Cơ chế matching hoạt động ra sao

Bốn bước:

Việc khớp là semantic matching — khớp theo ý định (intent), không phải theo từ khoá. Ví dụ "explain what this function does" vẫn khớp một skill mô tả là "explain code with visual diagrams" vì intent trùng nhau.

Bước confirmation ở (3) giữ cho người dùng biết context nào đang được kéo vào — skill không tự nạp nội dung một cách im lặng.

#Skill priority

Clone một repo có skill trùng tên với skill cá nhân thì cái nào thắng? Có thứ tự rõ ràng, cao → thấp:

Thứ tự này cho phép tổ chức ép chuẩn qua enterprise skill mà vẫn để cá nhân tuỳ biến. Ví dụ: công ty có enterprise skill code-review, mình tự tạo personal skill cũng tên code-review → bản enterprise thắng.

Cách tránh xung đột: đặt tên mô tả rõ. Đừng đặt review, hãy frontend-review hoặc backend-review.

#Bộ field metadata đầy đủ

Agent skills open standard hỗ trợ bốn field trong frontmatter của SKILL.md — hai bắt buộc, hai tuỳ chọn:

#Viết description hiệu quả

Hãy explicit với chỉ dẫn. Nếu ai đó bảo ta "việc của bạn là giúp về docs" thì ta không biết phải làm gì — Claude nghĩ y hệt như vậy.

Một description tốt trả lời đúng hai câu hỏi:

1. Skill này làm gì?
2. Khi nào Claude nên dùng nó?

Skill không trigger như mong đợi → thêm keyword khớp với cách ta thật sự diễn đạt yêu cầu. Description chính là thứ Claude dùng để quyết định skill có liên quan hay không, nên ngôn ngữ trong đó rất quan trọng.

#Giới hạn tool bằng allowed-tools

Đôi khi ta muốn một skill chỉ đọc file, không sửa — hợp với security-sensitive workflow, tác vụ read-only, hoặc bất cứ tình huống nào cần guardrail.

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Ở ví dụ này allowed-tools là Read, Grep, Glob, Bash: khi skill active, Claude chỉ dùng được đúng các tool đó mà không cần hỏi permission — không edit, không write.

⚠️ Bỏ hẳn allowed-tools = KHÔNG giới hạn gì. Claude dùng permission model bình thường của nó. Không khai báo không đồng nghĩa với cấm hết tool.

#Progressive disclosure

Skill dùng chung context window với hội thoại. Khi Claude activate một skill, toàn bộ nội dung SKILL.md được nạp vào context. Nhưng đôi khi skill cần reference, ví dụ, hoặc utility script đi kèm.

Nhồi hết vào một file 2.000 dòng có hai vấn đề: chiếm nhiều context window, và maintain rất khổ.

Progressive disclosure giải quyết: giữ chỉ dẫn cốt lõi trong SKILL.md, đẩy tài liệu chi tiết sang file riêng mà Claude chỉ đọc khi cần.

Open standard gợi ý cấu trúc skill directory:

Trong SKILL.md, link tới file phụ kèm chỉ dẫn rõ ràng về khi nào nạp chúng. Ví dụ: Claude chỉ đọc architecture-guide.md khi có người hỏi về system design; nếu chỉ hỏi "thêm component vào đâu" thì file đó không bao giờ được nạp. Giống như có mục lục trong context window thay vì cả cuốn sách.

Rule of thumb: giữ SKILL.md dưới 500 dòng. Vượt ngưỡng đó → cân nhắc tách nội dung sang reference file riêng.

#Dùng script hiệu quả

Script trong skill directory chạy được mà không cần nạp nội dung vào context: script thực thi, và chỉ output tốn token.

Chỉ dẫn then chốt phải viết trong SKILL.md: bảo Claude CHẠY script, đừng ĐỌC nó.

Đặc biệt hữu ích cho:

• Environment validation
• Data transformation cần nhất quán
• Thao tác đáng tin cậy hơn khi là code đã test thay vì code sinh ra tại chỗ

#Chọn đúng cơ chế: skill vs CLAUDE.md, subagent, hook, MCP

Claude Code có nhiều cơ chế tuỳ biến — Skills, CLAUDE.md, subagents, hooks, MCP servers. Chúng giải những bài toán khác nhau, và chọn sai dẫn tới phức tạp hoá vô ích.

#CLAUDE.md vs Skills — luôn bật vs theo yêu cầu

CLAUDE.md nạp vào mọi hội thoại, luôn luôn. Skill nạp on demand: khớp yêu cầu thì chỉ dẫn của nó nhập vào hội thoại.

#Skills vs Subagents — context hiện tại vs context tách biệt

Skill thêm kiến thức vào hội thoại hiện tại: activate thì chỉ dẫn của nó nhập vào context đang có. Subagent chạy ở context riêng: nhận task, làm việc độc lập, trả kết quả về — cách ly khỏi hội thoại chính.

#Skills vs Hooks — event-driven vs request-driven

Hook kích hoạt theo sự kiện: chạy linter mỗi lần Claude save file, validate input trước một số tool call. Skill kích hoạt theo điều người dùng đang hỏi.

#MCP servers

Cung cấp tool và integration bên ngoài — một phạm trù hoàn toàn khác với skill.

#Ghép tất cả lại

Một setup điển hình:

Mỗi cái lo đúng chuyên môn của nó. Đừng ép mọi thứ vào skill khi cơ chế khác hợp hơn — và hoàn toàn có thể dùng nhiều cái cùng lúc.

Dùng skill khi có kiến thức mà Claude nên tự động áp dụng lúc chủ đề trở nên liên quan, rồi kết hợp với các cơ chế còn lại để tuỳ biến toàn diện.

#Chia sẻ skill: ba cách phân phối

Skill có giá trị hơn hẳn khi được chia sẻ. Một PR review skill chỉ mình dùng thì hữu ích; cùng skill đó chia cho cả team thì nó chuẩn hoá code review và tạo trải nghiệm nhất quán cho cả tổ chức.

#1. Commit vào repository

Cách đơn giản nhất: đặt skill ở .claude/skills → ai clone repo là có ngay, không cần cài gì thêm. Push update → mọi người nhận ở lần pull kế tiếp.

Hợp với:

• Team coding standard
• Project-specific workflow
• Skill tham chiếu cấu trúc codebase

Thư mục .claude chứa agents, hooks, skills và settings — tất cả version-controlled và chia sẻ với team qua Git workflow bình thường.

#2. Phân phối qua plugin

Plugin là cách mở rộng Claude Code bằng chức năng tuỳ biến, thiết kế để chia sẻ xuyên team và project. Trong plugin project, tạo thư mục skills theo cấu trúc giống .claude: mỗi skill một folder riêng, bên trong có SKILL.md.

Phát hành plugin lên marketplace → người khác discover và install vào Claude Code của họ.

Hợp khi skill không quá project-specific và hữu ích cho cộng đồng ngoài team trực tiếp.

#3. Enterprise deployment qua managed settings

Administrator deploy skill toàn tổ chức qua managed settings. Enterprise skill có ưu tiên cao nhất — đè personal, project và plugin skill cùng tên.

Managed settings hỗ trợ strictKnownMarketplaces để kiểm soát plugin được cài từ đâu:

"strictKnownMarketplaces": [
  {
    "source": "github",
    "repo": "acme-corp/approved-plugins"
  },
  {
    "source": "npm",
    "package": "@acme-corp/compliance-plugins"
  }
]

Đây là lựa chọn đúng cho mandatory standard, security requirement, compliance workflow, và coding practice phải nhất quán toàn tổ chức. Từ khoá ở đây là "must".

#Skill và Subagent

Điều làm nhiều người bất ngờ: subagent KHÔNG tự thấy skill của bạn. Delegate một task cho subagent = nó khởi đầu với context sạch tinh.

Ba phân biệt cần nắm:

⚠️ Lưu ý về danh sách built-in agent: bài này liệt kê Explorer, Plan, Verify, trong khi khoá Introduction to Subagents nói General purpose, Explore, Plan — bộ built-in agent thay đổi theo version của Claude Code. Thứ không đổi và đáng thuộc: built-in agent không dùng được skill; chỉ custom subagent trong .claude/agents mới dùng được.

Cách tạo custom subagent có skill: thêm file agent markdown vào .claude/agents (có thể dùng lệnh /agents để tạo tương tác). File agent sinh ra có field skills liệt kê skill cần nạp:

---
name: frontend-security-accessibility-reviewer
description: "Use this agent when you need to review frontend code for accessibility..."
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
model: sonnet
color: blue
skills: accessibility-audit, performance-check
---

Delegate cho subagent này → nó có sẵn cả hai skill và áp dụng cho mọi lần review.

Thứ tự làm: đảm bảo skill đã tồn tại trong .claude/skills trước, rồi mới tạo subagent mới hoặc thêm field skills vào file agent có sẵn.

Pattern này chạy rất tốt khi:

• Muốn delegate cách ly nhưng vẫn có expertise cụ thể
• Subagent khác nhau cần skill khác nhau (frontend reviewer vs backend reviewer)
• Muốn ép chuẩn trong việc được delegate mà không phải dựa vào prompt

#Troubleshooting

Skill hỏng thì gần như luôn rơi vào vài nhóm đoán trước được: không trigger, không load, xung đột, hoặc fail lúc chạy. Tin tốt: hầu hết cách sửa đều đơn giản.

#Bắt đầu bằng skills validator

Việc đầu tiên nên thử là lệnh agent skills verifier. Cách cài tuỳ hệ điều hành, nhưng dùng uv là cách nhanh nhất. Cài xong thì vào thư mục skill hoặc chạy từ bất cứ đâu.

Validator bắt các vấn đề cấu trúc trước khi ta tốn thời gian debug thứ khác.

#Skill không trigger

Skill tồn tại, pass validation, nhưng Claude không dùng khi ta mong đợi. Nguyên nhân gần như luôn là description.

Claude dùng semantic matching, nên yêu cầu phải chồng lấn về nghĩa với description. Không đủ chồng lấn = không khớp. Cách xử lý:

• Đối chiếu description với cách ta thật sự diễn đạt yêu cầu
• Thêm trigger phrase mà người dùng thật sự nói
• Test bằng nhiều biến thể: "help me profile this" · "why is this slow?" · "make this faster"
• Biến thể nào không trigger → thêm chính keyword đó vào description

#Skill không load

Hỏi Claude "what skills are available" mà không thấy skill của mình → kiểm tra hai yêu cầu cấu trúc:

• File SKILL.md phải nằm TRONG một directory có tên — không để ở root của thư mục skills.
• Tên file phải đúng chính xác SKILL.md — SKILL viết hoa hết, md viết thường.

Chạy claude --debug để xem lỗi loading; tìm dòng có nhắc tên skill của mình. Nhiều khi chỉ vậy là ra ngay vấn đề.

#Dùng nhầm skill

Claude dùng sai skill hoặc lẫn lộn giữa các skill → description quá giống nhau. Làm chúng khác biệt hẳn.

Viết description càng cụ thể càng tốt không chỉ giúp Claude biết khi nào dùng skill, mà còn ngăn xung đột với những skill nghe na ná.

#Xung đột priority

Personal skill bị phớt lờ → có thể một enterprise skill (hoặc skill ưu tiên cao hơn) đang trùng tên. Ví dụ: công ty có enterprise skill code-review, ta cũng có personal skill code-review → bản enterprise thắng mọi lần.

Hai lựa chọn:

1. Đổi tên skill của mình thành cái khác biệt hơn — thường là đường dễ hơn.
2. Trao đổi với admin về enterprise skill đó.

#Skill của plugin không xuất hiện

Clear cache → restart Claude Code → reinstall.

Vẫn không thấy → cấu trúc plugin có thể sai. Đây chính là lúc validator tool phát huy giá trị.

#Runtime error

Skill load được nhưng fail lúc thực thi. Vài nguyên nhân thường gặp:

• Missing dependency — skill dùng package ngoài thì package phải được cài. Thêm thông tin dependency vào description của skill để Claude biết cần những gì.
• Permission issue — script cần quyền thực thi: chạy chmod +x lên mọi script mà skill tham chiếu.
• Path separator — dùng forward slash ở mọi nơi, kể cả trên Windows.

#Checklist nhanh

#Khi nào dùng skill

Skill hợp nhất với kiến thức chuyên biệt áp dụng cho tác vụ cụ thể:

• Code review standard của team
• Commit message format ưa dùng
• Brand guideline của tổ chức
• Documentation template cho từng loại tài liệu
• Debugging checklist cho một framework cụ thể

Rule of thumb gọn trong một câu: nếu thấy mình giải thích cùng một thứ cho Claude nhiều lần, đó là một skill đang chờ được viết.

#Áp dụng thực tế

Ba cơ chế này ánh xạ khá sạch sang cách một team thật vận hành. CLAUDE.md là nội quy dán ở cửa — ai vào cũng đọc, mọi lúc; nên nó phải ngắn, vì dán nhiều quá thì hết tường. Slash command là gọi tên rồi ra lệnh — không gọi thì không có gì xảy ra. Skill là cẩm nang trong tủ hồ sơ: ngoài gáy sách ghi "Quy trình review PR — dùng khi review PR hoặc kiểm tra thay đổi code", và người ta chỉ liếc gáy sách, đến lúc cần mới rút đúng cuốn ra đọc.

Hệ quả của việc "chỉ liếc gáy sách" là chỗ tôi thấy đáng nhớ nhất: gáy sách viết mơ hồ thì cuốn cẩm nang hay tới đâu cũng nằm im trong tủ. Đây đúng bằng bài học description ở subagent — Anthropic lặp lại cùng một pattern: thứ quyết định cái gì được kích hoạt luôn là dòng metadata, không phải phần nội dung. Nên khi skill không chạy, đừng viết lại chỉ dẫn cho hay hơn; sửa description trước.

Ranh giới personal vs project thì tôi đọc thẳng là ranh giới sở hữu: cái gì là khẩu vị cá nhân (tôi thích commit message viết thế nào) thì ở ~/.claude/skills — không ai phải chịu; cái gì là chuẩn chung cả team phải giống nhau thì ở .claude/skills và đi vào git như code. Chuẩn team mà nằm trong máy từng người thì mỗi người review một kiểu — vẫn là bài toán cũ, chỉ đổi chỗ chứa.

Nhưng priority order thì phá đúng cái ranh giới vừa vẽ — và đây là chỗ tôi thấy phải nhớ kỹ nhất bài này: Personal thắng Project. Trực giác nói "cụ thể hơn thì thắng", nên ta dễ mặc định project skill đè personal skill. Không phải. Nghĩa là: chuẩn team đặt trong repo KHÔNG bảo vệ được khỏi khẩu vị cá nhân — một dev có personal skill trùng tên là im lặng dùng bản của họ, repo không hay biết. Ở góc quản lý delivery, đây không phải bug mà là tuyên bố về ai được quyền ép: chỉ Enterprise (managed settings) mới ép được thật; project chỉ đề nghị. Nếu một chuẩn thực sự bắt buộc cho cả team thì nó phải lên enterprise, hoặc phải được gác bằng thứ chạy trong CI chứ không phải bằng file nằm trong repo. Và mẹo phòng thủ rẻ nhất mà bài đưa ra vẫn đúng: đặt tên đủ đặc thù (frontend-review thay vì review) để hai bên đơn giản là không đụng nhau.

Chi tiết nạp lúc startup thì nhỏ nhưng cắn thật: sửa skill xong mà quên restart, ta sẽ ngồi debug một description hoàn toàn không có lỗi. Và bước confirmation trước khi nạp là thứ tôi đánh giá cao hơn vẻ ngoài của nó — nó biến việc "context bị kéo vào" từ ngầm thành có người ký: đúng nguyên tắc mọi thứ ảnh hưởng đầu ra đều phải nhìn thấy được.

Progressive disclosure thì tôi thấy đúng bằng cách viết một bộ tài liệu dự án tử tế. Không ai đưa người mới cuốn 2.000 trang rồi bảo "đọc đi"; ta đưa một trang onboarding mỏng có mục lục, và ghi rõ "cần hiểu kiến trúc thì mở phụ lục A". Chỗ tinh tế nằm ở "kèm chỉ dẫn khi nào nạp": link không thôi là chưa đủ — phải nói điều kiện để Claude biết lúc nào không cần mở. Ngưỡng 500 dòng vì thế không phải luật thẩm mỹ, nó là ngưỡng cảnh báo rằng ta đang trả tiền context cho thứ 90% lần dùng không đọc tới.

Nhưng phần đắt nhất bài này là script: RUN, đừng READ. Nó tách bạch hai thứ mà ta hay gộp: kiến thức (Claude cần đọc để hiểu) và công cụ (Claude chỉ cần bấm để lấy kết quả). Với công cụ, việc bắt Claude đọc code là trả token để nó suy luận lại một thứ đã đúng sẵn. Lý do thứ hai còn quan trọng hơn tiền: bài nói script hợp với thao tác "đáng tin hơn khi là code đã test" — nghĩa là cùng input thì cùng output, mỗi lần chạy đều thế. Code Claude sinh ra tại chỗ thì mỗi lần một dị bản, và với data transformation thì "gần đúng nhưng khác nhau mỗi lần" là thứ tệ nhất có thể xảy ra. Ở góc delivery, đây chính là nguyên tắc quen: cái gì cần lặp lại giống hệt thì đóng thành script/checklist và ép chạy — đừng để mỗi lần một người làm một kiểu, kể cả khi "người" đó là AI.

allowed-tools thì tôi lưu ý cái bẫy ngược: bỏ trống không phải là "cấm hết", mà là "theo quy định chung". Nên nó là guardrail chủ động — muốn read-only thì phải nói ra, im lặng không cho ta sự an toàn nào. Và đây là chỗ skill giao đúng với bài tools của subagent: cấp quyền theo vai trò, một codebase-onboarding skill thì Read, Grep, Glob, Bash là đủ, mở thêm Write chỉ là mở cửa cho tai nạn.

Đến bài so sánh thì cả năm cơ chế xếp gọn được vào một câu tôi dùng để chọn: skill đổi Claude biết gì; subagent đổi ai làm và làm ở đâu; hook đổi cái gì tự chạy khi có sự kiện; MCP đổi Claude chạm được tới đâu; CLAUDE.md đổi luật nền luôn đúng. Năm câu hỏi khác nhau, nên "cái nào tốt hơn" là câu hỏi sai — bài nói thẳng: đừng ép mọi thứ vào skill, và dùng nhiều cái một lúc là chuyện bình thường.

Chỗ tôi thấy dễ chọn sai nhất là skill vs subagent, vì cả hai đều "đóng gói một vai trò" và đều có field giới hạn tool. Phân biệt bằng context: skill đọc tại bàn của mình — kiến thức nhập thẳng vào hội thoại đang chạy, ta vẫn nhìn thấy mọi thứ; subagent là cử người sang phòng khác làm — bàn riêng, quyền riêng, và chỉ tờ tóm tắt quay về. Nên khi bài liệt kê "cần tool access khác main conversation" là lý do chọn subagent, đừng nhầm với allowed-tools của skill: allowed-tools siết tool của chính hội thoại hiện tại, không tạo ra một không gian quyền hạn thứ hai.

Cặp hook vs skill thì tôi nhớ bằng ai là người bấm nút. Hook: sự việc bấm — file được save, tool sắp chạy; nó xảy ra dù ta có nói gì hay không, nên mọi thứ bắt buộc phải chạy (lint, validate) đều thuộc về hook. Skill: lời ta nói bấm — nó chỉ tham gia khi yêu cầu khớp description. Hệ quả thực dụng cho team: một chuẩn code mà ta thật sự muốn ép thì viết skill là chọn nhầm cơ chế — skill có thể không được kích hoạt, còn hook thì không có cửa trốn. Đây cũng là mảnh còn thiếu của bài priority ở lesson 2: chuẩn bắt buộc thì hoặc enterprise, hoặc hook/CI — đừng gửi gắm vào thứ chạy bằng cơ chế khớp ngữ nghĩa.

Còn MCP thì tôi đọc như tích hợp hệ thống thuần tuý, đúng nghề: nó không dạy Claude điều gì, nó nối dây ra hệ thống ngoài. Kiến thức về cách dùng cái dây đó cho đúng quy trình team — cái đó mới là skill. Hai thứ bổ sung nhau, và một setup trưởng thành thường có cả: MCP mang Jira vào tầm với, skill dạy khi tạo ticket thì viết theo template nào.

Bài chia sẻ thì đóng lại đúng vòng tròn tôi mở ở lesson 2. Ở đó tôi ghi: chuẩn team đặt trong repo không ép được ai, vì Personal thắng Project. Lesson 5 trả lời thẳng: muốn ép thì lên enterprise managed settings — nơi duy nhất có ưu tiên cao nhất, đè cả personal. Và bài chốt bằng đúng một chữ mà tôi thấy nên treo trước mặt mỗi khi định "chuẩn hoá" thứ gì: "must". Ba mức phân phối vì thế map rất sạch sang ba mức cam kết thật của một tổ chức: repo = "team mình làm thế này" (đề nghị, ai có bản riêng thì bản riêng thắng); plugin/marketplace = "ai thấy hay thì lấy dùng" (tự nguyện hoàn toàn, nên nội dung phải sạch chuyện nội bộ); enterprise = "bắt buộc, không bàn". Đẩy một chuẩn "nên" lên enterprise là lạm quyền cơ chế; để một chuẩn "must" nằm trong repo là ảo tưởng đã kiểm soát — đây mới là lỗi tôi thấy hay gặp hơn.

Nhưng phần đắt nhất bài là cái bẫy subagent không kế thừa skill, và tôi thích nó vì nó nhất quán chứ không phải bug. Cả khoá Subagents dạy: subagent tồn tại để có context sạch. Nếu nó tự động kéo mọi skill vào thì cái "sạch" ấy mất ngay từ giây đầu. Nên Anthropic bắt khai báo tường minh — anh muốn context của nó có gì thì tự ghi ra và tự chịu. Hệ quả kéo theo cũng logic: skill trong subagent nạp lúc start, không on demand, vì subagent không có ai ngồi đó để hỏi xác nhận — không có người thì không có bước confirm, nên chỉ còn cách nạp sẵn theo danh sách.

Điều đó đẻ ra một mẹo thực dụng tôi sẽ dùng ngay: skills trong agent frontmatter là cách ép chuẩn mà không cần cầu xin prompt. Bài nói đúng ý — "enforce standards in delegated work without relying on prompts". Ở main conversation, skill là request-driven: khớp thì chạy, không khớp thì thôi — tức là may rủi. Nhưng trong subagent, liệt kê skills: là chắc chắn nạp, mọi lần review đều áp dụng. Với một reviewer subagent của team, đây là khác biệt giữa "hy vọng nó nhớ chuẩn accessibility" và "nó luôn có chuẩn accessibility trong tay". Nói cách khác: muốn skill hết ngẫu nhiên, hãy gắn nó vào một subagent — cùng một file skill, nhưng đổi từ gợi ý thành bắt buộc chỉ bằng chỗ khai báo.

Cuối cùng, một nhắc nhở nghề: bài này gọi built-in agent là Explorer/Plan/Verify còn khoá Subagents gọi General purpose/Explore/Plan — hai tài liệu chính chủ, lệch nhau. Bài học không phải "cái nào đúng" mà là danh sách sản phẩm thì đổi, cơ chế thì bền. Cái đáng thuộc là built-in không dùng được skill, custom mới dùng được — thứ này còn đúng lâu sau khi tên mấy con agent kia đã đổi.

Phần troubleshooting thì tôi quy về một câu chẩn đoán trước khi động vào bất cứ file nào: Claude không biết skill tồn tại, hay biết mà không chọn, hay chọn rồi mà chạy hỏng? Ba tầng đó sửa ở ba chỗ hoàn toàn khác nhau — không load là lỗi vật lý (sai folder, sai tên file, YAML gãy); không trigger / chọn nhầm là lỗi ngôn ngữ (description); runtime là lỗi môi trường (dependency, permission, path). Giá trị của việc tách ba tầng nằm ở chỗ nó chặn kiểu debug đoán mò hay gặp nhất: ngồi viết lại description cho hay hơn trong khi bệnh thật là file đặt sai chỗ. Đây cũng là lý do bài bảo chạy validator TRƯỚC — nó dọn sạch tầng vật lý để ta khỏi mất buổi chiều nghi oan cho câu chữ.

Chi tiết tôi thấy sắc nhất bài: nhét thông tin dependency vào description. Đọc lần đầu thấy sai chỗ — description là để matching cơ mà? Nhưng ngẫm lại thì đúng: description là thứ duy nhất Claude đọc trước khi quyết định, nên nó là chỗ duy nhất đặt được cảnh báo "muốn chạy cái này thì cần có X". Cộng dồn cả khoá, description gánh bốn vai: quyết định trigger, định hình cách phân biệt với skill khác, mang dependency info, và (từ bài subagent) định hình prompt mà main agent viết ra. Nói cách khác, hầu như mọi thứ sai với skill đều sửa được ở đúng một dòng — nên khi bí, đọc lại dòng đó trước.

Và cách test trigger của bài đáng chép vào quy trình team: đừng ngồi đoán description đã hay chưa — viết ra 3–4 cách mình sẽ thật sự hỏi ("help me profile this", "why is this slow?", "make this faster"), thử từng cái, cái nào trượt thì nhét chữ đó vào. Đây là thử nghiệm, không phải suy luận — và nó thừa nhận một sự thật dễ chịu: ta không sửa được cách Claude hiểu, ta chỉ sửa được hợp đồng ngôn ngữ giữa hai bên. Riêng với tôi làm trên Windows, hai dòng cuối là loại lỗi mất buổi tối mà đọc trước thì né được: SKILL.md phân biệt hoa-thường, và forward slash ở mọi nơi, kể cả Windows.

Về xung đột enterprise, lời khuyên "đổi tên mình đi, thường dễ hơn" nghe như nhượng bộ nhưng thực ra là lời khuyên đúng về mặt tổ chức: nếu công ty đã bỏ công đưa code-review lên enterprise thì đó là chuẩn "must", và thứ ta muốn thêm hầu như luôn là một góc riêng — nên nó xứng đáng có tên riêng (frontend-review) chứ không phải một bản code-review thứ hai âm thầm tranh chỗ. Trùng tên với chuẩn bắt buộc, xét cho cùng, là một lỗi đặt tên, không phải một cuộc tranh chấp quyền.

#Từ khoá cần thuộc

🔴 Core: skill · SKILL.md · frontmatter · name (required · ≤ 64 ký tự · lowercase/số/hyphen) · description (required · ≤ 1.024 ký tự · matching criteria — field quan trọng nhất) · allowed-tools (optional — bỏ trống = KHÔNG giới hạn) · model (optional) · ~/.claude/skills (personal) · .claude/skills (project) · skill = load on demand · CLAUDE.md (load mọi hội thoại) · slash command (phải gõ tay) · rule of thumb: lặp lại chỉ dẫn nhiều lần = một skill đang chờ viết · priority: Enterprise → Personal → Project → Plugins · semantic matching · confirmation prompt trước khi load · skills load lúc startup → phải restart · progressive disclosure · SKILL.md < 500 dòng · script: RUN, đừng READ — chỉ output tốn token · description trả lời 2 câu hỏi: làm gì? khi nào dùng?

🔴 Core (bài so sánh): skill = request-driven vs hook = event-driven · skill nhập vào context hiện tại vs subagent = context tách biệt/isolation · MCP = phạm trù khác (tool + integration bên ngoài) · CLAUDE.md = always-on vs skill = on demand · kết hợp, đừng ép mọi thứ vào skill

🔴 Core (troubleshooting): chạy skills validator (agent skills verifier) TRƯỚC TIÊN · không trigger → description + trigger phrases · không load → SKILL.md phải trong directory có tên (không ở root) + tên file chính xác SKILL.md · claude --debug · dùng nhầm skill → description quá giống nhau → làm khác biệt hẳn · bị shadow → priority hierarchy → đổi tên (đường dễ hơn) · plugin skill mất → clear cache + restart + reinstall · runtime → dependencies · chmod +x · forward slash kể cả trên Windows · ⭐ ghi dependency info vào description

🔴 Core (bài chia sẻ): 3 cách phân phối: repo (.claude/skills) · plugin/marketplace · enterprise managed settings · enterprise = ưu tiên cao nhất, đè personal/project/plugin · từ khoá "must" · ⚠️ subagent KHÔNG tự thấy skill — context sạch · built-in agent KHÔNG dùng được skill · custom subagent phải liệt kê tường minh · field skills: trong frontmatter của .claude/agents/<name>.md · skill nạp lúc subagent START, không on demand

🟡 Important: discover · activate · match request against description · context window · personal skill vs project skill · version control · delegate to a separate execution context · "different tool access than the main conversation" → subagent · isolation · project-wide standards · constraints (vd "never modify the database schema") · framework preferences · coding style · hook: linter mỗi lần save file · validation trước tool call · automated side effects · skill: knowledge informs how Claude handles requests · guidelines affect Claude's reasoning · C:/Users/<user>/.claude/skills (Windows) · root directory of repository · folder of instructions and resources · skill = directory, tên directory khớp tên skill · mkdir -p ~/.claude/skills/<name> · update = sửa SKILL.md · remove = xoá directory · enterprise (managed settings) · plugins (ưu tiên thấp nhất) · tên mô tả rõ để tránh conflict (frontend-review thay vì review) · scan bốn vị trí, chỉ nạp name + description · agent skills open standard · scripts/ · references/ · assets/ · link file phụ + chỉ dẫn KHI NÀO nạp · Read, Grep, Glob, Bash (ví dụ read-only) · allowed-tools = dùng tool đó không cần hỏi permission · permission model · guardrails · security-sensitive workflow · environment validation · data transformation (cần nhất quán)

🟢 Good-to-know: code review standard · commit message format · brand guideline · documentation template · debugging checklist · skill load hiển thị trên terminal · pr-description skill (ví dụ của khoá) · git diff main...HEAD · format What / Why / Changes · available skills list · codebase-onboarding skill (ví dụ allowed-tools) · architecture-guide.md (ví dụ reference file) · ví von "mục lục thay vì cả cuốn sách" · file 2.000 dòng = tốn context + khó maintain · .claude chứa agents · hooks · skills · settings · marketplace · strictKnownMarketplaces (source: github/npm · repo · package) · mandatory standards · security requirements · compliance workflows · frontend-security-accessibility-reviewer (ví dụ agent) · accessibility-audit · performance-check · Explorer/Plan/Verify (built-in agent theo khoá này — khoá Subagents ghi General purpose/Explore/Plan) · "enforce standards in delegated work without relying on prompts" · uv (cách cài validator nhanh nhất) · "what skills are available" · biến thể test trigger: "help me profile this" · "why is this slow?" · "make this faster" · chmod +x · "the best skills come from real pain points"

Nguồn: Introduction to Agent Skills (Anthropic Academy) — Copyright Anthropic. Phần đề thi thử cho khoá này nằm ở tab "Đề thi thử".