Agent Skills

Dạy AI các kỹ năng mới với Skills system.

Tổng quan

Agent Skills cho phép OpenCode khám phá và sử dụng các hướng dẫn có thể tái sử dụng từ repo hoặc home directory. Skills được load on-demand thông qua tool skill - agents thấy danh sách skills và có thể load nội dung đầy đủ khi cần.

Đặt file SKILL.md

Tạo một folder cho mỗi skill và đặt file SKILL.md bên trong. OpenCode tìm kiếm ở các vị trí sau:

Ví dụ cấu trúc

.opencode/
  skills/
    git-release/
      SKILL.md
    code-review/
      SKILL.md
    deploy-check/
      SKILL.md

Viết SKILL.md

Mỗi file SKILL.md phải bắt đầu bằng YAML frontmatter:

---
name: git-release
description: Tạo releases và changelogs nhất quán
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do
- Draft release notes từ merged PRs
- Đề xuất version bump
- Cung cấp lệnh `gh release create` sẵn sàng copy-paste

## When to use me
Sử dụng skill này khi bạn đang chuẩn bị tagged release.
Hỏi thêm nếu không rõ versioning scheme.

Frontmatter fields

Quy tắc đặt tên

name phải:

• Từ 1-64 ký tự
• Chỉ dùng lowercase alphanumeric
• Dùng hyphen - để tách (không được liên tiếp --)
• Không bắt đầu hoặc kết thúc bằng -
• Trùng với tên folder chứa SKILL.md

Regex tương đương:

^[a-z0-9]+(-[a-z0-9]+)*$

Cách Agent sử dụng Skills

OpenCode liệt kê available skills trong tool description:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Tạo releases và changelogs nhất quán</description>
  </skill>
</available_skills>

Agent load skill bằng cách gọi tool:

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

Cấu hình Permissions

Kiểm soát skills nào agents có thể truy cập trong opencode.json:

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

Pattern hỗ trợ wildcards: internal-* match internal-docs, internal-tools, v.v.

Override per Agent

Cho custom agents (trong frontmatter):

---
permission:
  skill:
    "documents-*": "allow"
---

Cho built-in agents (trong opencode.json):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

Disable Skills

Hoàn toàn tắt skills cho agents không cần dùng:

Cho custom agents:

---
tools:
  skill: false
---

Cho built-in agents:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Ví dụ thực tế

Skill: Code Review

.opencode/skills/code-review/SKILL.md:

---
name: code-review
description: Review code theo best practices của team
---

## Checklist review
1. **Correctness**: Logic có đúng không?
2. **Performance**: Có bottlenecks không?
3. **Security**: Có vulnerabilities không?
4. **Readability**: Code có dễ hiểu không?
5. **Tests**: Có đủ test coverage không?

## Conventions
- Sử dụng TypeScript strict mode
- Prefer functional programming patterns
- Giữ functions dưới 50 lines
- Tên biến phải descriptive

## Output format
Trả về dạng:
- [ ] Issue cần fix
- [!] Warning cần xem xét
- [+] Suggestion cải thiện

Skill: Database Migration

.opencode/skills/db-migration/SKILL.md:

---
name: db-migration
description: Tạo và review database migrations
metadata:
  orm: drizzle
  database: postgresql
---

## Migration Guidelines
1. Luôn tạo migration reversible (có rollback)
2. Không thay đổi data trong migration
3. Thêm indexes cho foreign keys
4. Kiểm tra impact trên production data

## Naming Convention
`YYYYMMDD_HHMMSS_<description>.sql`

## Review Checklist
- [ ] Migration có thể rollback?
- [ ] Có ảnh hưởng performance?
- [ ] Data hiện tại có bị corrupt?

Troubleshooting

Nếu skill không xuất hiện:

1. Kiểm tra tên file: Phải là SKILL.md (chữ HOA)
2. Kiểm tra frontmatter: Phải có name và description
3. Kiểm tra tên unique: Skills phải có tên duy nhất across all locations
4. Kiểm tra permissions: Skills với deny bị ẩn khỏi agents

Tham khảo

• Docs chính thức: Agent Skills
• Docs chính thức: Agents
• Docs chính thức: Permissions