# Overview

## Tài liệu hướng dẫn Agent Skills

### Tài liệu tham khảo chính

Các tài liệu chính thức về Agent Skills:

1. OpenAI Codex Skills\
   <https://developers.openai.com/codex/skills/>
2. OpenCode Skills Documentation\
   <https://opencode.ai/docs/skills/>
3. Claude Agent Skills Documentation\
   <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview>
4. Các chuyên gia AI sẵn sàng chuyển đổi quy trình làm việc của bạn\
   <https://github.com/msitarzewski/agency-agents>

***

## 1. Agent Skills là gì

**Agent Skills** là các module mở rộng cho AI agent, giúp agent có thể thực hiện những nhiệm vụ chuyên biệt.

Skill thường bao gồm:

* Instructions (hướng dẫn)
* Scripts (code thực thi)
* Resources (tài liệu tham khảo)

Mục tiêu:

```
Write once → reuse everywhere
```

Một skill giúp agent thực hiện **một workflow cụ thể** thay vì phải dùng prompt dài lặp lại nhiều lần.

***

## 2. Vì sao cần Agent Skills

Agent Skills giúp:

#### 1. Chuyên môn hóa AI

Ví dụ:

| Không có skill | Có skill                |
| -------------- | ----------------------- |
| AI chung chung | AI chuyên code React    |
| AI chung chung | AI chuyên deploy Docker |
| AI chung chung | AI chuyên phân tích log |

***

#### 2. Tái sử dụng workflow

Thay vì prompt dài:

```
Write a changelog
Generate release notes
Create GitHub release command
```

Chỉ cần:

```
use skill: git-release
```

***

#### 3. Tự động load khi cần

Agent có thể:

* tự chọn skill
* hoặc gọi skill trực tiếp

Ví dụ:

```
skill({ name: "git-release" })
```

Agent sẽ load nội dung SKILL.md vào context.

***

## 3. Cấu trúc của một Skill

Một skill là **một thư mục**.

Ví dụ:

```
my-skill/
│
├── SKILL.md
├── scripts/
│   └── run.py
├── references/
│   └── api-doc.md
└── assets/
    └── template.md
```

Thành phần chính:

| File       | Chức năng     |
| ---------- | ------------- |
| SKILL.md   | bắt buộc      |
| scripts    | code thực thi |
| references | tài liệu      |
| assets     | template      |

***

## 4. File SKILL.md

File quan trọng nhất.

Bắt buộc có **YAML frontmatter**.

Ví dụ:

```
---
name: git-release
description: Create consistent releases and changelogs
---
```

Quy tắc:

* name: 1–64 ký tự
* chỉ chữ thường + số + dấu "-"
* description: 1–1024 ký tự

***

## 5. Nội dung SKILL.md

Ví dụ:

```
# Git Release Skill

## What I do

- Generate release notes
- Suggest version bump
- Create GitHub release command

## When to use

Use this when preparing a new release.
```

***

## 6. Cách agent tìm và load skill

Agent sẽ scan các thư mục:

#### OpenCode

```
.opencode/skills/
~/.config/opencode/skills/
.claude/skills/
~/.claude/skills/
.agents/skills/
```

Agent sẽ tìm:

```
skills/<skill-name>/SKILL.md
```

***

## 7. Cách cài skill

Ví dụ với Codex:

```
~/.codex/skills/
```

Hoặc:

```
project/.codex/skills/
```

Sau khi cài:

```
restart agent
```

Agent sẽ tự động phát hiện skill mới.

***

## 8. Cách agent sử dụng skill

Có 2 cách.

#### 1. Auto detect

User prompt:

```
Create a GitHub release
```

Agent sẽ chọn skill:

```
git-release
```

***

#### 2. Manual call

```
skill({ name: "git-release" })
```

***

## 9. Permission của skill

Trong file config:

```
opencode.json
```

Ví dụ:

```
{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
```

Các trạng thái:

| Permission | Meaning              |
| ---------- | -------------------- |
| allow      | load ngay            |
| deny       | không cho agent thấy |
| ask        | hỏi user             |

***

## 10. Disable skills

Có thể tắt hoàn toàn skill tool:

```
tools:
  skill: false
```

Agent sẽ không sử dụng skill.

***

## 11. Progressive Loading (quan trọng)

Skill được load theo từng bước:

#### Level 1

Metadata

```
name
description
```

***

#### Level 2

Instructions

```
SKILL.md
```

***

#### Level 3

Resources / scripts

```
scripts/
references/
```

Cách này giúp:

```
tiết kiệm context
```

***

## 12. Agent Skills là open standard

Hiện nay nhiều agent hỗ trợ cùng một chuẩn skill:

* Claude Code
* OpenAI Codex
* Cursor
* VSCode AI agents
* OpenCode

Các skill có thể **chạy cross-platform** giữa nhiều agent.

***

## 13. Ví dụ skill thực tế

### React Expert Skill

```
name: react-expert
description: Help build React applications
```

Chức năng:

* generate component
* optimize hooks
* create project structure

***

### DevOps Skill

```
name: docker-deploy
description: Deploy Docker services
```

Chức năng:

* build Dockerfile
* create compose
* deploy container

***

## 14. Lưu ý bảo mật

