Tao Custom Skills cho Claude Code — Mo rong kha nang voi SKILL.md

Claude Code mạnh mẽ sẵn, nhưng sức mạnh thật sự đến khi bạn tùy chỉnh nó cho workflow riêng của mình. Custom Skills cho phép bạn đóng gói các tập chỉ dẫn và script thành các khả năng có thể tái sử dụng — giống như tạo plugin cho chính Claude Code.

Custom Skills là gì?

Một Custom Skill là một gói bao gồm instructions (hướng dẫn) và scripts (các đoạn mã thực thi) mà bạn định nghĩa để Claude Code thực hiện một nhiệm vụ cụ thể. Thay vì giải thích lại cách deploy, cách generate docs hay cách seed database mỗi lần, bạn tạo một skill một lần và gọi lại bất cứ khi nào cần.

Thành phần của một Skill

• SKILL.md: File chính định nghĩa tên, mô tả, khi nào kích hoạt, và hướng dẫn chi tiết cho Claude
• Scripts: Các file Python, Bash hoặc JavaScript hỗ trợ thực thi các tác vụ cụ thể
• Resources: Template, config files, hoặc bất kỳ tài liệu tham khảo nào

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

Skills được lưu trong thư mục .claude/skills/ của project:

.claude/
  skills/
    deploy/
      SKILL.md
      deploy.sh
      health-check.py
    generate-docs/
      SKILL.md
      generate.py
      templates/
        api-doc.md
    seed-database/
      SKILL.md
      seed.py
      fixtures/
        users.json
        products.json

Mỗi thư mục con trong .claude/skills/ là một skill độc lập. Claude Code tự động nhận diện các skill dựa trên file SKILL.md trong mỗi thư mục.

Định dạng SKILL.md

File SKILL.md là "bộ não" của skill. Nó cho Claude biết skill này làm gì, khi nào nên dùng, và cách thực hiện. Đây là cấu trúc chuẩn:

# Skill: [Ten Skill]

## Description
Mo ta ngan gon skill lam gi va giai quyet van de gi.

## Trigger
Khi nao Claude nen tu dong kich hoat skill nay.
Vi du: "Khi nguoi dung yeu cau deploy", "Khi nguoi dung noi generate docs"

## Instructions
Huong dan chi tiet tung buoc Claude can lam khi skill duoc kich hoat.

### Buoc 1: [Ten buoc]
Chi tiet cach thuc hien...

### Buoc 2: [Ten buoc]
Chi tiet cach thuc hien...

## Scripts
- `deploy.sh` — Script chinh de thuc thi deploy
- `health-check.py` — Kiem tra suc khoe sau deploy

## Notes
Luu y quan trong, truong hop dac biet, canh bao.

Tạo Skill đầu tiên: Auto Deploy

Hãy tạo một skill tự động deploy ứng dụng lên server. Đây là ví dụ thực tế bạn có thể áp dụng ngay.

Bước 1: Tạo thư mục skill

mkdir -p .claude/skills/deploy

Bước 2: Viết SKILL.md

# Skill: Auto Deploy

## Description
Tu dong deploy ung dung len production server. Bao gom build,
test, deploy va health check.

## Trigger
Kich hoat khi nguoi dung yeu cau "deploy", "push to production",
hoac "release".

## Prerequisites
- SSH key da duoc cau hinh cho server production
- Docker da cai dat tren server
- File .env.production da ton tai

## Instructions

### Buoc 1: Pre-deploy checks
- Chay `npm run lint` de kiem tra loi code
- Chay `npm run test` de dam bao tests pass
- Kiem tra branch hien tai la `main`
- Kiem tra khong co uncommitted changes

### Buoc 2: Build
- Chay `npm run build`
- Kiem tra thu muc build/dist da duoc tao thanh cong
- Ghi lai build version tu package.json

### Buoc 3: Deploy
- Chay script `.claude/skills/deploy/deploy.sh`
- Script se:
  1. SSH vao server
  2. Pull code moi nhat
  3. Build Docker image
  4. Restart container voi zero-downtime

