Claude Plugins: Tạo Cowork Plugin tùy chỉnh

Plugin là gì và tại sao cần tạo plugin riêng?

Claude Cowork Plugin là gói mở rộng khả năng của Claude cho các workflow cụ thể. Thay vì giải thích lại context mỗi lần, plugin encode domain knowledge, quy trình làm việc, và integrations của tổ chức bạn — để Claude hoạt động như một chuyên gia trong lĩnh vực đó ngay từ đầu.

Khi nào nên tạo plugin riêng:

• Bạn có workflow lặp đi lặp lại mà cần Claude hiểu sâu context
• Team cần dùng Claude theo cách chuẩn hóa với cùng một bộ quy tắc
• Bạn muốn tích hợp Claude với tools nội bộ qua MCP
• Bạn muốn chia sẻ best practices thành "skill" mà cả team có thể dùng

Kiến trúc Plugin

Cấu trúc thư mục:

plugin-name/
├── .claude-plugin/
│   └── plugin.json           # Manifest (bắt buộc)
├── skills/                   # Skills (chính)
│   └── skill-name/
│       ├── SKILL.md          # Skill definition
│       └── references/       # Tài liệu tham khảo chi tiết
├── agents/                   # Subagent definitions (ít dùng)
├── .mcp.json                 # MCP server connections (nếu cần)
└── README.md                 # Tài liệu plugin

plugin.json tối thiểu:

{
  "name": "plugin-name",
  "version": "0.1.0",
  "description": "Mô tả ngắn về mục đích plugin",
  "author": {
    "name": "Tên của bạn hoặc tổ chức"
  }
}

Quy tắc đặt tên: kebab-case, chữ thường, chỉ dùng hyphens. Không có spaces hay ký tự đặc biệt.

5 Phase tạo Plugin

Phase 1: Discovery — Hiểu rõ cần build gì

Câu hỏi cần trả lời trước:

Trước khi bắt đầu code, hãy trả lời:

1. Plugin này giải quyết vấn đề gì cụ thể?
   [Mô tả pain point hiện tại]

2. Ai sẽ dùng plugin này?
   [Role, context làm việc, level kỹ thuật]

3. Plugin cần tích hợp với tools nào?
   [Jira, Slack, GitHub, nội bộ...]

4. Workflow điển hình trông như thế nào?
   [Bước 1 → Bước 2 → Bước 3...]

5. "Done" trông như thế nào?
   [Plugin thành công khi user có thể làm gì mà trước đây không thể?]

Ví dụ Discovery cho plugin PM tools:

Plugin: pm-toolkit
Vấn đề: PM team tốn nhiều thời gian viết PRD, tạo competitive brief, và báo cáo stakeholder theo các format khác nhau

Users: Product Managers tại công ty, không cần kỹ thuật cao

Integrations cần: Jira (pull sprint data), Confluence (save docs)

Workflow:
- PM mô tả feature cần spec → nhận PRD draft
- PM input competitor URL → nhận competitive brief
- PM paste sprint data → nhận stakeholder update

Success: PM có thể produce tài liệu chất lượng cao trong 1/3 thời gian hiện tại

Phase 2: Component Planning

Các component types:

Template Component Plan:

| Component | Số lượng | Mục đích |
|-----------|----------|----------|
| Skills    | 3        | /write-prd, /competitive-brief, /stakeholder-update |
| MCP       | 1        | Kết nối Jira để pull sprint data |
| Agents    | 0        | Không cần |
| Hooks     | 0        | Không cần |

Nguyên tắc: Bắt đầu với ít nhất — một skill tốt có giá trị hơn năm skill nửa vời.

Phase 3: Viết SKILL.md

Đây là phần quan trọng nhất. Skill body là hướng dẫn cho Claude, không phải documentation cho user.

Format SKILL.md chuẩn:

---
name: skill-name
description: Mô tả khi nào trigger skill này. Dùng trigger phrases cụ thể.
  Ví dụ: "Trigger khi user muốn viết PRD, spec tính năng, document requirements."
argument-hint: "<feature name hoặc problem statement>"
---

# Tên Skill

Mô tả ngắn về mục đích skill.

## Usage

/skill-name [arguments]

## Workflow

### 1. Thu thập thông tin
[Hướng dẫn cho Claude: hỏi user những gì]

### 2. Process
[Claude cần làm gì với thông tin đó]

### 3. Output
[Format output mong muốn]

## Tips

[Các gợi ý để output tốt hơn]

Ví dụ SKILL.md hoàn chỉnh:

---
name: write-prd
description: Viết Product Requirements Document (PRD) hoặc product spec từ
  feature idea hoặc problem statement. Trigger khi user nói:
  "viết PRD", "tạo spec", "document requirements", "feature specification".
argument-hint: "<feature name hoặc problem statement>"
---

# Write PRD

Tạo PRD chuyên nghiệp theo chuẩn của team.

## Usage

/write-prd [tên feature hoặc mô tả vấn đề]