Skill có thể:

* chạy code
* đọc file
* gọi API

Nếu skill độc hại có thể:

* đánh cắp dữ liệu
* chạy lệnh nguy hiểm

Vì vậy chỉ nên dùng skill từ **nguồn đáng tin cậy**.

***

## Tóm tắt

Agent Skills là **plugin cho AI agent**.

Skill gồm:

```
instructions
scripts
resources
```

Cấu trúc:

```
skill/
 ├ SKILL.md
 ├ scripts/
 ├ references/
 └ assets/
```

Skill giúp:

```
AI chuyên môn hóa
workflow tái sử dụng
automation mạnh hơn
```

***

## Template chuẩn tạo Agent Skill

### 1. Cấu trúc thư mục

```
skills/
└── your-skill-name/
    ├── SKILL.md
    ├── README.md
    ├── examples/
    │   └── example.md
    ├── scripts/
    │   └── run.py
    ├── resources/
    │   └── reference.md
    └── templates/
        └── template.md
```

Ý nghĩa:

| Folder    | Chức năng                      |
| --------- | ------------------------------ |
| SKILL.md  | file chính để agent hiểu skill |
| README.md | tài liệu cho developer         |
| examples  | ví dụ cách dùng                |
| scripts   | code thực thi                  |
| resources | tài liệu tham khảo             |
| templates | template output                |

***

### 2. File bắt buộc: SKILL.md

Đây là file quan trọng nhất.

### Template

````markdown
---
name: your-skill-name
description: Short description of what the skill does and when the agent should use it
version: 1.0.0
author: your-name
tags:
  - automation
  - coding
  - ai-agent
---

# Your Skill Name

## Purpose

Explain what this skill does.

Example:

This skill helps the AI agent generate release notes and GitHub releases automatically.

---

## When to Use

Use this skill when:

- The user asks to create releases
- The user asks for changelog generation
- The user prepares a software release

Do NOT use this skill when:

- The user is only asking about Git concepts
- The user is debugging Git issues

---

## Instructions

Follow these steps:

1. Analyze the user's request
2. Determine the required workflow
3. Use available scripts if necessary
4. Produce the final output in a structured format

---

## Workflow

Typical workflow:

1. Gather information
2. Process the data
3. Generate structured output

Example:

User request → analyze → generate release notes → output markdown.

---

## Output Format

Always return results in this format:

```bash
## Result

Summary:
...

Details:
...

Next Steps:
...

```

---

## Available Resources

The following resources may help:

resources/reference.md

---

## Scripts

If execution is needed use scripts from:

scripts/

Example:

```bash
python scripts/run.py
```

---

## Examples

Example user request:

```bash
Create release notes for version 2.0
```

Example output:

```bash
## Release Notes

### Features

- New API

#### Fixes

- Bug fixes

```

````

***

### 3. README.md (cho developer)

Template:

```
# Skill: your-skill-name

## Description

Explain what the skill does.

## Directory Structure

SKILL.md – main skill instructions  
scripts/ – executable scripts  
resources/ – reference materials  
examples/ – usage examples  

## Installation

Copy folder into:

.claude/skills/
.codex/skills/
.opencode/skills/

## Usage

The agent will automatically detect the skill when relevant.

Or manually call:

skill("your-skill-name")
```

***

### 4. Template script (scripts/run.py)

```
import sys

def main():
    print("Skill script executed successfully")

if __name__ == "__main__":
    main()
```

Agent chỉ nhận **output của script**, không cần load code vào context.

***

### 5. Template resource file

`resources/reference.md`

```
# Reference Guide

Important information used by the skill.

Example:

API endpoints
data schema
workflow rules
```

***

### 6. Template example

`examples/example.md`

```
User request:

Generate release notes for version 1.2

Expected output:

# Release Notes

## Features
- Feature A

## Fixes
- Fix B
```

***

### 7. Quy tắc đặt tên Skill

| Rule              | Example       |
| ----------------- | ------------- |
| lowercase only    | good          |
| use hyphen        | docker-deploy |
| max 64 characters | recommended   |

Không dùng:

```
spaces
UPPERCASE
special characters
```

***

### 8. Ví dụ Skill hoàn chỉnh

```
skills/
└── docker-deploy/
    ├── SKILL.md
    ├── scripts/
    │   └── deploy.py
    └── resources/
        └── docker-reference.md
```

Skill này có thể:

* build docker image
* generate docker-compose
* deploy container

***

### 9. Best Practices

#### Viết description rõ ràng

Tốt:

```
Generate structured blog posts from topic outlines
```

Kém:

```
Blog tool
```

***

#### Hạn chế prompt dài

Skill nên:

```
instructions < 5000 tokens
```

***

#### Dùng script cho logic phức tạp

Không nên:

```
AI tự viết code mỗi lần
```

Nên:

```
AI gọi script
```

***

### 10. Template nhanh nhất (minimal skill)

Nếu cần **skill đơn giản**, chỉ cần:

```
your-skill/
└── SKILL.md
```

Ví dụ:

```
---
name: blog-writer
description: Generate blog posts from topic prompts
---

# Blog Writer Skill

## Instructions

When the user asks for a blog post:

1. Generate outline
2. Write structured article
3. Include headings and sections
```

***