### Buoc 4: Health check
- Chay `.claude/skills/deploy/health-check.py`
- Kiem tra endpoint /health tra ve 200
- Kiem tra response time duoi 500ms
- Neu fail, tu dong rollback

### Buoc 5: Notification
- In ra ket qua deploy: thanh cong hoac that bai
- Ghi lai deploy log vao .claude/skills/deploy/logs/

## Rollback
Neu deploy that bai:
1. SSH vao server
2. Chay `docker rollback` de quay ve version truoc
3. Kiem tra health check lai
4. Bao nguoi dung biet can xu ly thu cong

## Notes
- Chi deploy tu branch main
- Luon chay tests truoc khi deploy
- Giu lai 3 phien ban cu de rollback

Bước 3: Tạo deploy script

#!/bin/bash
# .claude/skills/deploy/deploy.sh

set -euo pipefail

SERVER="user@production-server.com"
APP_DIR="/opt/app"
IMAGE_NAME="myapp"

echo "=== Starting deployment ==="

# SSH vao server va deploy
ssh $SERVER << 'REMOTE'
  cd /opt/app

  # Pull code moi nhat
  git pull origin main

  # Build Docker image moi
  docker build -t myapp:latest .

  # Zero-downtime restart
  docker compose up -d --no-deps --build app

  # Don dep images cu
  docker image prune -f

  echo "Deploy completed at $(date)"
REMOTE

echo "=== Deployment finished ==="

Bước 4: Tạo health check script

# .claude/skills/deploy/health-check.py
import requests
import sys
import time

HEALTH_URL = "https://myapp.com/health"
MAX_RETRIES = 5
RETRY_DELAY = 3  # seconds

def check_health():
    for attempt in range(1, MAX_RETRIES + 1):
        try:
            start = time.time()
            response = requests.get(HEALTH_URL, timeout=10)
            elapsed = (time.time() - start) * 1000

            if response.status_code == 200 and elapsed < 500:
                print(f"Health check passed (attempt {attempt})")
                print(f"  Status: {response.status_code}")
                print(f"  Response time: {elapsed:.0f}ms")
                return True
            else:
                print(f"Attempt {attempt}: status={response.status_code}, time={elapsed:.0f}ms")
        except requests.exceptions.RequestException as e:
            print(f"Attempt {attempt}: Connection error - {e}")

        if attempt < MAX_RETRIES:
            time.sleep(RETRY_DELAY)

    print("Health check FAILED after all retries")
    return False

if __name__ == "__main__":
    success = check_health()
    sys.exit(0 if success else 1)

Ví dụ 2: Generate API Documentation

Skill thứ hai tự động tạo tài liệu API từ source code:

# Skill: Generate API Docs

## Description
Tu dong tao tai lieu API tu cac route handlers va JSDoc comments
trong source code. Xuat ra file Markdown chuan.

## Trigger
Kich hoat khi nguoi dung yeu cau "generate docs", "update API docs",
hoac "tao tai lieu API".

## Instructions

### Buoc 1: Scan routes
- Tim tat ca file trong `src/routes/` va `src/controllers/`
- Doc JSDoc comments tren moi route handler
- Trich xuat: HTTP method, path, parameters, request body, response

### Buoc 2: Parse models
- Tim tat ca file trong `src/models/`
- Trich xuat schema definitions
- Map voi cac route da tim duoc

### Buoc 3: Generate documentation
- Chay script `.claude/skills/generate-docs/generate.py`
- Script doc source code va tao Markdown file
- Moi endpoint co: description, parameters, request/response examples

### Buoc 4: Output
- Luu file tai `docs/api-reference.md`
- In ra so luong endpoints da document
- Liet ke cac endpoints thieu JSDoc de nguoi dung bo sung

## Template
Su dung template tai `.claude/skills/generate-docs/templates/api-doc.md`

## Notes
- Chi scan cac file .ts va .js
- Bo qua cac file test va file bat dau bang _
- Giu lai noi dung custom ma nguoi dung da them vao docs truoc do

