# portal-ai-plugins: đưa Spotify Portal vào Claude Code, Codex — hướng dẫn cài đặt và dùng

> portal-ai-plugins là bộ plugin chính thức của Spotify, giúp các trợ lý lập trình AI (Claude Code, Codex, Cursor, pi) làm việc với Spotify Portal thông qua Portal CLI. Bạn dùng nó để tìm kiếm catalog phần mềm, xem tóm tắt dịch vụ, chạy chẩn đoán và gọi các action của Portal bằng ngôn ngữ tự nhiên. Cài đặt chỉ vài lệnh, nhưng cần có quyền truy cập Spotify Portal của tổ chức bạn.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-29 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/portal-ai-plugins-spotify-portal-claude-code-codex-cursor-2

portal-ai-plugins là bộ plugin do Spotify phát hành, để các trợ lý lập trình AI như Claude Code, Codex, Cursor và pi làm việc được với Spotify Portal. Thay vì tự gõ lệnh Portal CLI, bạn nói với trợ lý điều bạn cần, và plugin sẽ gọi CLI thay bạn theo từng quy trình có sẵn.

Bộ plugin này dành cho người trong tổ chức đã dùng Spotify Portal: lập trình viên, kỹ sư vận hành, hoặc người quản lý kỹ thuật cần tra cứu dịch vụ nhanh. Nếu bạn chưa có Portal thì repo này chưa có nhiều giá trị với bạn. Người làm kinh doanh hoặc văn phòng có thể nhờ đồng nghiệp kỹ thuật cài, rồi tự hỏi bằng câu thường ngày.

Điểm đáng giá nhất là các thao tác có rào an toàn. Khi gọi một action của Portal, plugin có phần xem trợ giúp, chạy thử (dry-run) và hỏi xác nhận trước khi làm thật. Repo hiện có khoảng 3218 sao và 255 fork, dùng giấy phép Apache-2.0.

```repo
- repo | spotify/portal-ai-plugins
- kind | Plugin
- desc | Plugin của Spotify đưa Spotify Portal vào Claude Code, Codex, Cursor và pi: tìm catalog phần mềm, tóm tắt dịch vụ, chạy action và Fleetshift.
- stars | 3.2k
- lang | TypeScript
- license | Apache-2.0
```

## portal-ai-plugins làm được gì

Mỗi chức năng là một "workflow" riêng. Bạn không cần nhớ lệnh, chỉ cần mô tả việc muốn làm.

- **Thiết lập (setup):** cấu hình đăng nhập Portal CLI cho môi trường trợ lý bạn đang dùng. Đây là bước đầu tiên và bạn chỉ làm một lần.
- **Chẩn đoán (doctor):** kiểm tra chỉ-đọc xem plugin, CLI, đăng nhập và các action đã sẵn sàng chưa. Khi có gì đó trục trặc, đây là chỗ nên thử đầu tiên vì nó không thay đổi gì.
- **Tìm kiếm (search):** tìm trong catalog phần mềm và tài liệu kỹ thuật bằng câu tự nhiên. Ví dụ bạn hỏi "dịch vụ nào lo phần thanh toán?" thay vì phải biết đúng tên dịch vụ.
- **Tóm tắt dịch vụ (service):** tạo bản tóm tắt ngắn về một dịch vụ, gồm các thông tin có sẵn như chủ sở hữu, tình trạng, sự cố và tài liệu. Rất tiện khi bạn vừa nhận bàn giao một dịch vụ lạ.
- **Action của Portal (actions):** tìm, xem chi tiết, xem trước và gọi các action. Có trợ giúp tích hợp, chạy thử và xác nhận để tránh bấm nhầm.
- **Phản hồi (feedback):** gửi góp ý về Portal CLI tới đội Portal.
- **Fleetshift:** gồm năm workflow. Bạn có thể tạo một "shift" từ mục tiêu (có bản xem trước dry-run), chạy shift và theo dõi với thời gian chờ có giới hạn, và dừng khi cần. Bạn cũng có thể xem tiến độ, đích và các PR (chỉ đọc), tìm nguyên nhân khi job lỗi (chỉ đọc), và mở PR cho các mục đã hoàn tất sau khi bạn xác nhận.

Ngoài ra, marketplace còn có thêm plugin **shunt** (hiện chỉ cho Claude Code). Nó chuyển các việc nặng I/O như đọc hàng loạt file hoặc sinh code mẫu sang các chế độ AiKA chạy mô hình worker rẻ hơn, qua registry action của Portal CLI. Chi tiết nằm trong `plugins/shunt/README.md` của repo.

