Agent Skills: Hướng dẫn chi tiết xây skill từ SKILL.md đến production

TL;DR

Agent Skills không phải plugin hay extension - đây là thư mục Markdown mà agent đọc khi cần.
Bài này đi vào từng lớp kỹ thuật: SKILL.md anatomy, progressive disclosure hoạt động ra sao bên dưới, dynamic context injection, invocation control, và các pattern nâng cao để skill không bị "dead on arrival" sau một vài turns.
Kèm ví dụ code thực tế để build skill production-ready từ đầu.

Vấn đề thật sự

AI agents giỏi về code, debug, viết docs - nhưng mặc định chúng không biết gì về cách team bạn làm việc. Không biết convention commit message, không biết pipeline linting tùy chỉnh, không biết mọi PR phải qua security checklist trước khi merge. Mỗi session mới, bạn lại giải thích lại từ đầu.

Giải pháp trước Skills là nhồi tất cả vào system prompt hoặc file CLAUDE.md. Vấn đề: toàn bộ context đó load mỗi session dù bạn không cần đến. 50 quy ước, 20 tài liệu API, 10 workflow - tất cả chiếm context window ngay cả khi bạn chỉ hỏi "refactor function này".

Skills giải quyết bằng lazy loading: chỉ load knowledge khi task thực sự cần đến nó.

Anatomy của SKILL.md

Một skill production-ready có cấu trúc:

your-skill/
├── SKILL.md              # Bắt buộc
├── scripts/
│   ├── validate.py       # Python/Bash/JS - agent chạy trực tiếp
│   └── transform.sh
├── references/
│   ├── api-guide.md      # Tài liệu load khi cần
│   └── examples/
└── assets/
    └── report-template.md

File SKILL.md có hai phần bắt buộc:

---
name: security-review            # max 64 ký tự, kebab-case
description: |
  Chạy security audit cho code changes bằng CodeQL và Semgrep.
  Dùng khi user hỏi về security, request PR review, hoặc check
  vulnerability. KHÔNG dùng cho code refactor thông thường.
allowed-tools: "Bash(python:*) Bash(npm:run) Read Write"
disable-model-invocation: false
---

# Security Review

## Instructions
[Markdown instructions...]

Hai trường YAML bắt buộc: name (max 64 ký tự) và description (max 1.024 ký tự). Spec khuyến nghị giữ body dưới 5.000 token và toàn bộ thư mục dưới 500 dòng.

Progressive disclosure dưới mui

Đây là cơ chế quan trọng nhất - hiểu rõ nó giúp bạn debug khi skill không hoạt động như kỳ vọng.

Tầng 1 - Session start: Agent scan tất cả thư mục skills, đọc chỉ YAML frontmatter của từng file. Khoảng 30-50 token/skill. 100 skills = ~3.000-5.000 token overhead tổng - không đáng kể.

Tầng 2 - Task matching: Khi user gửi request, agent so sánh intent với tất cả description đã load. Nếu match, agent pull toàn bộ SKILL.md body vào context - thường 1.000-5.000 token.

Tầng 3 - On-demand resources: Scripts, references, assets trong các thư mục con chỉ load khi skill body tham chiếu đến chúng và agent quyết định cần dùng. File PDF 10MB hoặc guide 50 trang không ảnh hưởng context cho đến khi thực sự cần.

Auto-compaction behavior: Khi conversation dài, Claude Code compact context nhưng re-attach skills đã invoke vào shared budget 25.000 token - giữ 5.000 token đầu tiên của mỗi skill. Nếu bạn invoke nhiều skills trong một session và skill đầu "dừng hoạt động", đó là lý do. Fix: re-invoke skill sau compaction, hoặc viết instructions ngắn hơn.

Description là trigger quan trọng nhất

Đây là sai lầm phổ biến nhất khi build skill: description quá chung chung khiến skill không bao giờ trigger, hoặc trigger sai.

