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:

OpenAI Codex Skills https://developers.openai.com/codex/skills/
OpenCode Skills Documentation https://opencode.ai/docs/skills/
Claude Agent Skills Documentation https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
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

PreviousPublish your docs NextTại sao nên cân nhắc xây dựng Skills trước thay vì Agents?

Last updated 4 months ago