Viết skill và agent
Skill, agent và prompt chỉ gồm Markdown và cấu hình, nên là loại tài nguyên dễ viết và dễ duyệt nhất. Trang này dẫn bạn từ lúc tạo khung đến lúc gửi lên Tara.
Bạn cần cài Phillip và đăng nhập Tara trước. Muốn gửi tài nguyên vào danh mục chính thức hoặc kho riêng của tổ chức thì bạn phải là Member trở lên trong tổ chức (Viewer không gửi được). Nơi gửi quyết định ai duyệt: Admin hoặc Owner của tổ chức duyệt kho riêng, còn nhân sự nền tảng PhillipCLI duyệt danh mục chính thức. Tài nguyên cộng đồng không cần ai duyệt vì Tara quét tự động.
Nên chọn loại nào?
Muốn truyền kiến thức hoặc quy trình để agent tự áp dụng thì chọn skill. Muốn tạo một lệnh có tên để người dùng gọi tay thì chọn prompt. Muốn giao một vai trò riêng như BA, Dev hay review code, với chỉ dẫn và tool giới hạn, thì chọn agent.
Cấu trúc thư mục
Một skill tên skill-api-spec có cấu trúc như sau.
skill-api-spec/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── api-spec/
│ ├── SKILL.md
│ └── reference/
│ └── template.md
├── README.md
└── CHANGELOG.mdMột agent tên agent-reviewer thì như sau.
agent-reviewer/
├── .claude-plugin/
│ └── plugin.json
├── agents/
│ └── reviewer.md
├── README.md
└── CHANGELOG.mdPrompt có cấu trúc giống skill, đặt dưới skills/<tên>/SKILL.md, và gọi bằng /prompt-<tên>:<lệnh>.
README.md và CHANGELOG.md là bắt buộc. Đừng đặt CLAUDE.md ở gốc gói vì Claude Code không nạp nó. Nội dung đó nên đưa vào skill, hoặc vào harness nếu là quy ước chung. Tên thư mục phải trùng với name trong plugin.json.
Tạo khung từ mẫu
ph tara new skill skill-api-spec --org acme --description "Viết đặc tả API theo chuẩn của chúng tôi"Lệnh dựng khung đúng cấu trúc trên. Muốn tạo tài nguyên cộng đồng thì thêm --personal. Bạn cũng có thể dùng trình hướng dẫn trên Portal (mục Contribute (đóng góp), bấm Create resource (tạo tài nguyên)) rồi sửa file ngay trong trình duyệt.
Viết plugin.json
{
"name": "skill-api-spec",
"displayName": "Đặc tả API",
"version": "1.0.0",
"description": "Viết đặc tả API theo chuẩn của chúng tôi",
"author": { "name": "Nhóm Nền tảng" },
"license": "UNLICENSED",
"keywords": ["api", "spec"],
"metadata": {
"forge": {
"schema": 1,
"type": "skill",
"org": "acme",
"owners": ["owner@example.com"],
"roles": ["BA", "SA", "Dev"],
"engines": ["claude-code"],
"status": "active"
}
}
}Trên Tara, version, description và author.name là bắt buộc, dù Claude Code coi chúng là tùy chọn. owners là email người chịu trách nhiệm bảo trì. Toàn bộ các trường có ở Định dạng tài nguyên.
Nếu agent cần skill khác thì bạn khai báo phụ thuộc, và nên dùng ~ hoặc ^ thay vì để trống.
"dependencies": [
{ "name": "skill-api-spec", "version": "^1.0" }
]Phụ thuộc phải là tài nguyên đã phát hành trên Tara, và tài nguyên chính thức chỉ được phụ thuộc tài nguyên chính thức.
Viết nội dung
Skill
SKILL.md có phần đầu YAML, phần thân là hướng dẫn.
---
name: api-spec
description: Viết đặc tả API từ yêu cầu. Dùng khi người dùng cần mô tả endpoint, tham số và mã lỗi.
---
Viết đặc tả theo mẫu trong `reference/template.md`.
## Cách làm
1. Liệt kê endpoint và phương thức.
2. Mô tả tham số, kết quả và mã lỗi.
3. Nêu ví dụ yêu cầu và phản hồi.Claude đọc description để quyết định khi nào nạp skill, nên bạn cần nêu rõ khi nào dùng. Nội dung dài thì chia thành các file trong reference/, để skill chỉ nạp khi cần.
Prompt
Muốn chỉ người dùng gọi được, bạn thêm disable-model-invocation: true vào phần đầu. Thêm argument-hint để gợi ý tham số.
Agent
---
name: reviewer
description: Review thay đổi mã theo checklist. Dùng khi cần đọc diff trước khi merge.
tools: Read, Grep, Glob, Bash(git diff:*)
---
Bạn là reviewer. Đọc diff, đối chiếu checklist, nêu vấn đề kèm dòng mã.
## Giới hạn
Không sửa file. Không đưa secret vào đầu ra.Bạn nên giới hạn tools. Tara cảnh báo cho người duyệt khi thấy Bash hoặc WebFetch không giới hạn, hoặc permissionMode: bypassPermissions. Nếu thật sự cần, hãy giải thích trong mục ## Permissions của README.
Một vài lời khuyên khi viết. Mỗi tài nguyên chỉ làm một việc. Thông tin nằm ở một nơi, nơi khác chỉ tra cứu bằng mã thay vì chép lại. Và bảo agent hỏi lại khi thiếu thông tin quan trọng.
Viết CHANGELOG.md
Mỗi version phải có một mục ## <version>.
# Changelog
## 1.0.0 - 2026-11-01
- Phiên bản đầu tiên.Nếu thiếu mục cho đúng version đang gửi thì bước kiểm báo lỗi. Phillip cũng lấy mục này để báo khi có version mới.
Kiểm tra và gửi
ph tara check ./skill-api-spec
ph tara publish ./skill-api-spec
ph tara status skill-api-spec@1.0.0Lệnh check chạy đúng luật kiểm của Tara mà không lưu gì, nên bạn sửa hết các dòng error trước khi gửi. Lệnh publish gửi version lên. Không thêm tùy chọn thì bài vào kho cá nhân của bạn; --org acme (hoặc metadata.forge.org: acme) đăng vào tổ chức nếu chính sách đăng của tổ chức cho phép. Tara quét gói và phát hành ngay nếu không có gì chặn. Chỉ org: aiforge mới chờ nhân sự nền tảng duyệt. Lệnh status cho biết trạng thái, kết quả kiểm và lý do nếu bài bị chặn hoặc bị trả lại.
Bài bị trả lại thì bạn lấy mã về sửa rồi gửi version mới.
ph tara pull skill-api-spec@1.0.0 --dir ./skill-api-spec
ph tara bump ./skill-api-spec 1.0.1 --changelog "Sửa mẫu thiếu mã lỗi"
ph tara publish ./skill-api-specTiêu chí duyệt nằm ở Tiêu chí duyệt, còn cách chọn số version ở Quy tắc version.