plugin-forge

Tổng quan về skill plugin-forge

plugin-forge là một skill chuyên để xây dựng và duy trì plugin dành cho tác giả Claude Code plugin, khi bạn cần đúng cấu trúc thư mục, đúng file manifest và đăng ký marketplace mà không phải tự mày mò lại toàn bộ quy trình. Công việc thực sự ở đây không chỉ là “viết vài dòng JSON”, mà là “phát hành một plugin được scaffold đúng chuẩn, version nhất quán và có thể cài được trong quy trình phân phối qua marketplace.”

plugin-forge phù hợp nhất với ai

Hãy dùng skill plugin-forge nếu bạn đang:

• tạo một Claude Code plugin mới từ đầu
• thêm các thành phần plugin như commands/, agents/, skills/ hoặc hooks/
• cập nhật .claude-plugin/plugin.json cùng lúc với metadata trên marketplace
• test plugin cục bộ trước khi publish
• duy trì một repository plugin kiểu marketplace có nhiều plugin

plugin-forge đặc biệt hữu ích với các lập trình viên cần một cấu trúc có thể lặp lại ổn định, chứ không chỉ là đầu ra dùng một lần từ prompt.

Điều gì khiến plugin-forge khác với một prompt thông thường

Một prompt thông thường có thể phác thảo skeleton cho plugin, nhưng plugin-forge bổ sung các “lan can” thực tế để giảm lỗi:

• bố cục thư mục plugin được quy ước rõ ràng
• vị trí manifest và kỳ vọng cho từng field được nêu cụ thể
• tham chiếu schema của marketplace
• quy trình cài cục bộ và test
• script tự động để scaffold và tăng version

Tổ hợp này quan trọng vì lỗi plugin phổ biến nhất thường không nằm ở chất lượng code, mà ở cấu trúc thiếu nhất quán hoặc metadata không khớp nhau.

plugin-forge thực sự bao phủ những gì

Dựa trên nội dung repository, plugin-forge tập trung vào:

• scripts/create_plugin.py để scaffold plugin mới
• scripts/bump_version.py để cập nhật version đồng bộ
• references/plugin-structure.md cho cấu trúc thư mục và manifest
• references/marketplace-schema.md cho quy tắc khai báo entry trên marketplace
• references/workflows.md cho luồng tạo, test và publish

Vì vậy, đây gần với một bộ hướng dẫn triển khai kèm công cụ hỗ trợ hơn là một tài liệu lý thuyết tổng quát.

Khi nào plugin-forge là lựa chọn mạnh cho Code Generation

plugin-forge cho Code Generation hữu ích nhất khi bạn muốn model tạo ra các file phải rơi đúng vào “form” plugin chuẩn, ví dụ:

• một skeleton plugin mới với metadata hợp lệ
• một command hoặc skill mới được chèn vào plugin hiện có
• cập nhật plugin.json đồng thời với thay đổi tương ứng trong entry marketplace
• chuẩn bị release có kèm semantic version bump

Nếu nhu cầu chính của bạn là viết business logic thuần túy bên trong một plugin đã chạy ổn định, thì plugin-forge sẽ kém hữu ích hơn một skill lập trình chuyên theo domain.

Cách dùng skill plugin-forge

Bối cảnh cài đặt cho plugin-forge

SKILL.md upstream không công bố lệnh cài đặt riêng, nên cách cài sẽ phụ thuộc vào cách bạn nạp skill trong môi trường của mình. Nếu bạn đang dùng skill bundle của repository, một mẫu phổ biến là:

npx skills add softaworks/agent-toolkit --skill plugin-forge

Sau đó, hãy gọi plugin-forge khi tác vụ của bạn liên quan đến tạo plugin, manifest, đăng ký marketplace, test cục bộ hoặc quản lý version.

Nên đọc các file này trước

Để vào việc nhanh, hãy đọc theo thứ tự sau:

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

Lộ trình này giúp bạn nắm “skill này làm gì” trước, rồi đến bố cục file cần có, tiếp theo là hợp đồng dữ liệu với marketplace, và cuối cùng là các helper có thể chạy trực tiếp.

plugin-forge cần bạn cung cấp những đầu vào gì

plugin-forge cho kết quả tốt nhất khi bạn đưa ra bối cảnh repository và publish thật cụ thể, thay vì chỉ nói “hãy làm cho tôi một plugin”. Tối thiểu, hãy nêu rõ:

• tên plugin ở dạng kebab-case
• đường dẫn root của marketplace
• mục đích của plugin
• tên và email tác giả
• bộ từ khóa ban đầu
• category
• bạn cần commands, agents, skills, hooks hay cấu hình MCP
• đây là plugin mới hay bản cập nhật của plugin hiện có

