Bài 8.325 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

Dự án cuối khóa: plugin cho cả team

Đóng gói skill, subagent và hook của todo-api thành một plugin, sửa hai chỗ vấp khi chuyển, kiểm tra, rồi phát qua marketplace của team.

Đây là bài cuối. Suốt khóa học, bạn đã dựng cho todo-api một bộ công cụ hoàn chỉnh. Bài này đóng gói nó thành một plugin, đặt vào marketplace của team, và cài ở một repo khác chỉ bằng một lệnh. Mọi bước dưới đây chúng tôi đã làm thật, kể cả hai chỗ vấp mà bạn sẽ gặp khi chuyển từ .claude/ sang plugin.

Bạn đã có gì

Gom lại từ các cấp:

Thứ Từ bài Vào plugin
Skill /add-endpoint 3.2 Có
Skill pr-review kèm script red-flags.sh 3.3 Có
Subagent reviewer, tester, debugger 4.2, 4.3 Có
Hook kiểm cú pháp, chặn "xong" khi test đỏ 6.2 Có
Hook chặn rm -rf, chặn ghi .env 6.3 Có
Luật deny Read(./.env) 6.3 Không: plugin không mang được luật quyền
CLAUDE.md của dự án 2.1 Không: nằm trong plugin thì không được nạp

Hai dòng cuối là điều đáng nhớ đầu tiên: plugin mang được khả năng (skill, agent, hook, MCP), nhưng không mang luật quyền và bộ nhớ dự án. Những thứ đó vẫn nằm trong từng repo.

Từ .claude/ sang plugin

Bố cục của plugin todo-api-toolkit:

todo-api-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── add-endpoint/SKILL.md
│   └── pr-review/
│       ├── SKILL.md
│       └── scripts/red-flags.sh
├── agents/
│   ├── reviewer.md
│   ├── tester.md
│   └── debugger.md
├── hooks/
│   └── hooks.json
└── scripts/
    ├── block-rm.sh
    ├── protect-env.sh
    ├── check-js.sh
    └── tests-before-stop.sh

Chỉ plugin.json nằm trong .claude-plugin/; mọi thứ khác ở gốc plugin. Đặt skills/ vào trong .claude-plugin/ là skill không được nạp.

JSON
{
  "name": "todo-api-toolkit",
  "description": "Team toolkit for todo-api: skills, agents, safety and test hooks",
  "version": "1.0.0",
  "author": { "name": "todo-api team" }
}

name thành tiền tố cho mọi thứ: /add-endpoint giờ là /todo-api-toolkit:add-endpoint, agent tester giờ là todo-api-toolkit:tester.

Hook chuyển gần như nguyên vẹn: chép khối hooks trong .claude/settings.json sang hooks/hooks.json, chỉ đổi đường dẫn script từ $CLAUDE_PROJECT_DIR/.claude/hooks/ sang ${CLAUDE_PLUGIN_ROOT}/scripts/, bọc trong ngoặc kép:

JSON
{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/block-rm.sh\"" }

Plugin được cài ở đâu thì ${CLAUDE_PLUGIN_ROOT} trỏ tới đó. Đừng ghi dữ liệu vào thư mục này, vì nó đổi theo mỗi phiên bản.

Hai chỗ phải sửa khi chuyển

Chỗ thứ nhất: file đi kèm nằm ngoài dự án. Ở bài 3.3, checklist nằm trong checklist.md cạnh SKILL.md. Khi chạy từ plugin, Claude bị từ chối đọc file đó, vì plugin được cài ở ngoài thư mục dự án. Chúng tôi thử chèn bằng !`cat …` kèm quyền cho đúng lệnh đó, và kết quả còn tệ hơn: Claude Code chỉ cho cat trong thư mục làm việc, nên cả lần gọi skill bị hủy. Cách sửa đơn giản nhất: checklist chỉ có năm dòng, đưa thẳng vào SKILL.md. Script đi kèm thì vẫn chạy tốt qua ${CLAUDE_SKILL_DIR}, vì nó được chạy, không phải đọc.

Chỗ thứ hai: bản cũ còn trong .claude/. Nếu chưa xóa, skill và agent cũ tồn tại song song với bản có tiền tố, còn hook chạy hai lần (bản trong settings và bản trong plugin). Kiểm tra plugin chạy đúng rồi xóa bản gốc khỏi .claude/.

