---
name: skill-authoring
description: Phương pháp viết Agent Skills chuyên nghiệp. Sử dụng khi tạo mới, cập nhật, hoặc review Agent Skills theo chuẩn AgentSkills.io và best practices của dự án GoodGo.
compatibility: "Antigravity, Claude Code, hoặc các agent khác hỗ trợ Agent Skills spec"
metadata:
  author: Velik Ho
  version: "1.0"
  references: "agentskills.io, antigravity.google"
---

# Phương Pháp Viết Agent Skills

## 1. Tổng Quan / Overview

Agent Skills là một định dạng mở, nhẹ để mở rộng khả năng của AI agents với kiến thức chuyên môn và quy trình làm việc có thể tái sử dụng.

**Ưu điểm chính:**
- **Self-documenting**: Skill author hoặc user có thể đọc và hiểu ngay chức năng
- **Extensible**: Từ đơn giản (chỉ text) đến phức tạp (scripts, assets, templates)
- **Portable**: Dễ chỉnh sửa, version control, và chia sẻ

## 2. Cấu Trúc Thư Mục / Directory Structure

```
skill-name/
├── SKILL.md              # BẮT BUỘC: Hướng dẫn + metadata
├── scripts/              # TÙY CHỌN: Code thực thi
│   ├── extract.py
│   └── validate.sh
├── references/           # TÙY CHỌN: Tài liệu tham khảo chi tiết
│   ├── REFERENCE.md
│   └── examples.md
└── assets/               # TÙY CHỌN: Templates, diagrams, data files
    ├── template.json
    └── diagram.png
```

### Quy tắc đặt tên thư mục
- **Lowercase**: Chỉ dùng chữ thường và dấu gạch ngang (`a-z`, `-`)
- **Không bắt đầu/kết thúc bằng `-`**
- **Không có `--` liên tiếp**
- **Tên thư mục PHẢI khớp với field `name` trong frontmatter**

**Ví dụ hợp lệ:**
```
✅ pdf-processing/
✅ data-analysis/
✅ api-design/
```

**Ví dụ KHÔNG hợp lệ:**
```
❌ PDF-Processing/    # Có chữ hoa
❌ -pdf-processing/   # Bắt đầu bằng -
❌ pdf--processing/   # Có -- liên tiếp
```

## 3. Format SKILL.md

### 3.1 Frontmatter (BẮT BUỘC)

SKILL.md PHẢI bắt đầu với YAML frontmatter:

```yaml
---
name: skill-name
description: Mô tả ngắn gọn về skill làm gì và khi nào nên sử dụng.
---
```

#### Field `name` (BẮT BUỘC)
- Độ dài: 1-64 ký tự
- Format: lowercase alphanumeric + hyphens
- PHẢI khớp với tên thư mục chứa skill

#### Field `description` (BẮT BUỘC)
- Độ dài: 1-1024 ký tự
- Nên mô tả: (1) Skill làm gì, (2) Khi nào sử dụng
- Bao gồm keywords giúp agent xác định tasks liên quan

**Ví dụ TỐT:**
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
```

**Ví dụ XẤU:**
```yaml
description: Helps with PDFs.
```

#### Fields Tùy Chọn

```yaml
---
name: api-design
description: RESTful API design standards for GoodGo microservices...
license: Apache-2.0
compatibility: "express>=4.18, zod>=3, @types/express"
metadata:
  author: Velik Ho
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---
```

| Field | Mục đích | Ghi chú |
|-------|----------|---------|
| `license` | Giấy phép áp dụng | Giữ ngắn gọn |
| `compatibility` | Yêu cầu môi trường | Products, packages, system deps |
| `metadata` | Thông tin bổ sung | Map of key-value strings |
| `allowed-tools` | Tools được pre-approved | Experimental feature |

### 3.2 Body Content

Phần body chứa hướng dẫn chi tiết cho agent. Nên bao gồm:

1. **When to Use** - Khi nào nên sử dụng skill này
2. **Step-by-step Instructions** - Hướng dẫn từng bước
3. **Examples** - Ví dụ input/output
4. **Common Mistakes** - Lỗi thường gặp và cách tránh
5. **Quick Reference** - Bảng tham chiếu nhanh
6. **Resources** - Links đến tài liệu liên quan

**Khuyến nghị độ dài:** < 5000 tokens cho body content

### 3.3 File Size Guidelines / Hướng Dẫn Kích Thước File

**Token Estimation / Ước Lượng Token:**
- **Rule of thumb**: 1 line ≈ 10-20 tokens
- **Recommended max body content**: < 5,000 tokens (~250-500 lines)
- **Hard limit**: Never exceed 10,000 tokens (~500-1,000 lines)

**When to split into references / Khi nào tách ra references:**

| Lines | Bytes | Action |
|-------|-------|--------|
| < 300 | < 12KB | ✅ Keep in SKILL.md |
| 300-500 | 12-20KB | ⚠️ Consider extracting detailed sections to references/ |
| > 500 | > 20KB | 🚨 MUST split - move detailed content to references/ |

**Example oversized sections to extract / Ví dụ các phần nên tách:**
- Detailed API templates / Mẫu API chi tiết
- Extensive code examples / Ví dụ code dài
- Tool configuration files / File cấu hình công cụ
- Migration guides / Hướng dẫn migration
- Comprehensive reference tables / Bảng tham chiếu toàn diện
- Troubleshooting guides / Hướng dẫn khắc phục sự cố

**Benefits of splitting / Lợi ích khi tách:**
1. **Progressive Disclosure**: Agent loads only what's needed
2. **Better Performance**: Faster skill discovery and activation
3. **Easier Maintenance**: Update specific guides without touching core
4. **Clearer Structure**: Main skill stays focused on essentials

## 4. Progressive Disclosure

Agent Skills sử dụng mô hình "tiết lộ dần dần" để tối ưu context:

| Giai đoạn | Nội dung | Tokens |
|-----------|----------|--------|
| **1. Metadata** | `name` + `description` | ~100 tokens |
| **2. Instructions** | Toàn bộ SKILL.md body | < 5000 tokens |
| **3. Resources** | Files trong scripts/, references/, assets/ | Theo nhu cầu |

**Workflow của Agent:**
1. **Discovery**: Load metadata của tất cả skills khi khởi động
2. **Activation**: Khi task khớp với description, load full SKILL.md
3. **Execution**: Gọi scripts hoặc load resources khi cần

## 5. File References

Tham chiếu đến files khác trong SKILL.md:

```markdown
See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script: scripts/extract.py
```

Agent sẽ tự động load các files được tham chiếu khi cần.

## 6. Optional Directories

### 6.1 scripts/

Chứa code thực thi. Scripts nên:
- **Self-contained** hoặc document dependencies rõ ràng
- **Error messages** hữu ích
- **Edge cases** xử lý gracefully

```python
# scripts/extract.py
#!/usr/bin/env python3
"""
PDF text extraction script.
Dependencies: pip install pdfplumber
"""

