Định dạng tài nguyên
Trang này tả plugin.json của mọi tài nguyên trên Tara, khối metadata.forge, cấu trúc gói theo từng loại và catalog model. Muốn làm từng bước thì xem Viết skill và agent.
plugin.json
File nằm ở .claude-plugin/plugin.json. Các trường theo chuẩn plugin của Claude Code, cộng thêm quy tắc riêng của Tara.
| Trường | Bắt buộc | Mô tả |
|---|---|---|
name | Có | Tên tài nguyên, xem quy tắc đặt tên |
version | Có | Semver MAJOR.MINOR.PATCH |
description | Có | Mô tả ngắn, không rỗng |
author.name | Có | Tên tác giả hoặc nhóm |
displayName | Không | Tên hiển thị |
license | Không | Giấy phép |
keywords | Không | Từ khóa tìm kiếm |
dependencies | Harness: có | Danh sách phụ thuộc, xem mục dưới |
hooks, mcpServers | Không | Khai báo trực tiếp. Thường đặt trong hooks/hooks.json và .mcp.json |
metadata.forge | Có | Dữ liệu riêng của nền tảng |
Claude Code coi version, description và author.name là tùy chọn, nhưng Tara bắt buộc cả ba.
dependencies
Mỗi mục là một object { "name", "version" } hoặc chuỗi "tên". Bạn chỉ phụ thuộc được vào tài nguyên có trên Tara, không trỏ sang marketplace khác. Tài nguyên chính thức cũng chỉ phụ thuộc tài nguyên chính thức.
"dependencies": [
{ "name": "agent-dev", "version": "~1.1.0" },
{ "name": "skill-sdlc", "version": "^1.2.0" }
]Ràng buộc version viết được theo các kiểu ^1.2, ~1.2.0, =1.2.0 (hoặc 1.2.0), >=1.0 <2.0 và ^1.0 || ^2.0. Thiếu ràng buộc thì Tara cảnh báo. Cách Tara khóa version nằm ở Khóa version và chữ ký số.
metadata.forge
Claude Code bỏ qua khối này, chỉ Tara và Phillip đọc.
| Trường | Bắt buộc | Kiểu | Mô tả |
|---|---|---|---|
schema | Có | số | Phiên bản định dạng, hiện là 1 |
type | Có | chuỗi | skill, agent, kit, prompt hoặc harness |
org | Tài nguyên chính thức và của tổ chức | chuỗi | Không gian tên của kho: aiforge cho danh mục chính thức, hoặc slug tổ chức của bạn cho kho riêng của tổ chức. Bỏ trống thì đây là tài nguyên cộng đồng, nằm trong không gian tên của người gửi |
center | Không | chuỗi | Đã bỏ, thay bằng org. Vẫn được đọc kèm cảnh báo: rnd tính là aiforge, giá trị khác tính là tổ chức của người gửi |
owners | Có | mảng email | Người chịu trách nhiệm bảo trì, ít nhất một |
roles | Không | mảng chuỗi | Vai trò nghề nghiệp phù hợp, gồm PO, BA, UIUX, SA, PM, Dev, Reviewer, Test, Security, DevOps, Docs, Builder |
engines | Có | mảng chuỗi | claude-code, hoặc phillip (chỉ dành cho kit plugin của Phillip) |
status | Có | chuỗi | active hoặc deprecated |
replacedBy | Không | chuỗi | Tên tài nguyên thay thế khi deprecated |
model | Không | chuỗi | Alias model mặc định cho harness, phải có trong catalog |
docs | Không* | mảng | Tài liệu đi kèm, xem mục dưới. *Kit và harness bắt buộc có install và usage |
phillip | Kit plugin | object | Khai báo plugin cho Phillip |
guardrails | Kit policy | object | Khai báo gói policy Guardrails |
roles chỉ giúp tìm kiếm và gợi ý, không cấp quyền.
docs
"docs": [
{ "type": "install", "path": "docs/cai-dat.md", "title": "Hướng dẫn cài đặt" },
{ "type": "usage", "path": "docs/su-dung.pdf" }
]| Trường | Mô tả |
|---|---|
type | install, usage, configuration, troubleshooting hoặc other |
path | Đường dẫn trong gói |
title | Tiêu đề hiển thị; bỏ trống thì dùng tên loại |
Hiện Tara nhận md (tối đa 2 MB) và pdf (tối đa 20 MB, có kiểm chữ ký đầu file). Loại và định dạng là cấu hình của Tara nên có thể khác ở tổ chức của bạn, gọi GET /v1/document-policy để xem. Tài liệu tách khỏi gói cài, lưu theo version, không sửa được và nằm trong chữ ký số. Muốn đọc thì chạy ph tara docs <tên>.
phillip
Khối này dành cho kit có engines: ["phillip"]. Hợp đồng chi tiết nằm ở Hợp đồng plugin.
| Trường | Bắt buộc | Mô tả |
|---|---|---|
provides | Có | scm, notify hoặc tracker |
api | Có | Phiên bản hợp đồng, hiện là 1 |
entry | Có | Đường dẫn module ESM trong gói |
capabilities | Không | scm có task, report, sync (bỏ trống là task); notify có send; tracker có task |
matches | scm | Host của remote origin mà kit phục vụ. notify và tracker không dùng trường này |
credential.label | Có | Tên credential hiển thị cho người dùng |
credential.help, url, env, optional | Không | Hướng dẫn, trang tạo token, biến môi trường gợi ý, và cho phép chạy không cần bí mật |
settings.<tên> | Không | default, env, required, help. Kit tracker bắt buộc có settings.project với required: true |
guardrails
| Trường | Giá trị |
|---|---|
schema | 1 |
level | company hoặc project |
policy | Đường dẫn file luật trong gói |
Quy tắc đặt tên
<loại>-<tên>Tên viết theo kebab-case, dài tối đa 64 ký tự và bắt đầu bằng tiền tố loại: skill-, agent-, kit-, prompt- hoặc harness-. Tên không chứa từ claude hay anthropic, cũng không dùng từ dành riêng của nền tảng (tên các thành phần, official). Tên cũ có thêm một mã ở giữa, như agent-tta-java-review, vẫn hợp lệ, nhưng tên mới không cần mã này.
Không gian tên không nằm trong tên. Tên đầy đủ là <org>/<tên>, theo kiểu npm scope, ví dụ acme/skill-review. Tên trần như skill-review nghĩa là aiforge/skill-review. Khi gặp tên trần, Tara chỉ tìm trong aiforge, rồi đến tổ chức của người gọi, không bao giờ sang tổ chức khác. Nhờ vậy không ai chiếm được tên trần bằng một tài nguyên cộng đồng của riêng mình. Tài nguyên cộng đồng của tổ chức khác phải gọi bằng tên đầy đủ; nếu tên trần không khớp mà có tên như vậy, Tara trả 404 kèm gợi ý, ví dụ did you mean beta/skill-foo?. Phụ thuộc là tên trần trong manifest của một gói được tìm trong aiforge, rồi đến tổ chức của chính gói đó. Muốn phụ thuộc vào tài nguyên của tổ chức khác, ghi tên đầy đủ.
Kênh
Kênh của tài nguyên do metadata.forge.org quyết định.
org trong manifest | Kênh | Ai duyệt | Nội dung |
|---|---|---|---|
aiforge | official | Nhân sự nền tảng | Có thể kèm script, hook, MCP |
| Slug tổ chức của người gửi | org (kho riêng của tổ chức) | Admin hoặc Owner của tổ chức | Có thể kèm script, hook, MCP |
| Bỏ trống | community | Không có người duyệt, bộ quét tự động quyết định | Chỉ Markdown và cấu hình, bắt đầu ở chế độ private |
Tài nguyên cộng đồng nằm trong không gian tên của chính người gửi. Trường center cũ vẫn được đọc: rnd thành aiforge, giá trị khác thành tổ chức của người gửi, và Tara thêm một phát hiện báo trường này đã bỏ.
Cấu trúc theo loại
| Loại | Bắt buộc thêm |
|---|---|
| Mọi loại | README.md, CHANGELOG.md có mục ## <version>; không có CLAUDE.md ở gốc |
agent | Ít nhất một agents/<tên>.md |
skill, prompt | Ít nhất một skills/<tên>/SKILL.md |
kit | Ít nhất một: .mcp.json, hooks/hooks.json, metadata.forge.phillip, metadata.forge.guardrails |
harness | template/CLAUDE.md và dependencies |
Catalog model
Model không phải gói cài, nó là một mục trong catalog gồm các trường sau.
| Trường | Mô tả |
|---|---|
alias | Tên ngắn kebab-case, ví dụ sonnet-std |
engine | Engine, ví dụ claude-code |
model | Định danh model gửi cho engine |
task | reasoning, code hoặc light |
purpose | Mô tả ngắn công dụng |
roles | Vai trò nghề nghiệp phù hợp |
status | active (chọn mới được) hoặc deprecated (đang rút dần) |
recommended | Model được gợi ý mặc định cho task. Model deprecated không thể là gợi ý |
Muốn chọn model cho dự án thì chạy ph model use <alias>.