Thêm một lưu ý cho agent: trong plugin, permissionMode, hooks, mcpServers của agent bị bỏ qua. Hook và MCP phải khai ở cấp plugin.

Kiểm tra trước khi phát

Ba bước, đều chạy từ shell:

Terminal
claude plugin validate ./todo-api-toolkit
claude --plugin-dir ./todo-api-toolkit plugin details todo-api-toolkit
claude --plugin-dir ./todo-api-toolkit
  • validate kiểm manifest và frontmatter của mọi skill, agent. Của chúng tôi: ✔ Validation passed.
  • plugin details liệt kê thành phần và chi phí: 2 skill, 3 agent, hook ở 3 sự kiện (hook không tốn ngữ cảnh), tổng khoảng 232 token mỗi phiên.
  • --plugin-dir mở một phiên có plugin mà không cài, để thử từng thứ.

Khi thử: hook của plugin chặn rm -rf dù có luật allow; /todo-api-toolkit:pr-review chạy script, đi qua từng mục checklist và chỉ ra console.log ở src/routes/todos.js:8; agent todo-api-toolkit:tester báo 5/5 test đạt.

Marketplace cho team

Đặt plugin vào một repo marketplace, ví dụ your-org/todo-team-plugins:

todo-team-plugins/
├── .claude-plugin/marketplace.json
└── plugins/todo-api-toolkit/   (thư mục plugin ở trên)
JSON
{
  "name": "todo-team-plugins",
  "owner": { "name": "todo-api team" },
  "plugins": [
    { "name": "todo-api-toolkit", "source": "./plugins/todo-api-toolkit",
      "description": "Skills, agents and hooks for working on todo-api" }
  ]
}

Chạy claude plugin validate ./todo-team-plugins rồi push. Người trong team cài bằng:

/plugin marketplace add your-org/todo-team-plugins
/plugin install todo-api-toolkit@todo-team-plugins

Muốn repo tự gợi ý cho người mới, thêm vào .claude/settings.json của repo đó:

JSON
{
  "extraKnownMarketplaces": {
    "todo-team-plugins": { "source": { "source": "github", "repo": "your-org/todo-team-plugins" } }
  },
  "enabledPlugins": { "todo-api-toolkit@todo-team-plugins": true },
  "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)", "Read(!.env.example)"] }
}

Marketplace được đăng ký khi họ tin thư mục, và luật deny cho .env vẫn nằm ở đây vì plugin không mang được nó. Mỗi người vẫn cài plugin một lần trên máy mình (bài 8.2). Phát bản mới: sửa plugin, tăng version, push. Marketplace bên thứ ba mặc định không tự cập nhật, nên nhắc team bật hoặc chạy claude plugin update.

Khép lại khóa học

Workflow CI ở bài 8.1 giờ dùng được chính plugin này: plugin_marketplaces trỏ tới repo marketplace, plugins: "todo-api-toolkit@todo-team-plugins", và prompt: "/todo-api-toolkit:pr-review".

Nhìn lại cả hành trình: bạn bắt đầu bằng việc giao một bug nhỏ và đọc diff (cấp 1); dạy Claude về dự án (cấp 2); biến quy trình thành lệnh và skill (cấp 3); chia việc cho các agent chuyên trách (cấp 4); nối với GitHub qua MCP với quyền tối thiểu (cấp 5); đặt luật chạy mỗi lần bằng hook (cấp 6); làm việc lớn an toàn với plan, rewind và phiên dài (cấp 7); và cuối cùng chạy không người trông, đóng gói cho cả team (cấp 8).

Nguyên tắc xuyên suốt vẫn chỉ có một: Claude làm nhiều hơn khi bạn cho nó đúng bối cảnh, đúng công cụ và đúng giới hạn. Mỗi khi thấy mình lặp lại cùng một việc, hãy hỏi: đây là dữ kiện (CLAUDE.md), quy trình (skill), việc phụ (subagent), kết nối (MCP), hay luật phải luôn đúng (hook)? Rồi đóng gói nó lại.

Luyện tập bài 8.3

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.