## Cần chuẩn bị gì

Tư liệu của repo nói khá ít về yêu cầu, nên mình chỉ ghi những gì chắc chắn:

- Một trong các công cụ: Claude Code, Codex, Cursor hoặc pi. Bạn cần có sẵn công cụ này.
- Lệnh `npx`, vì các workflow gọi Portal CLI qua `npx @spotify/portal-cli <command>`. `npx` thường đi kèm Node.js. README không ghi phiên bản Node tối thiểu, nên bạn xem thêm trong `package.json` của repo nếu cần.
- Quyền truy cập Spotify Portal của tổ chức bạn để đăng nhập ở bước setup. README không mô tả chi tiết cách cấp quyền, bạn hỏi quản trị viên Portal nếu chưa có.
- Cursor: cần dùng team marketplace của Cursor để đăng ký repo.
- README không nói về hệ điều hành hay phần cứng. Hướng dẫn dưới đây chỉ là lệnh terminal, không cần GPU.

```note
Plugin dùng đăng nhập của bạn để đọc catalog và gọi action. Chỉ cài khi bạn được phép truy cập Portal, và luôn đọc phần xem trước (dry-run) trước khi xác nhận bất kỳ action nào thay đổi dữ liệu.
```

## Cài đặt từng bước

Cách cài khác nhau theo từng công cụ. Bạn chọn đúng công cụ mình đang dùng.

```steps
- Chọn công cụ | Claude Code, Codex, Cursor hoặc pi
- Thêm marketplace | Đăng ký repo spotify/portal-ai-plugins
- Cài plugin | Cài plugin Spotify Portal (tên gói portal)
- Mở phiên mới | Bắt đầu session hoặc task mới
- Chạy setup | Đăng nhập Portal CLI qua workflow setup
```

### Cài cho Claude Code

Mở terminal (PowerShell, Terminal hoặc cửa sổ lệnh bạn quen dùng), rồi chạy:

```bash
claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal   # optional: token-saving AiKA delegation
```

Lệnh đầu thêm marketplace của Spotify. Lệnh thứ hai cài plugin chính tên `portal`. Lệnh thứ ba là tuỳ chọn, chỉ cần nếu bạn muốn dùng shunt để tiết kiệm token. Phần sau dấu `#` chỉ là ghi chú, bạn không cần gõ.

Sau đó mở một session mới của Claude Code và chạy:

```text
/portal:setup
```

Chỗ người mới hay vấp: nếu không mở session mới, plugin có thể chưa được nạp.

### Cài cho Codex

```bash
codex plugin marketplace add spotify/portal-ai-plugins
codex
```

Trong Codex, mở `/plugins`, cài Spotify Portal, bắt đầu một task mới rồi gõ:

```text
Set up Spotify Portal for me.
```

### Cài cho Cursor

README mô tả bằng giao diện, không có lệnh. Bạn đăng ký repo [spotify/portal-ai-plugins] vào team marketplace của Cursor, rồi vào **Cursor Settings → Plugins** để cài Spotify Portal. Thường bước đăng ký marketplace cần quyền quản trị của team, nên hãy nhờ người phụ trách nếu bạn không thấy tuỳ chọn.

### Cài cho pi

```bash
pi install git:github.com/spotify/portal-ai-plugins
```

Mở session mới và chạy:

```text
/skill:setup
```

### Đăng nhập Portal CLI

Bước setup ở trên chính là phần đăng nhập. Theo README, setup kiểm tra các lệnh `auth`, `actions`, `owner`, `search` và `service` của Portal CLI trước khi tiếp tục. Hãy làm theo các hướng dẫn hiện ra trong phiên. README không ghi chi tiết từng màn hình đăng nhập.

Các workflow gọi CLI qua lệnh sau. Bạn không cần tự chạy, nhưng nên biết nó tồn tại:

```bash
npx @spotify/portal-cli <command>
```

## Kiểm tra đã chạy được chưa

Cách an toàn nhất là nhờ workflow `doctor`. Nó chạy chẩn đoán chỉ-đọc để kiểm tra plugin, CLI, đăng nhập và các action. Bạn có thể nói với trợ lý một câu như:

```text
Chạy doctor của Spotify Portal giúp mình.
```