## Workflow

### 1. Thu thập context
Hỏi user (nếu chưa rõ từ argument):
- User problem: Vấn đề gì, ai gặp?
- Target users: Segment nào?
- Success metrics: Biết thành công qua metric nào?
- Constraints: Kỹ thuật, timeline, dependencies?

### 2. Tạo PRD

Viết PRD với các sections:
1. Problem Statement (2-3 câu, evidence-based)
2. Goals (3-5 measurable outcomes)
3. Non-Goals (3-5 items explicitly out of scope)
4. User Stories (format: As a [user], I want [capability] so that [benefit])
5. Requirements: P0 (must-have) / P1 (nice-to-have) / P2 (future)
6. Success Metrics (leading + lagging indicators với targets cụ thể)
7. Open Questions (tag theo người cần trả lời)

### 3. Review

Sau khi draft xong:
- Hỏi user có cần adjust section nào không
- Offer expand bất kỳ phần nào
- Offer tạo engineering ticket breakdown hoặc stakeholder pitch

## Tips

- Goals là outcomes, không phải outputs
- Non-goals quan trọng như goals — ngăn scope creep
- Mọi requirement P0 phải có acceptance criteria cụ thể
- Success metrics phải specific (số %, không phải "improve")

Phase 4: Cài đặt MCP connections (nếu cần)

Format .mcp.json:

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/jira/index.js"],
      "env": {
        "JIRA_URL": "${JIRA_URL}",
        "JIRA_TOKEN": "${JIRA_TOKEN}"
      }
    }
  }
}

Lưu ý bảo mật: Dùng environment variables cho credentials, không bao giờ hardcode trong .mcp.json.

Phase 5: Package và distribute

Validate plugin:

# Kiểm tra thủ công:
1. .claude-plugin/plugin.json tồn tại và có field "name" hợp lệ
2. Name là kebab-case (chỉ lowercase, numbers, hyphens)
3. Mỗi skill directory có SKILL.md
4. Frontmatter của SKILL.md có "name" và "description"
5. Không có hardcoded paths (dùng ${CLAUDE_PLUGIN_ROOT})

Tạo .plugin file:

cd /path/to/plugin-directory
zip -r /tmp/plugin-name.plugin . -x "*.DS_Store"
cp /tmp/plugin-name.plugin /path/to/output/plugin-name.plugin

File .plugin là ZIP thông thường đổi extension. Khi user nhận file này trong Cowork, họ sẽ thấy preview và có thể install bằng một click.

Best practices khi viết Skills

Trigger phrases phải cụ thể:

KHÔNG TỐT:
description: "Giúp với product management tasks"

TỐT:
description: "Tạo PRD hoặc product spec. Trigger khi user nói:
  'viết PRD', 'tạo spec cho feature X', 'document requirements',
  'product specification', 'feature requirements document'"

Progressive disclosure:

• SKILL.md body: core workflow, dưới 3000 words
• references/: detailed content khi cần depth (templates, examples, checklists)
• examples/: ví dụ cụ thể cho edge cases

Viết cho Claude, không phải cho người dùng:

KHÔNG TỐT (documentation):
"PRD là tài liệu quan trọng trong product development..."

TỐT (instructions for Claude):
"Khi user yêu cầu viết PRD, hỏi về user problem và target segment trước.
Sau đó generate PRD với cấu trúc sau..."

Ví dụ plugin hoàn chỉnh: pm-toolkit

pm-toolkit/
├── .claude-plugin/
│   └── plugin.json
│       {
│         "name": "pm-toolkit",
│         "version": "1.0.0",
│         "description": "PM tools: PRD, competitive brief, sprint planning"
│       }
├── skills/
│   ├── write-prd/
│   │   └── SKILL.md
│   ├── competitive-brief/
│   │   └── SKILL.md
│   └── sprint-planning/
│       ├── SKILL.md
│       └── references/
│           └── capacity-templates.md
└── README.md

Troubleshooting phổ biến

• Plugin không load được: Kiểm tra plugin.json syntax (valid JSON, name là kebab-case)
• Skill không trigger: Description cần include trigger phrases mà user thực tế nói
• MCP không kết nối: Kiểm tra env variables và path dùng ${CLAUDE_PLUGIN_ROOT}
• Skill quá verbose: Move detailed content vào references/, giữ SKILL.md dưới 3000 words

Bước tiếp theo

Sau khi tạo plugin, bước tiếp theo thường là customize nó cho các teams khác nhau trong tổ chức. Xem Claude Plugins: Tùy chỉnh Plugin cho team để biết cách adapt một plugin có sẵn cho workflow và tools cụ thể của từng team.

Bài viết liên quan

• Claude Plugins: Tùy chỉnh Plugin cho team
• Developer Playbook — Claude cho lập trình viên
• Claude API — Authentication, Rate Limits và Error Handling
• Claude cho Engineering: Deploy checklist tự động
• Evaluator-Optimizer — Tự cải thiện output với feedback loop