import sys
import pdfplumber

def extract_text(pdf_path):
    try:
        with pdfplumber.open(pdf_path) as pdf:
            return '\n'.join(page.extract_text() for page in pdf.pages)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: extract.py <pdf_path>", file=sys.stderr)
        sys.exit(1)
    print(extract_text(sys.argv[1]))
```

### 6.2 references/

Tài liệu kỹ thuật chi tiết:
- `REFERENCE.md` - Technical reference đầy đủ
- `FORMS.md` - Form templates
- Domain-specific files (`finance.md`, `legal.md`, etc.)

### 6.3 assets/

Templates và resources:
- Document templates
- Configuration templates
- Images/diagrams
- Lookup tables, schemas

## 7. Best Practices cho GoodGo

### 7.1 Cấu Trúc Content Chuẩn

```markdown
---
name: skill-name
description: Mô tả skill. Use for X, Y, Z.
compatibility: "dependencies"
---

# Skill Title

## When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:
- Condition 1
- Condition 2

## Core Principles / Nguyên Tắc Cốt Lõi

1. **Principle 1**: Explanation
2. **Principle 2**: Explanation

## Key Patterns / Mẫu Chính

### Pattern 1

```typescript
// Code example
```

### Pattern 2

```typescript
// Code example
```

## Common Mistakes / Lỗi Thường Gặp

1. **Mistake 1**: Description
   ```typescript
   // ❌ BAD: Wrong approach
   // ✅ GOOD: Correct approach
   ```

## Quick Reference / Tham Chiếu Nhanh

| Category | Standard |
|----------|----------|
| Item 1 | Value 1 |
| Item 2 | Value 2 |

## Resources / Tài Nguyên