Nếu mọi thứ báo sẵn sàng thì bạn đã cài xong. Nếu có mục báo lỗi, bạn làm lại bước setup rồi chạy lại doctor. README không mô tả chính xác nội dung màn hình kết quả, nên bạn cứ đọc thông báo từng mục mà trợ lý hiển thị.

Một cách thử nhanh nữa là hỏi thử một việc tìm kiếm nhỏ (xem tình huống đầu tiên bên dưới). Nếu trợ lý trả lời bằng dữ liệu thật từ catalog của tổ chức bạn thì đường dẫn từ plugin đến Portal đã thông.

## Dùng vào việc thật

Các tình huống dưới đây dựa trên các workflow trong README. Câu lệnh mẫu chỉ là cách diễn đạt gợi ý, bạn đổi theo ngữ cảnh của mình.

### Tìm đúng dịch vụ trong catalog

Bạn là nhân viên mới trong đội kỹ thuật và chưa biết dịch vụ nào là của ai. Thay vì hỏi từng người, bạn nhờ workflow `search`:

```text
Tìm trong catalog Portal các dịch vụ liên quan đến thanh toán, kèm tài liệu kỹ thuật nếu có.
```

Kết quả là danh sách dịch vụ và tài liệu khớp với câu hỏi. Từ đó bạn biết nên đọc gì trước và hỏi ai.

### Đọc nhanh một dịch vụ vừa được bàn giao

Sáng nay bạn nhận quản lý một dịch vụ cũ. Bạn nhờ workflow `service`:

```text
Tóm tắt dịch vụ <tên dịch vụ> trong Portal: ai sở hữu, tình trạng hiện tại, sự cố gần đây và tài liệu.
```

Bạn nhận một bản tóm tắt ngắn gọn với các thông tin Portal có sẵn như chủ sở hữu, tình trạng, sự cố và tài liệu. Thông tin nào Portal không có thì bản tóm tắt cũng sẽ không có, nên đừng coi đó là toàn bộ sự thật.

> Cái hay nhất của plugin này là bạn được xem trước mọi thứ trước khi để AI làm thật.
>
> — Ông T

### Gọi một action có kiểm soát

Bạn cần chạy một action của Portal nhưng chưa nhớ tham số. Hãy nhờ workflow `actions`:

```text
Liệt kê các action Portal mà mình có thể gọi, giải thích action <tên action>, rồi chạy thử (dry-run) trước khi làm thật.
```

Trợ lý sẽ tìm action, giải thích cách dùng, cho bạn xem bản xem trước, và chỉ làm thật khi bạn xác nhận. Với người mới, đây là cách học action nhanh mà ít rủi ro nhất.

### Chạy một đợt thay đổi hàng loạt bằng Fleetshift

Đội bạn cần cập nhật cùng một thay đổi trên nhiều kho code. Bạn mô tả mục tiêu cho workflow `fleetshift-create-shift`, xem bản dry-run, rồi để `fleetshift-run-shift` chạy và theo dõi với thời gian chờ có giới hạn:

```text
Tạo một shift Fleetshift với mục tiêu: <mô tả thay đổi>. Cho mình xem bản xem trước trước khi tạo.
```

Sau đó bạn dùng `fleetshift-check-shift` để xem tiến độ và các PR, và `fleetshift-troubleshoot-shift` nếu job nào lỗi. Khi các mục đã hoàn tất, `fleetshift-create-prs` mở PR sau khi bạn xác nhận. Bạn cũng có thể yêu cầu dừng shift bất cứ lúc nào.

## Lỗi hay gặp và cách xử lý

### Gõ lệnh slash nhưng không thấy gì

Thường là do plugin chưa được nạp. Hãy đóng session, mở session mới rồi chạy lại `/portal:setup` (Claude Code) hoặc `/skill:setup` (pi). Với Codex, kiểm tra xem bạn đã cài Spotify Portal trong `/plugins` chưa.

### Không thấy plugin trong Cursor

Bước đăng ký marketplace ở Cursor làm ở mức team. Nếu bạn không thấy Spotify Portal trong **Cursor Settings → Plugins**, hãy kiểm tra repo đã được đăng ký vào team marketplace chưa, và hỏi quản trị viên team.

### `npx` không chạy hoặc báo không tìm thấy lệnh

Workflow gọi Portal CLI qua `npx`, nên máy bạn cần có công cụ này. `npx` thường đi kèm Node.js. Cài Node.js từ trang chính thức rồi mở terminal mới. Nếu vẫn lỗi, xem yêu cầu phiên bản trong `package.json` của repo.

### Đăng nhập thất bại hoặc hết hạn

