Overview

Các nền tảng này đều mô tả Agent Skills như một chuẩn chung để mở rộng khả năng của AI agents.

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

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

---