Script generate docs

# .claude/skills/generate-docs/generate.py
import os
import re
import json

ROUTES_DIR = "src/routes"
OUTPUT_FILE = "docs/api-reference.md"

def parse_route_file(filepath):
    """Doc file route va trich xuat thong tin endpoint."""
    endpoints = []
    with open(filepath, 'r') as f:
        content = f.read()

    # Tim cac route definitions
    pattern = r'/**s*(.*?)*/s*router.(get|post|put|delete)s*(s*['"]([^'"]+)['"]'
    matches = re.findall(pattern, content, re.DOTALL)

    for doc, method, path in matches:
        endpoints.append({
            'method': method.upper(),
            'path': path,
            'description': doc.strip().replace('* ', '').replace('
', ' ')
        })

    return endpoints

def generate_markdown(all_endpoints):
    """Tao file Markdown tu danh sach endpoints."""
    lines = ["# API Reference
"]
    lines.append(f"Generated automatically. Total endpoints: {len(all_endpoints)}
")

    for ep in all_endpoints:
        lines.append(f"## {ep['method']} {ep['path']}
")
        lines.append(f"{ep['description']}
")
        lines.append("---
")

    return '
'.join(lines)

def main():
    all_endpoints = []
    for root, dirs, files in os.walk(ROUTES_DIR):
        for f in files:
            if f.endswith(('.ts', '.js')) and not f.startswith('_'):
                filepath = os.path.join(root, f)
                endpoints = parse_route_file(filepath)
                all_endpoints.extend(endpoints)

    markdown = generate_markdown(all_endpoints)

    os.makedirs(os.path.dirname(OUTPUT_FILE), exist_ok=True)
    with open(OUTPUT_FILE, 'w') as f:
        f.write(markdown)

    print(f"Generated docs for {len(all_endpoints)} endpoints")
    print(f"Output: {OUTPUT_FILE}")

if __name__ == "__main__":
    main()

Ví dụ 3: Database Seed

Skill thứ ba tự động tạo dữ liệu mẫu cho môi trường development:

# Skill: Database Seed

## Description
Tao du lieu mau cho database development. Ho tro tao users,
products, orders va cac du lieu lien quan voi so luong tuy chinh.

## Trigger
Kich hoat khi nguoi dung yeu cau "seed database", "tao du lieu mau",
hoac "populate dev database".

## Instructions

### Buoc 1: Kiem tra moi truong
- Xac nhan dang o moi truong development (KHONG BAO GIO seed production)
- Kiem tra database connection
- Hoi nguoi dung co muon xoa du lieu cu truoc khi seed khong

### Buoc 2: Chon du lieu can seed
Hoi nguoi dung muon seed nhung gi:
- Users (default: 50)
- Products (default: 100)
- Orders (default: 200)
- Reviews (default: 500)
- Hoac "all" de seed tat ca voi so luong default

### Buoc 3: Thuc thi seed
- Chay `.claude/skills/seed-database/seed.py` voi arguments phu hop
- Script se doc fixtures va tao du lieu voi faker

### Buoc 4: Xac nhan
- In ra so luong records da tao cho tung bang
- Kiem tra foreign key constraints da dung
- In ra sample records de nguoi dung xac nhan

## Safety
- KHONG BAO GIO chay tren production database
- Luon backup truoc khi xoa du lieu cu
- Kiem tra bien NODE_ENV hoac APP_ENV truoc khi chay

Script seed database

# .claude/skills/seed-database/seed.py
import json
import os
import sys
import random
from datetime import datetime, timedelta

# Kiem tra moi truong
env = os.getenv('NODE_ENV', 'development')
if env == 'production':
    print("KHONG THE SEED PRODUCTION DATABASE!")
    sys.exit(1)

def load_fixtures(filename):
    """Doc du lieu mau tu file JSON."""
    filepath = os.path.join(os.path.dirname(__file__), 'fixtures', filename)
    with open(filepath, 'r') as f:
        return json.load(f)

def generate_users(count=50):
    """Tao du lieu users."""
    templates = load_fixtures('users.json')
    users = []
    for i in range(count):
        template = random.choice(templates)
        users.append({
            'id': i + 1,
            'name': f"{template['first_name']} {template['last_name']}",
            'email': f"user{i+1}@example.com",
            'role': random.choice(['customer', 'admin']) if i < 3 else 'customer',
            'created_at': (datetime.now() - timedelta(days=random.randint(1, 365))).isoformat()
        })
    return users

def generate_products(count=100):
    """Tao du lieu products."""
    templates = load_fixtures('products.json')
    products = []
    for i in range(count):
        template = random.choice(templates)
        products.append({
            'id': i + 1,
            'name': f"{template['name']} V{random.randint(1,5)}",
            'price': round(random.uniform(10, 500) * 1000, -3),
            'category': template.get('category', 'general'),
            'stock': random.randint(0, 200),
            'created_at': datetime.now().isoformat()
        })
    return products

def generate_orders(count=200, user_count=50, product_count=100):
    """Tao du lieu orders."""
    orders = []
    for i in range(count):
        orders.append({
            'id': i + 1,
            'user_id': random.randint(1, user_count),
            'product_id': random.randint(1, product_count),
            'quantity': random.randint(1, 5),
            'status': random.choice(['pending', 'paid', 'shipped', 'delivered']),
            'created_at': (datetime.now() - timedelta(days=random.randint(0, 90))).isoformat()
        })
    return orders

def main():
    # Parse arguments
    counts = {
        'users': int(sys.argv[1]) if len(sys.argv) > 1 else 50,
        'products': int(sys.argv[2]) if len(sys.argv) > 2 else 100,
        'orders': int(sys.argv[3]) if len(sys.argv) > 3 else 200,
    }

    print(f"Seeding database ({env} environment)...")

    users = generate_users(counts['users'])
    print(f"  Created {len(users)} users")

    products = generate_products(counts['products'])
    print(f"  Created {len(products)} products")

    orders = generate_orders(counts['orders'], counts['users'], counts['products'])
    print(f"  Created {len(orders)} orders")

    print(f"
Seed completed successfully!")
    print(f"Sample user: {json.dumps(users[0], indent=2)}")

if __name__ == "__main__":
    main()

Chia sẻ Skills trong Team

Một trong những lợi ích lớn nhất của Custom Skills là khả năng chia sẻ giữa các thành viên team. Vì skills nằm trong thư mục .claude/skills/ và được commit vào git, mọi người trong team đều có thể sử dụng cùng một bộ skills.

Quy trình chia sẻ

1. Tạo skill: Một thành viên viết skill và test kỹ
2. Review: Team review SKILL.md và scripts như code bình thường
3. Merge: Merge vào branch chính
4. Sử dụng: Tất cả thành viên pull và có thể sử dụng ngay

Version control cho Skills

# Cau truc git-friendly
.claude/
  skills/
    deploy/
      SKILL.md          # Huong dan — luon duoc review
      deploy.sh         # Script — can test truoc khi merge
      health-check.py   # Script — can test truoc khi merge
      CHANGELOG.md      # Lich su thay doi cua skill
    .gitignore          # Bo qua logs, temp files

# .claude/skills/.gitignore
*.log
__pycache__/
.env
temp/

Convention cho team

• Mỗi skill phải có SKILL.md với format chuẩn
• Scripts phải có error handling và exit codes rõ ràng
• Không hardcode credentials — dùng biến môi trường
• Ghi CHANGELOG khi update skill
• Viết comments bằng tiếng Anh trong scripts để team quốc tế đọc được

Testing Skills trước khi sử dụng

Trước khi commit một skill mới, bạn cần test kỹ lưỡng:

Test thủ công

# 1. Kich hoat skill bang cach noi voi Claude Code
# Vi du: "deploy ung dung len production"
# Claude se doc SKILL.md va thuc hien theo huong dan

# 2. Kiem tra Claude co doc dung SKILL.md khong
# Hoi: "Ban dang su dung skill nao? Mo ta cac buoc."

# 3. Test tung script doc lap
python .claude/skills/deploy/health-check.py
bash .claude/skills/deploy/deploy.sh

# 4. Test edge cases
# - Chay khi khong co internet
# - Chay khi database chua khoi dong
# - Chay voi quyen han thieu

Checklist review skill

• SKILL.md có rõ ràng và đầy đủ không?
• Trigger conditions có chính xác không? (Không bị kích hoạt nhầm)
• Scripts có error handling không?
• Có safety checks không? (Đặc biệt với production)
• Có log output để debug không?
• Dependencies đã được ghi rõ chưa?

Skill Marketplace và Cộng đồng

Ngoài việc tạo skills riêng, bạn có thể tham khảo và sử dụng skills từ cộng đồng. Một số nguồn:

• GitHub repositories: Tìm kiếm "claude code skills" trên GitHub để thấy các skill open-source
• Team internal registry: Tạo một repo riêng chứa các skills chuẩn của công ty
• Claude Code community: Tham gia các diễn đàn và group để chia sẻ skills

Cài đặt skill từ bên ngoài

# Clone skill tu GitHub
git clone https://github.com/example/claude-skill-deploy.git temp-skill

# Copy vao project
cp -r temp-skill/.claude/skills/deploy .claude/skills/

# Doc SKILL.md de hieu cach su dung
cat .claude/skills/deploy/SKILL.md

# Tuy chinh theo nhu cau cua project
# Sua SERVER, APP_DIR, va cac config khac

# Xoa temp
rm -rf temp-skill

Những sai lầm thường gặp

1. Skill quá rộng

Một skill nên làm tốt một việc. Đừng tạo skill "làm mọi thứ" — hãy chia thành nhiều skill nhỏ, mỗi skill có trách nhiệm rõ ràng.

2. Không có safety checks

Đặc biệt với các skill ảnh hưởng đến production (deploy, database operations), luôn kiểm tra môi trường và yêu cầu xác nhận trước khi thực hiện hành động nguy hiểm.

3. Hardcode thông tin nhạy cảm

Không bao giờ ghi trực tiếp password, API key hay server address vào SKILL.md hoặc scripts. Dùng biến môi trường và file .env (đã được gitignore).

4. Không cập nhật SKILL.md

Khi scripts thay đổi nhưng SKILL.md không được cập nhật, Claude sẽ làm theo hướng dẫn cũ và gặp lỗi. Luôn cập nhật đồng bộ giữa SKILL.md và scripts.

5. Trigger quá chung chung

Trigger như "khi người dùng yêu cầu bất cứ điều gì liên quan đến code" sẽ khiến skill bị kích hoạt nhầm. Viết trigger cụ thể: "khi người dùng yêu cầu deploy lên staging hoặc production server".

Skill Dependencies và Environment Setup

Nhiều skills cần các thư viện hoặc công cụ bên ngoài để hoạt động. Bạn cần quản lý dependencies một cách có hệ thống để đảm bảo skill chạy được trên mọi máy của thành viên team.

File requirements cho Python skills

# .claude/skills/requirements.txt
# Dung chung cho tat ca skills
requests>=2.28.0
python-dotenv>=1.0.0

# Cho skill deploy
paramiko>=3.0.0    # SSH connections

# Cho skill generate-docs
pyyaml>=6.0.0      # Parse YAML configs
jinja2>=3.1.0      # Template rendering

# Cho skill seed-database
faker>=18.0.0      # Generate fake data
psycopg2-binary>=2.9.0  # PostgreSQL connection

Setup script tự động

#!/bin/bash
# .claude/skills/setup.sh
# Chay mot lan khi clone project hoac khi co skill moi

set -euo pipefail

echo "Setting up Claude Code Skills environment..."

# Tao virtual environment neu chua co
if [ ! -d ".claude/skills/.venv" ]; then
    python3 -m venv .claude/skills/.venv
    echo "Created virtual environment"
fi

# Kich hoat venv va cai dependencies
source .claude/skills/.venv/bin/activate
pip install -r .claude/skills/requirements.txt --quiet

echo "All dependencies installed"

# Kiem tra cac bien moi truong can thiet
required_vars=("SSH_KEY_PATH" "DATABASE_URL")
for var in "${required_vars[@]}"; do
    if [ -z "${!var:-}" ]; then
        echo "WARNING: $var chua duoc set"
    fi
done

echo "Setup completed"

Khi một thành viên mới tham gia project, họ chỉ cần chạy một lệnh duy nhất để cài đặt môi trường cho tất cả skills. Điều này giảm thời gian onboarding và tránh lỗi "chạy trên máy tôi được" (works on my machine).

Xử lý biến môi trường trong skills

# .claude/skills/.env.example (commit vao git)
SSH_KEY_PATH=~/.ssh/id_rsa
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DEPLOY_SERVER=user@production.example.com

# .claude/skills/.env (KHONG commit, moi nguoi co rieng)
SSH_KEY_PATH=/home/dev/.ssh/deploy_key
DATABASE_URL=postgresql://dev:secret@localhost:5432/myapp_dev
DEPLOY_SERVER=admin@10.0.1.50

Skill Chaining — Kết nối nhiều Skills

Đôi khi bạn muốn chạy nhiều skills liên tiếp. Ví dụ: chạy tests, generate docs, rồi deploy. Skill chaining cho phép bạn định nghĩa các workflow gồm nhiều skills:

# Skill: Release Pipeline

## Description
Chay toan bo quy trinh release: test, build, generate docs, deploy.

## Trigger
Kich hoat khi nguoi dung yeu cau "release", "ship it",
hoac "chay release pipeline".

## Instructions

### Buoc 1: Chay test suite
Kich hoat skill "test" (neu co) hoac chay truc tiep:
- npm run test
- Neu co test that bai, DUNG LAI va bao nguoi dung

### Buoc 2: Generate docs
Kich hoat skill "generate-docs":
- Cap nhat API reference tu source code
- Commit thay doi docs neu co

### Buoc 3: Build
- Chay npm run build
- Kiem tra output khong co errors

### Buoc 4: Deploy
Kich hoat skill "deploy":
- Deploy len staging truoc
- Chay health check
- Neu staging OK, hoi nguoi dung co muon deploy production khong

### Buoc 5: Post-release
- Tao git tag voi version tu package.json
- In ra release notes tu cac commits ke tu tag truoc

Skill chaining giúp bạn tự động hóa các quy trình phức tạp bằng cách kết hợp các skills đơn giản đã có. Mỗi skill vẫn được maintain độc lập, nhưng có thể làm việc cùng nhau khi cần.

Nâng cao: Skill kết hợp với Hooks

Bạn có thể kết hợp skills với Claude Code hooks để tự động kích hoạt skill tại các thời điểm cụ thể:

// .claude/settings.json
{
  "hooks": {
    "pre-commit": {
      "command": "python .claude/skills/generate-docs/generate.py",
      "description": "Tu dong cap nhat API docs truoc moi commit"
    },
    "post-merge": {
      "command": "python .claude/skills/seed-database/seed.py 10 20 50",
      "description": "Seed du lieu mau sau khi merge branch moi"
    }
  }
}

Với hooks, skills không chỉ được gọi thủ công mà còn có thể chạy tự động theo các sự kiện trong workflow phát triển.

Tóm tắt

Custom Skills biến Claude Code từ một công cụ thông minh thành một trợ lý được cá nhân hóa hoàn toàn cho project và team của bạn. Các điểm chính:

• SKILL.md là file cốt lõi định nghĩa hành vi của skill
• Kết hợp instructions và scripts để tự động hóa tác vụ phức tạp
• Chia sẻ skills qua git để cả team cùng hưởng lợi
• Luôn test kỹ và có safety checks cho các skill nguy hiểm
• Giữ skill nhỏ gọn, mỗi skill làm tốt một việc

Khám phá thêm các hướng dẫn thực hành Claude Code tại Thư viện Ứng dụng.