Best Practices

Các nguyên tắc để tạo Agent Skills hiệu quả và an toàn.

Best Practices

1. Giữ Skill tập trung

❌ Sai: Một skill làm mọi thứ

---
name: everything-skill
description: Xử lý documents, phân tích dữ liệu, tạo presentations, gửi email...
---

✅ Đúng: Nhiều skills chuyên biệt

# skill 1
name: document-formatter
description: Format documents theo brand guidelines

# skill 2
name: data-analyzer
description: Phân tích dữ liệu sales theo workflow công ty

# skill 3
name: slide-creator
description: Tạo presentations từ data analysis results

Tip: Skills tập trung dễ maintain và compose với nhau hơn.

2. Viết Description rõ ràng

Description là yếu tố quan trọng nhất - Claude dựa vào đây để quyết định khi nào invoke skill.

❌ Mơ hồ:

description: Xử lý dữ liệu

✅ Cụ thể:

description: Phân tích dữ liệu bán hàng theo quý, tạo báo cáo với biểu đồ revenue và so sánh YoY

3. Bắt đầu đơn giản

Không cần scripts phức tạp ngay từ đầu:

Phiên bản 1 - Chỉ có instructions:

---
name: meeting-notes
description: Format meeting notes theo template công ty
---

# Meeting Notes Formatter

## Template

### [Ngày] - [Tên cuộc họp]

**Người tham dự:** [Danh sách]

**Agenda:**
1. ...

**Action Items:**
- [ ] Task - @người - Deadline

**Next Steps:**
- ...

Phiên bản 2 - Thêm scripts khi cần:

meeting-notes/
├── SKILL.md
└── scripts/
    └── export_to_notion.py  # Thêm sau khi v1 hoạt động tốt

4. Sử dụng Examples

Examples giúp Claude hiểu output mong muốn:

## Examples

### Input
"Tóm tắt meeting hôm nay về product launch"

### Output
### 2024-01-15 - Product Launch Planning

**Người tham dự:** An, Bình, Chi, Dung

**Agenda:**
1. Review timeline
2. Assign responsibilities
3. Budget discussion

**Action Items:**
- [ ] Finalize design - @An - 2024-01-20
- [ ] Setup marketing campaign - @Bình - 2024-01-22

**Next Steps:**
- Họp review tiến độ vào thứ 6

5. Test liên tục

graph LR
    A[Viết SKILL.md] --> B[Test local]
    B --> C{Hoạt động?}
    C -->|Không| A
    C -->|Có| D[Upload]
    D --> E[Test với prompts khác nhau]
    E --> F{Invoke đúng?}
    F -->|Không| G[Cập nhật description]
    G --> D
    F -->|Có| H[✅ Done]

Checklist trước khi upload:

• SKILL.md có YAML frontmatter hợp lệ
• Description dưới 200 ký tự và mô tả rõ use case
• Tất cả files được reference đều tồn tại
• Scripts chạy được (nếu có)

Test sau khi upload:

• Thử nhiều prompts khác nhau
• Xem thinking process để confirm skill được load
• Kiểm tra output có đúng format mong muốn

6. Skills có thể compose

Skills không thể trực tiếp gọi nhau, nhưng Claude tự động sử dụng nhiều skills cùng lúc:

User: "Phân tích dữ liệu sales Q4 và tạo slide báo cáo theo brand guidelines"

Claude:
  [Load: data-analyzer skill]
  [Load: slide-creator skill]
  [Load: brand-guidelines skill]

  → Kết hợp cả 3 skills để hoàn thành task

Security Considerations

⚠️ Không hardcode sensitive data

❌ Nguy hiểm:

scripts/api_client.py

API_KEY = "sk-1234567890abcdef"  # ❌ NEVER DO THIS

✅ An toàn:

import os

API_KEY = os.environ.get("API_KEY")  # Lấy từ environment

⚠️ Review skills trước khi enable

Skills có thể chứa code thực thi. Chỉ enable skills từ nguồn tin cậy:

Nguồn	Độ tin cậy
Anthropic Skills	✅ Cao
Partner Skills (Notion, Figma…)	✅ Cao
Tự tạo	✅ Cao (bạn kiểm soát)
Download từ internet	⚠️ Cần review kỹ

⚠️ Sử dụng MCP cho external services

Thay vì hardcode API calls trong scripts, dùng MCP:

---
name: notion-manager
description: Quản lý Notion pages
# Không cần API key trong skill
# MCP connection xử lý authentication
---

⚠️ Giới hạn file access

Skills chỉ nên access files trong sandbox:

# ✅ Tốt
with open("output/report.pdf", "wb") as f:
    f.write(pdf_data)

# ❌ Tránh
with open("/etc/passwd", "r") as f:  # System files
    ...

Agent Skills Open Standard

Anthropic khuyến khích theo agentskills.io - tiêu chuẩn mở cho Agent Skills:

• Skills tạo theo chuẩn này có thể hoạt động trên nhiều platforms
• Dễ share và tái sử dụng
• Cộng đồng có thể đóng góp

Tài liệu tham khảo

• Skill authoring best practices - Claude Docs
• GitHub: anthropics/skills
• Agent Skills Open Standard