Chạy lại workflow `setup`, sau đó chạy `doctor` để xác nhận. Nếu vẫn không được, nhiều khả năng tài khoản của bạn chưa có quyền vào Portal, và bạn cần hỏi người quản trị. Đừng chia sẻ thông tin đăng nhập qua chat hay email.

### Action không chạy như mong đợi

Đừng bỏ qua bước xem trước. Dùng dry-run để xem chính xác điều sẽ xảy ra, đọc kỹ rồi mới xác nhận. Nếu kết quả khác với dự đoán của bạn, dừng lại và nhờ người phụ trách action đó kiểm tra. Gặp lỗi lạ, bạn có thể dùng workflow `feedback` để báo cho đội Portal.

## Có nên dùng không

**Điểm mạnh:**

- Do chính Spotify phát hành, giấy phép Apache-2.0, repo còn được cập nhật trong vài tháng gần đây.
- Hỗ trợ bốn công cụ phổ biến (Claude Code, Codex, Cursor, pi), nên đổi công cụ không phải học lại từ đầu.
- Có rào an toàn rõ ràng: chẩn đoán chỉ-đọc, dry-run, xác nhận trước khi làm thật.
- Quy trình được đóng gói thành workflow riêng, nên bạn nói điều cần làm thay vì nhớ lệnh.

**Giới hạn:**

- Chỉ có ích khi tổ chức bạn dùng Spotify Portal. Không có Portal thì plugin không giúp được gì.
- Phụ thuộc vào Portal CLI. README cho biết các workflow đều gọi qua `npx @spotify/portal-cli`.
- Plugin shunt hiện chỉ dùng cho Claude Code.
- README không nói rõ về hệ điều hành, phiên bản Node hay quy trình cấp quyền, nên bạn cần hỏi người quản trị Portal ở chỗ này.
- Chất lượng tóm tắt và tìm kiếm tuỳ vào dữ liệu có trong catalog của bạn.

**Khi nào chọn cách khác:** nếu bạn chỉ cần một trợ lý lập trình thông thường mà không có Portal, plugin này không cần thiết. Nếu bạn muốn tự động hoá các việc ngoài Portal, bạn cần plugin hoặc công cụ khác. Còn nếu đội bạn đã dùng Portal và muốn hỏi trợ lý thay vì mở giao diện web, đây là lựa chọn tự nhiên và khá an toàn để thử.

## Câu hỏi thường gặp

### portal-ai-plugins là gì?

Đây là bộ plugin của Spotify để đưa Spotify Portal vào Claude Code, Codex, Cursor và pi. Nó cung cấp các workflow như đăng nhập, tìm kiếm catalog, tóm tắt dịch vụ, gọi action và Fleetshift, đều chạy qua Portal CLI.

### Có miễn phí không?

Repo dùng giấy phép Apache-2.0, nên mã nguồn mở. Tư liệu không nói gì về chi phí của Spotify Portal hay của công cụ AI mà bạn dùng cùng, nên mình chưa có thông tin về phần đó.

### Cần GPU hoặc máy mạnh không?

README không nêu yêu cầu phần cứng. Cài đặt chỉ gồm các lệnh terminal và gọi Portal CLI qua npx, nên không có dấu hiệu cần GPU.

### Chạy trên Windows được không?

README không nói rõ về hệ điều hành. Các lệnh cài đặt đều là lệnh terminal thông thường của Claude Code, Codex và pi. Bạn nên thử và dùng workflow doctor để kiểm tra.

### Tôi cần tài khoản gì?

Bạn cần quyền truy cập Spotify Portal của tổ chức, vì bước setup sẽ cấu hình đăng nhập cho Portal CLI. README không mô tả chi tiết cách cấp quyền, nên hãy hỏi quản trị viên Portal nếu bạn chưa có.

### Plugin có tự làm thay đổi dữ liệu không?

Theo README, các action đi kèm trợ giúp tích hợp, dry-run và bước xác nhận. Việc mở PR từ Fleetshift cũng chỉ diễn ra sau khi bạn xác nhận. Các workflow doctor, check và troubleshoot là chỉ-đọc.

### shunt là gì, có bắt buộc cài không?

shunt là plugin tuỳ chọn, hiện chỉ cho Claude Code. Nó chuyển các việc nặng I/O như đọc hàng loạt file hoặc sinh code mẫu sang mô hình worker rẻ hơn để tiết kiệm token. Bạn không cần cài nó để dùng plugin chính.