- [Related Skill 1](../related-skill-1/SKILL.md)
- [External Doc](https://example.com)
```

### 7.2 Bilingual Support

GoodGo skills hỗ trợ song ngữ (EN/VI):

**Option 1: Inline (cho headings ngắn)**
```markdown
## Quick Reference / Tham Chiếu Nhanh
```

**Option 2: Bullets (cho explanations)**
```markdown
Use this skill when:
- Creating new API endpoints / Tạo API endpoints mới
- Designing DTOs / Thiết kế DTOs
```

**Option 3: EN first, VI in parentheses**
```markdown
1. **Clear and Concise**: Use simple language (Sử dụng ngôn ngữ đơn giản)
```

### 7.3 Cross-References

Link đến skills liên quan ở cuối file:

```markdown
## Resources

- [API Design](../api-design/SKILL.md) - API patterns
- [Testing Patterns](../testing-patterns/SKILL.md) - Testing best practices
- [Project Rules](../project-rules/SKILL.md) - Coding standards
```

## 8. Validation & Testing

### 8.1 Sử dụng skills-ref

```bash
# Validate skill format
skills-ref validate ./my-skill

# Generate prompt XML
skills-ref to-prompt ./my-skill
```

### 8.2 Checklist Trước Khi Commit

- [ ] **Metadata validation**:
  - [ ] `name` khớp với tên thư mục
  - [ ] `description` đủ chi tiết (1-1024 chars)
  - [ ] `version` được cập nhật nếu có thay đổi quan trọng
- [ ] **File size check**:
  - [ ] SKILL.md body content < 500 lines (check với `wc -l`)
  - [ ] SKILL.md < 20KB (check với `wc -c`)
  - [ ] Nếu > 500 lines, detailed content đã move sang references/
  - [ ] Nếu > 1000 lines, MANDATORY refactor required
- [ ] **Token estimation**: Body content < 5,000 tokens (estimate ~10-20 tokens/line)
- [ ] **Content quality**:
  - [ ] Code examples đã test và hoạt động
  - [ ] Links đều valid (run `markdown-link-check`)
  - [ ] Có section "When to Use"
  - [ ] Có section "Common Mistakes" (nếu applicable)
  - [ ] Có "Quick Reference" table
  - [ ] Có links đến related skills/resources

### 8.3 Skill Quality Audit / Kiểm Toán Chất Lượng Skill

Run these checks periodically on existing skills / Chạy định kỳ để kiểm tra skills:

**File Size Audit:**
```bash
# Check all skills for size violations (line count)
find .agent/skills -name "SKILL.md" -exec sh -c 'lines=$(wc -l < "$1"); echo "$lines $1"' _ {} \; | sort -rn | head -10

# Show skills > 500 lines (red flag)
find .agent/skills -name "SKILL.md" -exec sh -c 'lines=$(wc -l < "$1"); [ $lines -gt 500 ] && echo "🚨 $lines lines: $1"' _ {} \;

# Show skills 300-500 lines (yellow flag)
find .agent/skills -name "SKILL.md" -exec sh -c 'lines=$(wc -l < "$1"); [ $lines -gt 300 ] && [ $lines -le 500 ] && echo "⚠️  $lines lines: $1"' _ {} \;
```

**Byte Size Audit (rough proxy for tokens):**
```bash
# Check byte size of all skills
find .agent/skills -name "SKILL.md" -exec sh -c 'size=$(wc -c < "$1"); echo "$size bytes $1"' _ {} \; | sort -rn | head -10

# Show skills > 20KB (red flag - likely > 5000 tokens)
find .agent/skills -name "SKILL.md" -exec sh -c 'size=$(wc -c < "$1"); [ $size -gt 20000 ] && echo "🚨 $size bytes: $1"' _ {} \;
```

**Refactoring Criteria / Tiêu Chí Refactor:**
- **Yellow flag** (300-500 lines, 12-20KB): Review and consider splitting
- **Red flag** (> 500 lines, > 20KB): Refactor required, move content to references/
- **Critical** (> 1000 lines, > 40KB): IMMEDIATE action - violates Agent Skills spec

**Example Refactoring:**
```bash
# Before: documentation/SKILL.md (1,451 lines, 40KB)
# After:
#   - documentation/SKILL.md (400 lines, 12KB)
#   - documentation/references/OPENAPI.md
#   - documentation/references/VERSIONING.md
#   - documentation/references/DIAGRAMS.md
#   - documentation/references/API_TABLES.md
#   - documentation/references/CONFIGURATION.md
#   - documentation/references/AUTOMATION.md
```

## 9. Template Skill Mới

```markdown
---
name: new-skill-name
description: Brief description of what this skill does and when to use it. Use for X, Y, Z.
compatibility: "tool/framework requirements if any"
metadata:
  author: Velik Ho
  version: "1.0"
---

# Skill Title / Tiêu Đề Skill

## When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:
- [Condition 1]
- [Condition 2]

## Core Concepts / Khái Niệm Cốt Lõi

### Concept 1

Explanation...

### Concept 2

Explanation...

## Key Patterns / Mẫu Chính

### Pattern Name

```typescript
// Code example with comments
```

## Common Mistakes / Lỗi Thường Gặp

### Mistake 1

**Problem**: Description
**Solution**: How to fix

```typescript
// ❌ BAD
wrongApproach();

// ✅ GOOD
correctApproach();
```

## Quick Reference / Tham Chiếu Nhanh

| Category | Standard/Pattern |
|----------|-----------------|
| [Category 1] | [Value 1] |
| [Category 2] | [Value 2] |

## Resources / Tài Nguyên

- [Related Skill 1](../related-skill-1/SKILL.md)
- [External Documentation](https://example.com)
```

## 10. Security Considerations

Khi viết skills có scripts:

1. **Sandboxing**: Run scripts trong môi trường isolated
2. **Allowlisting**: Chỉ execute scripts từ trusted sources
3. **Confirmation**: Hỏi user trước khi chạy operations nguy hiểm
4. **Logging**: Ghi log tất cả script executions

## Resources / Tài Nguyên

- [AgentSkills.io Specification](https://agentskills.io/specification)
- [AgentSkills.io Integration Guide](https://agentskills.io/integrate-skills)
- [Example Skills on GitHub](https://github.com/anthropics/skills)
- [skills-ref Library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
- [Project Rules](../project-rules/SKILL.md) - GoodGo coding standards
- [Documentation](../documentation/SKILL.md) - Documentation guidelines