feat: Update documentation guidelines to version 2.0, adopting kebab-case Vietnamese filenames and simplifying templates.

.agent/skills/skill-authoring/SKILL.md

@@ -123,6 +123,35 @@ Phần body chứa hướng dẫn chi tiết cho agent. Nên bao gồm:
 
 **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:
@@ -305,15 +334,66 @@ skills-ref to-prompt ./my-skill
 
 ### 8.2 Checklist Trước Khi Commit
 
-- [ ] `name` khớp với tên thư mục
-- [ ] `description` đủ chi tiết (1-1024 chars)
-- [ ] Body content < 5000 tokens
-- [ ] Code examples đã test và hoạt động
-- [ ] Links đều valid
-- [ ] Có section "When to Use"
-- [ ] Có section "Common Mistakes" (nếu applicable)
-- [ ] Có "Quick Reference" table
-- [ ] Có links đến related skills/resources
+- [ ] **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