admin/pos-system

Fork 0

Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

14 KiB

Raw Permalink Blame History

name, description, compatibility, metadata

name

description

compatibility

metadata

skill-authoring

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.

Antigravity, Claude Code, hoặc các agent khác hỗ trợ Agent Skills spec

author	version	references
Velik Ho	1.0	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:

---
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:

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:

description: Helps with PDFs.

Fields Tùy Chọn

---
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:

When to Use - Khi nào nên sử dụng skill này
Step-by-step Instructions - Hướng dẫn từng bước
Examples - Ví dụ input/output
Common Mistakes - Lỗi thường gặp và cách tránh
Quick Reference - Bảng tham chiếu nhanh
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:

Progressive Disclosure: Agent loads only what's needed
Better Performance: Faster skill discovery and activation
Easier Maintenance: Update specific guides without touching core
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:

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

5. File References

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

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

# 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

---
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

// Code example

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

Mistake 1: Description

// ❌ 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


### 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)

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

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:

## 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

# 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:

# 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):

# 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:

# 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

---
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

// ❌ 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


## 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

14 KiB Raw Permalink Blame History

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

1. Tổng Quan / Overview

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

Quy tắc đặt tên thư mục

3. Format SKILL.md

3.1 Frontmatter (BẮT BUỘC)

Field name (BẮT BUỘC)

Field description (BẮT BUỘC)

Fields Tùy Chọn

3.2 Body Content

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

4. Progressive Disclosure

5. File References

6. Optional Directories

6.1 scripts/

6.2 references/

6.3 assets/

7. Best Practices cho GoodGo

7.1 Cấu Trúc Content Chuẩn

Pattern 2

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

Quick Reference / Tham Chiếu Nhanh

Resources / Tài Nguyên

7.3 Cross-References

8. Validation & Testing

8.1 Sử dụng skills-ref

8.2 Checklist Trước Khi Commit

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

9. Template Skill Mới

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

Mistake 1

Quick Reference / Tham Chiếu Nhanh

Resources / Tài Nguyên

14 KiB

Raw Permalink Blame History

Field `name` (BẮT BUỘC)

Field `description` (BẮT BUỘC)