| tags | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
Mục tiêu của tài liệu này: giúp bạn tạo một skill chạy được ngay trong 15–30 phút, rồi từng bước nâng cấp lên mức “đem đi dùng cho team / cộng đồng”.
- Chọn 2–3 use cases cụ thể (một câu là đủ).
- Tạo folder skill theo kebab-case và file
SKILL.md. - Viết YAML frontmatter thật “đúng trigger” (đây là phần quan trọng nhất).
- Viết Instructions theo kiểu workflow có bước + tiêu chí thành công + xử lý lỗi.
- Test 3 loại: Triggering / Functional / Performance.
- Zip folder → upload vào Claude.ai hoặc đặt vào thư mục skills của Claude Code.
Skill là một “gói hướng dẫn” (instructions) được đóng gói dạng một folder để Claude có thể:
- Nhận ra khi nào cần dùng (dựa vào YAML frontmatter).
- Tải đúng phần cần thiết (progressive disclosure).
- Thực hiện workflow một cách ổn định, đỡ phải nhắc đi nhắc lại.
| Thành phần | Bắt buộc | Dùng để làm gì |
|---|---|---|
SKILL.md |
✅ | Hướng dẫn chính (Markdown + YAML frontmatter) |
scripts/ |
⛔️ | Code chạy được (Python/Bash/Node…) để validate/transform… |
references/ |
⛔️ | Tài liệu phụ, API guide, examples… Claude sẽ load khi cần |
assets/ |
⛔️ | Template, fonts, icon, file mẫu… |
- Progressive Disclosure
- Frontmatter = “đèn báo” giúp Claude biết skill nào liên quan.
- Body
SKILL.md= hướng dẫn đầy đủ, chỉ load khi skill được chọn. - File link trong
references//assets/= chỉ mở khi thật cần.
- Composability
- Claude có thể load nhiều skill cùng lúc.
- Skill của bạn nên “chơi đẹp”: không giả định mình là skill duy nhất.
- Portability
- Cùng một skill chạy được trên Claude.ai / Claude Code / API (nếu môi trường đủ dependency).
graph TD
A["Level 1<br/>YAML frontmatter<br/>(luôn nằm trong system prompt)"] --> B["Level 2<br/>SKILL.md body<br/>(load khi skill liên quan)"]
B --> C["Level 3<br/>Linked files<br/>references/ assets/ scripts/"]
A --- A1["Mục tiêu: kích hoạt đúng"]
B --- B1["Mục tiêu: làm đúng workflow"]
C --- C1["Mục tiêu: chi tiết + ít token"]
Nếu bạn có MCP server (Notion/Linear/Sentry/Figma…), thì:
- MCP = cho Claude dụng cụ + nguyên liệu (tool access, data realtime).
- Skills = công thức (cách dùng tools cho ra kết quả tốt, ổn định).
| MCP (Connectivity) | Skills (Knowledge) |
|---|---|
| Kết nối Claude tới dịch vụ | Dạy Claude dùng dịch vụ “đúng bài” |
| Cho phép gọi tool + lấy data realtime | Nhúng workflow + best practices |
| “Claude có thể làm gì” | “Claude nên làm như thế nào” |
Không có skill thì hay gặp:
- User kết nối xong nhưng không biết “bước tiếp theo”.
- Ticket support kiểu: “làm sao để làm X?”
- Mỗi cuộc chat bắt đầu lại từ 0.
- Kết quả thiếu nhất quán (vì prompt mỗi người mỗi kiểu).
Có skill thì:
- Workflow tự kích hoạt khi cần.
- Tool usage ổn định, giảm lỗi.
- Onboarding nhanh hơn.
Goal: một skill “đủ dùng”, trigger ổn, instructions rõ.
Checklist nhanh:
- Folder kebab-case
- Có
SKILL.mdđúng chữ (case-sensitive) - Frontmatter có
name+description -
descriptioncó WHAT + WHEN - Có ít nhất 2 ví dụ + 1 phần troubleshooting
Goal: có test cases, success criteria, versioning, rollback notes.
- Thêm
metadata.version - Thêm “Triggering tests” (10–20 câu)
- Thêm “Do / Don’t” để tránh overtrigger
Goal: repo GitHub, README cho người, docs cho người dùng, workflow rõ ràng.
- Repo public + README (ở root repo, không nằm trong folder skill)
- Hướng dẫn cài đặt + screenshots
- Release zip
graph LR
Z["0: Draft"] --> T["1: Test"] --> I["2: Iterate"] --> S["3: Share"]
T -->|under/over trigger| I
I --> T
Trước khi viết chữ nào, chốt 2–3 use cases.
Template:
- Use case: …
- Trigger: user hay nói câu gì?
- Steps: 3–7 bước, có tool nào?
- Result: “xong” nghĩa là gì? (deliverable cụ thể)
Ví dụ (MCP + skill):
- Use case: Lên kế hoạch sprint
- Trigger: “help me plan this sprint”, “create sprint tasks”
- Steps:
- Fetch project status (Linear MCP)
- Ước lượng capacity/velocity
- Đề xuất ưu tiên
- Tạo tasks với label/estimate
- Result: Sprint được tạo, tasks đủ metadata
| Category | Dùng khi | Đặc điểm | Có cần MCP? |
|---|---|---|---|
| 1) Document & Asset Creation | tạo doc/design/code output “đẹp và chuẩn” | style guide + template + checklist | ❌ |
| 2) Workflow Automation | quy trình nhiều bước, cần consistency | step-by-step + validation gates + loops | tuỳ |
| 3) MCP Enhancement | đã có connector, cần “workflow guidance” | phối hợp tool calls + error handling | ✅ |
Đặt tiêu chí kiểu “đủ đo”, nhưng không cần quá khoa học.
Định lượng (gợi ý):
- Trigger đúng ~90% trên 10–20 câu test.
- Hoàn thành workflow trong X tool calls (so với baseline).
- 0 API call fail trong happy path.
Định tính (gợi ý):
- User không cần nhắc “giờ làm gì tiếp?”.
- Workflow xong mà ít phải sửa.
- Kết quả ổn định qua nhiều session.
Tip: Lúc đầu chỉ cần chọn 1 task khó nhất, iterate tới khi “ngon”, rồi rút thành skill.
Nếu skill dùng trong tổ chức, thêm mấy cái này để khỏi “toang”:
- Versioning:
metadata.version+ changelog ngắn ở repo. - UAT: test lại 10–20 triggering + 3–5 functional trước khi rollout.
- Rollout: beta nhóm nhỏ → mở rộng.
- Ownership: ai chịu trách nhiệm update + support.
your-skill-name/
├── SKILL.md
├── scripts/ # optional
│ ├── validate.py
│ └── normalize.sh
├── references/ # optional
│ ├── api-guide.md
│ └── examples/
└── assets/ # optional
└── template.md
SKILL.mdphải đúng chính tả + đúng hoa/thường.- ✅
SKILL.md - ❌
skill.md,SKILL.MD
- ✅
- Folder skill dùng kebab-case:
- ✅
notion-project-setup - ❌
Notion Project Setup,notion_project_setup
- ✅
- Không đặt
README.mdbên trong folder skill.- README cho người đọc nên để ở root repo khi bạn share trên GitHub.
Format tối thiểu:
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---name(required)- kebab-case, không space, không capital
- nên trùng tên folder
description(required)- phải có WHAT + WHEN
- có trigger phrases thật sự (câu user hay nói)
- < 1024 ký tự
- không có ký tự XML
<> - nên nhắc tới file types nếu liên quan
Optional (đáng dùng):
license: MIT
compatibility: Claude.ai / Claude Code. Requires network access.
metadata:
author: YourNameOrOrg
version: 1.0.0
mcp-server: linear
category: productivity
tags: [project-management, automation]
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"Lưu ý bảo mật: không dùng
<>trong frontmatter. Skill name không được chứa “claude” hoặc “anthropic” (reserved).
---
name: your-skill
description: ...
---
# Tên Skill
## Instructions
### Step 1: ...
- Làm gì
- Input cần gì
- Output thế nào là đúng
### Step 2: ...
...
## Examples
### Example 1
User says: "..."
Actions:
1. ...
Result: ...
## Troubleshooting
### Error: "..."
Cause: ...
Solution: ...Công thức: [WHAT] + [WHEN] + [KEY CAPABILITIES]
✅ Ví dụ tốt:
description: Phân tích file thiết kế Figma và tạo tài liệu handoff cho dev. Dùng khi user upload .fig, hoặc hỏi "design specs", "component documentation", "design-to-code handoff".❌ Ví dụ tệ:
description: Helps with projects.- Cụ thể + hành động được
- ✅ “Run
python scripts/validate.py --input {filename}…” - ❌ “Validate the data before proceeding.”
- ✅ “Run
- Gắn tiêu chí pass/fail
- “Expected output: …”
- Error handling rõ
- “Nếu gặp
Connection refusedthì check…"
- “Nếu gặp
- Progressive disclosure
- cái gì dài thì bỏ vào
references/rồi link
- cái gì dài thì bỏ vào
- Deterministic validation
- chỗ critical thì dùng script validate thay vì chỉ viết chữ
| Cách test | Khi nào dùng | Ưu / Nhược |
|---|---|---|
| Manual (Claude.ai) | prototype nhanh | nhanh nhưng khó repeat |
| Scripted (Claude Code) | lặp lại được | setup hơn nhưng ổn định |
| Programmatic (Skills API) | scale/prod | build suite + infra |
- Triggering tests
- ✅ trigger ở câu “rõ ràng”
- ✅ trigger ở câu paraphrase
- ❌ không trigger ở câu không liên quan
Ví dụ:
- Should trigger:
- “Giúp mình tạo sprint plan trong Linear”
- “Tạo tickets cho sprint này”
- Should NOT trigger:
- “Thời tiết hôm nay sao?”
- “Viết hàm Python” (nếu skill không liên quan)
- Functional tests
- Output đúng cấu trúc
- Tool/API call thành công
- Error handling chạy được
- Edge cases
- Performance comparison So sánh “có skill” vs “không skill”:
- số lần back-and-forth
- số tool calls
- token
- tỉ lệ fail
skill-creator là skill hỗ trợ bạn tạo và iterate skills nhanh. Nó làm tốt 3 việc:
- Tạo skill từ mô tả tự nhiên: sinh ra
SKILL.mdđúng format + gợi ý trigger phrases. - Review skill: flag lỗi thường gặp (description mơ hồ, thiếu trigger, cấu trúc lộn xộn) + cảnh báo under/over-triggering.
- Iterate theo feedback: sau khi bạn test và thấy fail case, đưa transcript/edge case vào để nó đề xuất chỉnh.
Cách dùng (prompt mẫu):
- “Use the skill-creator skill to help me build a skill for [your use case]”
- “Review this skill and suggest improvements”
- “Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]”
Note:
skill-creatorgiúp thiết kế và cải thiện skill, nhưng không tự chạy test suite hay đo metric định lượng thay bạn.
- Undertrigger → thêm trigger phrases thật, cụ thể hơn.
- Overtrigger → thêm “Do NOT use when …” và bó scope.
- Không làm theo instructions → rút gọn, đưa critical lên đầu, thêm checklist, thêm script validate.
Cá nhân:
- Download folder
- Zip (nếu cần)
- Upload Claude.ai: Settings → Capabilities → Skills
- Hoặc đặt vào Claude Code skills directory
Tổ chức:
- Admin có thể deploy workspace-wide
- Auto updates + centralized management
Một chuẩn mở (portable):
Skills được publish như một open standard (giống MCP). Nên về nguyên tắc, bạn “tạo 1 lần, chạy nhiều nơi”. Nếu skill phụ thuộc môi trường (network access, system packages, MCP server cụ thể…), ghi rõ trong compatibility + metadata để người dùng khỏi đoán.
| Use case | Best surface |
|---|---|
| End users dùng trực tiếp | Claude.ai / Claude Code |
| Manual testing trong dev | Claude.ai / Claude Code |
| App/agent chạy tự động | API |
| Prod deployments ở scale | API |
| Pipelines/automation | API |
Note: Skills qua API thường yêu cầu Code Execution Tool (beta) để có môi trường sandbox an toàn cho chạy tool/scripts.
- Host skill trên GitHub (public)
- README cho người đọc (cài đặt + ảnh + demo)
- Releases zip
- Link skill trong docs MCP (nếu có)
- giải thích “MCP + Skills” tạo value nhanh hơn
- Viết Installation Guide (template)
# Installing the [Your Service] skill
1. Download
- git clone ...
- hoặc tải ZIP từ Releases
2. Install
- Claude.ai → Settings → Skills → Upload
- Chọn folder skill (zipped)
3. Enable
- bật skill
- đảm bảo MCP server Connected (nếu có)
4. Test
- hỏi: "Set up a new project in [Your Service]"✅ Tập trung vào outcome:
- “Thiết lập workspace dự án trong 30s thay vì 30 phút.”
❌ Đừng nói kiểu:
- “Skill là folder chứa YAML…”
- Problem-first: user nói outcome → skill tự chọn tool + orchestrate.
- Tool-first: user có tool rồi → skill dạy best practices + workflow.
flowchart TD
Q[User intent?] --> P{User nói outcome<br/>hay nói tool?}
P -->|Outcome| PF[Problem-first skill]
P -->|Tool/connector| TF[Tool-first skill]
PF --> O[Orchestrate workflow]
TF --> G[Guide best practices]
Dùng khi: quy trình nhiều bước, thứ tự quan trọng.
- Bước rõ ràng
- Data dependency giữa bước
- Validation mỗi bước
- Có rollback/fallback
Dùng khi: workflow chạy qua nhiều dịch vụ.
- Phase separation
- Pass dữ liệu giữa MCPs
- Error handling tập trung
Dùng khi: output cần iterate mới đẹp.
- Draft → validate → refine loop
- Có “quality threshold”
- Biết dừng khi đủ
Dùng khi: cùng outcome nhưng tool khác nhau theo context.
- Decision criteria rõ
- Fallback options
- Giải thích “vì sao chọn tool này”
Dùng khi: skill mang tri thức chuyên ngành (compliance, security, finance…).
- Rule check trước khi hành động
- Audit trail
- Governance rõ
| Symptom / Error | Cause | Fix |
|---|---|---|
| “Could not find SKILL.md” | sai tên file | rename đúng SKILL.md |
| “Invalid frontmatter” | YAML sai format | kiểm tra --- delimiters, quote… |
| “Invalid skill name” | name có space/capital |
dùng kebab-case |
Quick checklist:
descriptioncó đủ trigger phrases chưa?- Có nhắc file types chưa? (nếu liên quan)
- Có đang quá chung chung không?
Debug tip:
- Hỏi Claude: “When would you use the [skill name] skill?” → Claude sẽ quote description, bạn nhìn xem thiếu gì.
Cách fix:
- Thêm negative trigger:
description: Advanced data analysis for CSV files (regression, clustering). Do NOT use for simple exploration (use data-viz skill instead).- Bó scope:
- “chỉ dành cho contract review” thay vì “process documents”
Checklist:
- MCP server Connected?
- Auth token/API key còn sống?
- Test MCP độc lập (không qua skill) xem có gọi được không
- Tool names đúng case-sensitive không
Nguyên nhân hay gặp:
- Instructions quá dài → rút gọn.
- Critical bị chôn dưới → đưa lên đầu, dùng
## Critical. - Ngôn ngữ mơ hồ → chuyển thành checklist + tiêu chí rõ.
- Chỗ critical → thêm script validate (deterministic).
Fix:
- Chuyển chi tiết sang
references/ - Giữ
SKILL.md< ~5.000 words - Đừng bật quá nhiều skill cùng lúc (20–50+ là dễ “nặng”)
- Có 2–3 use cases cụ thể
- Xác định tools cần (built-in / MCP)
- Xem qua guide + examples
- Planned folder structure
- Folder kebab-case
-
SKILL.mdđúng tên - YAML có
---delimiters -
namekebab-case -
descriptioncó WHAT + WHEN - Không có
<>ở bất kỳ đâu - Instructions rõ + actionable
- Có error handling
- Có examples
- References link rõ
- Test trigger câu rõ ràng
- Test trigger câu paraphrase
- Test không trigger câu unrelated
- Functional tests pass
- Tool integration ok (nếu có)
- Zip folder
- Test trong hội thoại thật
- Theo dõi under/over trigger
- Thu feedback
- Iterate description + instructions
- Update version trong metadata
Required:
---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific trigger phrases.
---All optional fields (gợi ý):
---
name: my-skill
description: ...
license: MIT
compatibility: Claude.ai / Claude Code. Requires network access.
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
author: Company Name
version: 1.0.0
mcp-server: server-name
category: productivity
tags: [project-management, automation]
documentation: https://example.com/docs
support: support@example.com
---Đây là mẫu “đủ dùng”: có trigger, có steps, có examples, có troubleshooting.
---
name: sprint-planning-assistant
description: Lập kế hoạch sprint end-to-end (phân rã công việc, ước lượng, ưu tiên, tạo checklist). Dùng khi user nói "plan sprint", "sprint tasks", "create tickets", "đánh backlog".
metadata:
version: 0.1.0
category: productivity
---
# Sprint Planning Assistant
## Instructions
### Step 1: Clarify scope (2–4 câu hỏi)
- Sprint length? Team size/capacity?
- Goal của sprint?
- Constraints: deadline, dependencies?
### Step 2: Build plan
- Đề xuất danh sách tasks (có ưu tiên)
- Mỗi task có: owner, estimate, acceptance criteria
### Step 3: Quality check
- Đủ coverage cho goal chưa?
- Có task nào mơ hồ không? (viết lại)
- Có rủi ro lớn nào cần spike không?
## Examples
### Example 1
User says: "Help me plan this sprint for checkout refactor"
Actions:
1. Ask scope questions
2. Propose prioritized tasks
3. Add acceptance criteria + risks
Result: Sprint plan ready-to-copy
## Troubleshooting
### Problem: User không có đủ context
Cause: Thiếu input (capacity, goal)
Solution: quay lại Step 1, hỏi tối thiểu 3 câu, không đoán bừa.Anthropic Resources:
- Best Practices Guide
- Skills Documentation
- API Reference
- MCP Documentation
API / SDK:
- Skills API Quickstart
- Create Custom skills
- Skills in the Agent SDK
- Introducing Agent Skills
- Engineering Blog: Equipping Agents for the Real World
- Skills Explained
- How to Create Skills for Claude
- Building Skills for Claude Code
- Improving Frontend Design through Skills
- Public skills repository:
anthropics/skills - Partner Skills Directory: skills từ Asana, Atlassian, Canva, Figma, Sentry, Zapier…
skill-creatorskill: generate/review/iterate skills nhanh- Validation: nhờ
skill-creatorreview + checklist ở Appendix A
- Community forums / Discord (Claude Developers)
- Bug reports:
anthropics/skills/issues(kèm skill name + error message + steps to reproduce)