Nếu thiếu các thông tin này, model vẫn có thể draft file, nhưng đầu ra thường sẽ cần dọn lại bằng tay khá nhiều.

Biến mục tiêu mơ hồ thành prompt plugin-forge mạnh hơn

Prompt yếu:

Create a Claude Code plugin for my project.

Prompt mạnh hơn:

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

Prompt thứ hai cung cấp cho plugin-forge đủ dữ liệu để tạo ra các file gần với mức có thể dùng được ngay hơn nhiều.

Dùng script scaffold khi bạn ưu tiên tốc độ

Nếu bạn đã biết metadata mình cần, hãy dùng helper script thay vì tự dựng cây thư mục ban đầu bằng tay:

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

Đây là đường đi nhanh nhất khi điều bạn quan tâm nhiều hơn là setup đúng chuẩn, thay vì một bộ scaffold được “chạm tay” tùy biến hoàn toàn.

Dùng script version để tránh manifest bị lệch nhau

Một trong những phần thiết thực nhất khi dùng plugin-forge là versioning đồng bộ. Skill này có scripts/bump_version.py để cập nhật cả hai file:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Ví dụ:

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

Điều này quan trọng vì lệch version giữa hai file trên là một lỗi bảo trì rất hay gặp.

Làm theo đúng workflow plugin-forge

Một quy trình plugin-forge thực tế sẽ là:

1. scaffold plugin
2. kiểm tra plugin.json đã được tạo
3. xác minh entry marketplace trong .claude-plugin/marketplace.json
4. thêm các thành phần như command hoặc skill
5. test cục bộ qua luồng cài từ marketplace
6. lặp lại và chỉnh sửa
7. bump version trước khi release

Quy trình này đáng tin cậy hơn so với việc dồn mọi thứ vào một prompt khổng lồ duy nhất.

Chuẩn bị sớm cho luồng test cục bộ

Các tài liệu tham chiếu có nêu một đường test cục bộ rất cụ thể:

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

Điều đó có nghĩa là bạn nên thiết kế prompt để plugin-forge tạo ra đường dẫn và metadata có thể cài được, chứ không chỉ tạo các file mô tả. Chỉ cần lệch đường dẫn nguồn hoặc tên plugin là khâu test sẽ hỏng ngay.

Các file mà plugin-forge thường sẽ chỉnh sửa

Trong sử dụng thực tế, bạn nên chờ plugin-forge tạo mới hoặc sửa các mục sau:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

Phạm vi đó rất đáng lưu ý khi lên kế hoạch review, vì plugin-forge thường là công cụ tạo thay đổi trên nhiều file cùng lúc.

Mẹo thực tế giúp nâng chất lượng đầu ra của plugin-forge

Hãy yêu cầu plugin-forge:

• giữ nguyên chính xác tên plugin và path hiện có
• dùng kebab-case cho mọi identifier
• hiển thị cả plugin manifest và marketplace entry cùng nhau
• giải thích các field bắt buộc mà nó không thể tự suy ra
• tách rõ phần “generated files” và phần “manual follow-up”
• kiểm tra version và tên có khớp nhau giữa các manifest hay không

Những yêu cầu này giúp giảm khả năng tạo ra đầu ra nhìn có vẻ đẹp nhưng lại không cài được.

Câu hỏi thường gặp về skill plugin-forge

Nếu tôi đã prompt tốt rồi thì plugin-forge còn đáng dùng không?

Có, nếu rủi ro chính của bạn nằm ở độ đúng cấu trúc. plugin-forge hữu ích hơn một prompt thông thường khi bạn cần manifest nhất quán, entry marketplace khớp chuẩn và bố cục thư mục ổn định. Nếu bạn chỉ cần trợ giúp để viết một file command trong một plugin đã tồn tại, lợi thế này sẽ nhỏ hơn.

plugin-forge có thân thiện với người mới không?

Phần lớn là có. plugin-forge cho người mới một lộ trình khá cụ thể để đi từ tạo plugin đến test. Điểm cần lưu ý là người mới vẫn phải hiểu root marketplace của mình ở đâu, quy ước đặt tên ra sao và thực sự muốn những thành phần nào. Nó giúp mạnh về cấu trúc hơn là về thiết kế sản phẩm.

Khi nào không nên dùng plugin-forge?

Hãy bỏ qua plugin-forge nếu:

• bạn không xây dựng Claude Code plugin
• bạn không phân phối theo kiểu marketplace
• bạn chỉ muốn sinh code Python hoặc JavaScript chung chung
• repository của bạn có bố cục plugin tùy biến và cố ý khác với cấu trúc được tài liệu hóa

