Claude Code Agent Skills — Hướng dẫn trực quan cho người mới

Skill là gì? (Không phải file markdown!)

Hiểu sai lầm phổ biến nhất trước tiên: Skill KHÔNG phải là file markdown chứa mấy dòng hướng dẫn. Skill là một thư mục hoàn chỉnh — một "gói kiến thức" mà Claude khám phá dần dần.

    💡 Tóm gọn trong 1 câu: Skill = thư mục chứa hướng dẫn + script + template + dữ liệu mà Claude tải theo nhu cầu, thay vì nhét hết vào prompt.
  

So sánh nhanh: Cách cũ vs Skills

❌ Cách cũ — dump vào prompt

Nhét tất cả hướng dẫn vào CLAUDE.md hoặc system prompt. Tốn token, Claude hay bị "quên" vì context quá dài.

✅ Skills — tải theo nhu cầu

Claude chỉ đọc metadata (~100 tokens). Khi cần mới đọc thêm. Tiết kiệm context, Claude tập trung hơn.

Cấu trúc thư mục Skill

my-skill/
├── SKILL.md          # Bắt buộc: metadata + hướng dẫn
├── references/       # Tài liệu API, docs — đọc khi cần
├── scripts/          # Python/Bash tools — chạy khi cần
├── assets/           # Template, font, icon
└── examples/         # Output mẫu để Claude tham khảo

Ví dụ SKILL.md đơn giản nhất

---
name: create-report
description: "Tạo báo cáo Excel từ dữ liệu. Kích hoạt khi user
  yêu cầu phân tích CSV, tạo spreadsheet, hoặc báo cáo bảng."
---

# Quy trình tạo báo cáo

1. Đọc file dữ liệu từ user
2. Chạy script phân tích: `python scripts/analyze.py`
3. Tạo Excel output theo template trong assets/template.xlsx

## Gotchas (điểm hay sai)
- Luôn kiểm tra encoding UTF-8 trước khi đọc CSV
- Cột ngày tháng phải format YYYY-MM-DD

Kiến trúc Progressive Disclosure

Đây là "linh hồn" của Skills — hệ thống 3 cấp độ tải thông tin, xem context window như tài nguyên công cộng có hạn.

Sơ đồ: Kiến trúc Progressive Disclosure 3 cấp — context window được bảo vệ bằng cách tải thông tin theo nhu cầu

    🔑 Insight quan trọng từ Thariq Shihipar (kỹ sư Anthropic):

    "Context window là tài nguyên công cộng — mỗi token bạn nhét vào đều cạnh tranh trực tiếp với conversation history và reasoning space của model."

Tại sao điều này quan trọng?

LLM có hiện tượng "context rot" — khi context quá dài, khả năng nhớ lại thông tin giảm sút do cơ chế attention phải xử lý n² quan hệ cặp đôi. Anthropic báo cáo context engineering đúng cách cải thiện 54% hiệu suất benchmark agent, giảm 84% token consumption trong test 100 vòng.

9 danh mục Skill nội bộ Anthropic

Thariq Shihipar xác nhận taxonomy này vào 03/2026 — không phải quy tắc bắt buộc, mà là cách tốt để kiểm tra "tổ chức mình đang thiếu loại nào".

Library & API Reference

Dạy Claude dùng đúng library/SDK nội bộ mà training data chưa biết

billing-lib

Product Verification

Test & verify code đang chạy đúng. Kết hợp Playwright, tmux

signup-flow-driver

Data Fetching & Analysis

Kết nối data stack, monitoring. Đóng gói credentials, query patterns

funnel-query

Business Process

Rút gọn workflow lặp đi lặp lại thành 1 lệnh đơn

standup-post

Code Scaffolding

Generate boilerplate cho framework bằng composable scripts

new-migration

Code Quality & Review

Enforce code standards, chạy tự động qua hooks / GitHub Actions

adversarial-review

CI/CD & Deployment

Push, deploy, release management. Babysit PR, retry CI

babysit-pr

Runbooks

Nhận triệu chứng → điều tra multi-tool → báo cáo chẩn đoán

oncall-runner

Infrastructure Ops

Bảo trì, destructive actions cần guardrails (cleanup orphaned pods...)