Pattern tốt:

description: |
  Phân tích Figma design files và generate developer handoff docs.
  Dùng khi user upload file .fig, hỏi về "design specs",
  "component documentation", hoặc "design-to-code handoff".
  KHÔNG dùng cho code review hay text editing thông thường.

Pattern tệ:

description: Helps with design projects.

Nguyên tắc: bao gồm trigger phrases user thực sự sẽ nói, đề cập file types liên quan, nêu rõ bài toán skill giải quyết, và thêm negative triggers ("KHÔNG dùng cho...") để tránh false positives.

Dynamic context injection

Tính năng ít được biết đến nhưng cực kỳ mạnh. Cú pháp ! trong SKILL.md chạy shell command trước khi LLM đọc bất kỳ gì - output được inject trực tiếp vào instructions:

---
name: summarize-changes
description: Tóm tắt uncommitted changes và flag rủi ro.
---

# Summarize Changes

Current diff:
!git diff HEAD

Modified files:
!git diff --name-only HEAD

## Instructions
Phân tích diff trên và:
1. Tóm tắt các thay đổi chính
2. Flag bất kỳ pattern nguy hiểm nào (hardcoded secrets, SQL injection, XSS)
3. Đề xuất test cases cần thêm

Khi skill này chạy, lệnh git diff HEAD thực thi trước, output thay thế placeholder, Claude nhận được prompt với actual diff đã inline - không cần đoán từ file đang mở. Multi-line commands dùng fenced code block mở bằng ```!.

Invocation control

Mặc định cả user và agent đều có thể trigger skill. Hai frontmatter fields cho phép kiểm soát:

Rule đơn giản: bất kỳ skill nào có side effects ngoài thế giới thực (push code, gửi message, deploy) nên dùng disable-model-invocation: true. Bạn không muốn agent tự quyết định deploy vì "code trông có vẻ ổn".

Cài đặt và quản lý

Dùng CLI từ Vercel để install skills một lệnh, tự detect agent đang cài:

# Install từ GitHub
npx skills add anthropics/skills

# Install skill cụ thể
npx skills add vercel-labs/agent-skills@vercel-react-best-practices

# Install cho tất cả agents đang có
npx skills add firecrawl/cli --all

# List skills đã cài
npx skills list

# Kiểm tra update
npx skills check

Nếu install thủ công, vị trí thư mục skills khác nhau theo agent: Claude Code đọc từ ~/.claude/skills/, Codex CLI từ ~/.codex/skills/, Gemini CLI từ ~/.gemini/skills/. Skills cần restart session để có hiệu lực - không hot-reload mid-session.

Bảo mật khi dùng community skills

Skills kế thừa toàn bộ permissions của agent: shell access, filesystem, network. Snyk scan Feb 2026 cho thấy 36% skills trên marketplace có lỗ hổng bảo mật, 76 skills có malicious payload xác nhận. Trước khi install bất kỳ skill nào từ nguồn không quen:

• Đọc toàn bộ SKILL.md và mọi file trong scripts/ - không dùng nếu không hiểu

• Chú ý đặc biệt đến instructions kết nối network bên ngoài hoặc đọc credentials

• Kiểm tra allowed-tools trong frontmatter - skill chỉ nên request permissions cần thiết

• Dùng skills từ official repos: anthropics/skills, verified partners tại claude.com/connectors

Skill tệ không chỉ vô dụng - nó làm giảm baseline performance của agent trên tasks không liên quan thông qua token competition và architectural pattern bleed.

Bắt đầu từ đâu

Thực tế nhất: dùng skill-creator skill của Anthropic. Mô tả workflow cần trong conversation, agent viết SKILL.md cho bạn - thường dưới 15 phút. Browse skills.sh để xem patterns từ 89.000+ skills đã publish, hoặc dùng thẳng repo official anthropics/skills như reference.

Via: Claude Code Docs, Claude API Docs, Anthropic Engineering.