Trong các trường hợp này, plugin-forge có thể đẩy bạn về một “form” không phù hợp.

plugin-forge có tự động lo luôn việc publish không?

Chưa hoàn toàn. Skill này làm tốt phần chuẩn bị: scaffold, manifest, đăng ký marketplace, hướng dẫn test cục bộ và cập nhật version. Nhưng nó không phải một nền tảng release end-to-end. Bạn vẫn cần tự review file, test cục bộ và chạy quy trình publish hoặc phân phối của riêng mình.

Rào cản lớn nhất khi áp dụng là gì?

Thường là thiếu bối cảnh repository. plugin-forge giả định rằng bạn biết marketplace root nằm ở đâu và plugin của mình nên được xếp vào category nào. Nếu bạn chưa trả lời được những câu hỏi đó, đầu ra tạo ra vẫn chỉ ở mức draft, chưa sẵn sàng cho production.

plugin-forge khác gì so với tự sửa manifest bằng tay?

Tự sửa tay vẫn ổn cho thay đổi một lần, nhưng plugin-forge tốt hơn khi bạn cần tính lặp lại hoặc muốn tránh việc plugin.json và marketplace.json bị lệch nhau theo thời gian. Các script đi kèm chính là lợi thế thực tế rõ ràng nhất.

Cách cải thiện skill plugin-forge

Cung cấp đầu vào có bối cảnh repository cho plugin-forge

Cách cải thiện tốt nhất là cung cấp path chính xác và các file hiện tại. Thay vì chỉ yêu cầu “bump version”, hãy nói:

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

Cách viết này buộc skill đi theo các thay đổi có thể kiểm chứng được, thay vì chỉ đưa lời khuyên chung chung.

Yêu cầu đầu ra theo từng file, không chỉ tóm tắt

plugin-forge làm tốt hơn khi bạn yêu cầu deliverable cụ thể:

• toàn bộ plugin.json
• entry marketplace chính xác
• cây thư mục đề xuất
• bản khởi đầu cho README
• các lệnh tiếp theo để test cục bộ

Điều này đặc biệt quan trọng với plugin-forge cho Code Generation, nơi giá trị nằm ở các file có thể áp dụng ngay.

Ngăn các lỗi phổ biến nhất

Hãy để ý những vấn đề sau trong đầu ra của plugin-forge:

• tên plugin khác nhau giữa các file
• path source trên marketplace không khớp với bố cục thư mục thực tế
• version chỉ được cập nhật ở một manifest mà không cập nhật manifest còn lại
• metadata có nhắc tới thành phần tùy chọn nhưng file/thư mục tương ứng không được tạo
• cấu trúc sinh ra thiếu .claude-plugin/plugin.json

Chỉ cần review nhanh đối chiếu với references/plugin-structure.md và references/marketplace-schema.md là bạn có thể bắt được phần lớn lỗi kiểu này.

Dùng workflow hai lượt để có kết quả tốt hơn

Một cách dùng plugin-forge hiệu quả trong thực tế là:

1. lượt đầu: tạo cấu trúc và manifest
2. lượt hai: tạo các thành phần plugin và cải thiện README

Nếu cố làm scaffold, business logic, tài liệu, thiết lập test và ghi chú publish trong một prompt duy nhất, chất lượng thường sẽ giảm. plugin-forge mạnh nhất khi ưu tiên cấu trúc trước.

Lặp lại sau đầu ra đầu tiên bằng các chỉnh sửa có mục tiêu

Đừng chỉ nói “fix this”. Hãy đưa chỉ dẫn sửa cụ thể, ví dụ:

• “Regenerate marketplace.json entry so source points to ./plugins/schema-audit.”
• “Add skills/ to the tree and keep manifest fields unchanged.”
• “Update only version fields; do not rewrite descriptions or keywords.”
• “Align the plugin name to kebab-case everywhere.”

Kiểu lặp lại có ràng buộc như vậy sẽ giúp plugin-forge đáng tin cậy hơn nhiều.

Kết hợp plugin-forge với tài liệu tham chiếu, đừng dùng nó để thay thế tài liệu

Cách tốt nhất để cải thiện đầu ra của plugin-forge là yêu cầu nó viện dẫn hoặc bám sát các tài liệu tham chiếu trong repository một cách rõ ràng. Trong prompt, hãy nhắc tới:

• references/plugin-structure.md cho yêu cầu về cấu trúc thư mục
• references/marketplace-schema.md cho các field của marketplace
• references/workflows.md cho luồng cài đặt và test

Nhờ vậy, skill sẽ bám vào quy ước thực tế của repo thay vì quay về các giả định plugin quá chung chung.