dependency-management

    💡 Quy tắc vàng: Skills hiệu quả nhất khi dạy Claude những điều nó CHƯA BIẾT — kiến thức nội bộ tổ chức (internal API, quy trình team, deployment procedures), không phải kiến thức chung mà model đã biết từ training data.
  

9 tips viết Skill hay — từ người trong cuộc

Best practices từ đội Anthropic sau hàng trăm skills nội bộ, tổng hợp từ bài viết của Thariq Shihipar và tài liệu chính thức.

1. Description là trigger, không phải summary

Khi khởi động, Claude scan description của tất cả skills để quyết định "có skill nào phù hợp?" Description viết cho model đọc, không phải cho người.

❌ Description tệ

"I help with Excel."

✅ Description tốt

"Xử lý file Excel và tạo báo cáo. Sử dụng khi user hỏi về dữ liệu bảng tính, phân tích CSV, hoặc đầu ra dạng bảng."

Research cộng đồng cho thấy: description tối ưu đúng cách cải thiện activation rate từ 20% → 50%. Thêm examples thì 72% → 90%.

2. Gotchas — phần giá trị nhất

Claude đã biết nhiều pattern tiêu chuẩn. Skill nên tập trung vào thông tin đẩy model ra khỏi hành vi mặc định. Phần Gotchas liệt kê các failure points phổ biến — update liên tục qua thời gian.

## Gotchas
- API v3 trả 200 nhưng body rỗng khi token hết hạn
- Field "amount" là CENT, không phải dollar
- Staging dùng endpoint khác production
- Luôn check rate limit header trước khi retry

📁

3. File system = Context engineering

Tách reference ra file riêng (REFERENCE.md, FORMS.md). Claude chỉ đọc khi cần → tiết kiệm token.

💾

4. Dùng ${CLAUDE_PLUGIN_DATA}

Data trong skill directory bị xóa khi upgrade. Lưu vào thư mục ổn định này cho logs, config, SQLite.

🔗

5. On-demand hooks

Hooks chỉ active khi skill gọi: /careful block destructive ops, /freeze lock files. 18+ event types.

📜

6. Script storage — cực hiệu quả

Đóng gói script sẵn → Claude compose thay vì viết từ đầu. Code script không vào context, chỉ output.

🎯

7. Đừng "railroading" Claude

Skill được tái sử dụng nhiều lần. Cho đủ thông tin nhưng để Claude linh hoạt thích ứng tình huống.

⚙️

8. Setup pattern

Skill cần config? Lưu vào config.json. Chưa setup → agent hỏi user. Pattern đơn giản nhưng hiệu quả.

Demo: Skill "standup-post" hoạt động thế nào?

Theo dõi một skill đi qua từng cấp độ progressive disclosure để hiểu cơ chế hoạt động thực tế.

Bước 1

Khởi động Claude Code

Claude scan metadata: standup-post — "Tổng hợp standup từ GitHub + Jira"

~100 tokens

→

Bước 2

User: "Viết standup cho hôm nay"

Claude khớp yêu cầu → đọc SKILL.md body: quy trình, format, gotchas

~2.000 tokens

→

Bước 3

Thực thi

Chạy scripts/fetch_activity.py → lấy GitHub PRs + Jira tickets. Đọc standups.log để so sánh

Chỉ output vào context

    🎯 Kết quả: Claude tổng hợp activity từ nhiều nguồn, format theo template chuẩn team, so sánh với lần trước để giữ consistency — tất cả từ 1 lệnh /standup-post
  

So sánh với Cursor, Windsurf, Copilot, Cline

Tất cả đều dùng markdown + metadata — nhưng cách và thời điểm load vào context window là yếu tố quyết định.

Tính năng	Claude Code Skills	Cursor Rules	Windsurf Rules	Copilot	Cline Rules
Tải theo nhu cầu	✓ Progressive	Glob-based	Model decide	Always-on	Append prompt
Thư mục + scripts	✓ Đầy đủ	File đơn	File đơn	File đơn	File đơn
Hooks/Events	18+ event types	Không	Không	Có hooks	Không
Cross-platform	agentskills.io	Cursor only	Windsurf only	VS Code/GH	Cline only
Đặc biệt	Plugin marketplace	Glob patterns tốt	Memories system	Platform sâu nhất	AI tự sửa rules

Context Engineering > Prompt Engineering

Skills là triển khai trực tiếp của context engineering — khái niệm mà Anthropic gọi là "sự tiến hoá tự nhiên của prompt engineering".

Context engineering quản lý toàn bộ cấu hình token model nhìn thấy — không chỉ prompt

Anthropic xác định 6 chiến lược chính: system prompt đúng "độ cao", thiết kế tool hiệu quả token, truy xuất context đúng lúc, progressive disclosure, compaction cho task dài, và ghi chú có cấu trúc cho agentic memory.

    💡 Thariq nói: "Hãy nghĩ về toàn bộ file system như một dạng context engineering và progressive disclosure." — Skills chính là triển khai thực tế của triết lý này.
  

Hệ sinh thái & cảnh báo chất lượng

60K+ skills trên GitHub nhưng chất lượng rất khác nhau. Biết chọn đúng skill là kỹ năng quan trọng.

    ⚠️ Cảnh báo thực tế: Nhà đánh giá Mikhail Shcheglov test 47 skills phổ biến → 40 cái làm output TỆ HƠN so với Claude Code thuần. Hầu hết chỉ là "shallow prompt wrappers" thêm token, latency mà không tạo giá trị.
  

Skills đáng chú ý (đã được kiểm chứng)

🎨

frontend-design

Skill chính thức của Anthropic. 277K+ installs. Cải thiện "design taste" của Claude, tránh mấy pattern AI cũ rích.

🛡️

Sentry code-review

Skill bảo mật duy nhất Tim Kamanin thấy đáng cài đặt sau khi test 5 security skills.

🔧

obra/superpowers

20+ skills đã battle-tested: TDD, debugging, collaboration workflows. Bộ sưu tập cộng đồng chất lượng cao.

🧰

skill-creator (meta-skill)

Skill để tạo skill! Có vòng lặp tối ưu description, chạy eval 60/40 train/test, iterate tới 5 lần.

Nơi tìm Skills chất lượng

Claude Plugin Marketplace

claude.com/plugins

GitHub — anthropics/skills

github.com/anthropics/skills

SkillsMP — 500K+ entries

skillsmp.com

agent-skills.cc — 1K curated

agent-skills.cc

Tài nguyên học tập chính thức

Nguồn tham khảo chính thức và các bài viết kỹ thuật từ đội Anthropic — đáng bookmark.

Tài liệu Anthropic

Skills Documentation

docs.claude.com/.../skills

Agent Skills Overview

docs.claude.com/.../overview

Engineering Blog: Agent Skills

anthropic.com/engineering/...

Context Engineering Blog

anthropic.com/engineering/...

Bài viết & talks của Thariq Shihipar (@trq212)

How We Use Skills (03/2026)

x.com/trq212/status/203394...

Agent SDK Workshop (~2h)

youtube.com — AI Engineer CODE

Complete Guide PDF

resources.anthropic.com/...

Open Standard Spec

agentskills.io

Bắt đầu trong 5 phút

Tạo skill đầu tiên của bạn — chỉ cần 1 file SKILL.md.

Tạo thư mục

mkdir -p .claude/skills/my-first-skill

→

Viết SKILL.md

YAML frontmatter + hướng dẫn + gotchas

→

Dùng ngay!

Gõ /my-first-skill hoặc để Claude tự kích hoạt

Template khởi đầu

---
name: my-first-skill
description: "Mô tả WHEN TO TRIGGER — không phải summary.
  Ví dụ: Sử dụng khi user yêu cầu X, Y, hoặc Z."
---

# Hướng dẫn chính (giữ dưới 5.000 tokens)

Quy trình:
1. Bước 1...
2. Bước 2...

## Gotchas
- Điểm hay sai #1
- Điểm hay sai #2

## Tài liệu tham khảo
Xem references/api-docs.md để biết chi tiết API.

    🚀 Mẹo nhanh: Dùng meta-skill skill-creator của Anthropic — gõ /skill-creator trong Claude Code và nó sẽ giúp bạn tạo skill mới, tự tối ưu description, chạy eval để kiểm tra trigger rate!
  