# portal-ai-plugins: đưa Spotify Portal vào Claude Code, Codex, Cursor — cài và dùng

> spotify/portal-ai-plugins là bộ plugin 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 dịch vụ trong catalog, xem tóm tắt vận hành, chạy action và quản lý Fleetshift shift bằng ngôn ngữ tự nhiên. Cài chỉ cần vài lệnh, nhưng bạn cần có sẵn quyền truy cập Spotify Portal của tổ chức mình.

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

Repo này là bộ plugin chính thức của Spotify, giúp trợ lý lập trình AI như Claude Code, Codex, Cursor và pi làm việc trực tiếp với Spotify Portal. Phía sau, plugin gọi Portal CLI để xác thực, tìm kiếm catalog phần mềm, xem thông tin dịch vụ và chạy các action trong Portal. Bạn không phải nhớ từng lệnh CLI, chỉ cần nhờ trợ lý bằng câu thường.

Người nên quan tâm là các nhóm kỹ thuật đang dùng Spotify Portal (hay Backstage bản của Spotify) để quản lý dịch vụ nội bộ: lập trình viên, kỹ sư vận hành, người làm nền tảng. Nếu bạn làm văn phòng hoặc kinh doanh nhưng công ty có dùng Portal, plugin này giúp bạn hỏi nhanh ai sở hữu một dịch vụ, tài liệu nằm đâu, mà không phải lục nhiều trang.

Điểm đáng giá nhất là các lớp bảo vệ khi chạy action: có trợ giúp tích hợp, chạy thử (dry-run) và bước xác nhận trước khi thật sự làm. Hiện repo có khoảng 3.218 sao và 255 fork, giấy phép Apache-2.0, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | spotify/portal-ai-plugins
- kind | Plugin
- desc | Plugin của Spotify đưa 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 chẩn đoán và gọi action an toàn.
- stars | 3.2k
- lang | TypeScript
- license | Apache-2.0
```

## Portal AI Plugins làm được gì

Plugin chia thành các workflow nhỏ, mỗi workflow lo một việc. Bạn không phải dùng hết, chỉ gọi cái cần.

### Thiết lập và kiểm tra

- **setup**: cấu hình xác thực cho Portal CLI trong môi trường trợ lý bạn đang dùng. Đây là bước đầu tiên và bắt buộc.
- **doctor**: chạy chẩn đoán chỉ đọc, kiểm tra plugin, CLI, xác thực và khả năng dùng action đã sẵn sàng chưa. Vì chỉ đọc nên chạy thoải mái, không sợ làm hỏng gì.

### Tìm hiểu dịch vụ

- **search**: tìm trong catalog phần mềm và tài liệu kỹ thuật bằng câu hỏi tự nhiên. Lợi ích: bạn hỏi như nói chuyện thay vì đoán từ khóa.
- **service**: tạo bản tóm tắt vận hành ngắn gọn cho một dịch vụ, gồm các thông tin có sẵn về chủ sở hữu, tình trạng, sự cố và tài liệu. Hợp khi bạn vừa nhận một dịch vụ lạ và cần nắm nhanh.

### Hành động

- **actions**: khám phá, xem chi tiết, xem trước và chạy action của Portal. Có trợ giúp, dry-run và xác nhận để tránh chạy nhầm.
- **feedback**: gửi phản hồi về Portal CLI tới đội Portal.

### Fleetshift

Năm workflow còn lại xoay quanh Fleetshift shift:

- **fleetshift-create-shift**: soạn và tạo shift từ một mục tiêu, có bản xem trước dry-run.
- **fleetshift-run-shift**: kích hoạt shift, theo dõi với thời gian chờ có giới hạn, và dừng khi bạn yêu cầu.
- **fleetshift-check-shift**: báo tiến độ, các đích và PR (chỉ đọc).
- **fleetshift-troubleshoot-shift**: chẩn đoán job lỗi từ trạng thái và log (chỉ đọc).
- **fleetshift-create-prs**: mở PR cho các đích đã hoàn tất, sau khi bạn xác nhận.

### Plugin shunt (tùy chọn)

Kho này còn có 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 hay sinh code mẫu sang các chế độ AiKA chạy mô hình rẻ hơn, thông qua danh mục action của Portal CLI. Mục tiêu là tiết kiệm token. Chi tiết nằm ở `plugins/shunt/README.md` trong repo.

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

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

- Một trong các môi trường: **Claude Code**, **Codex**, **Cursor** hoặc **pi**. Riêng shunt chỉ dùng được với Claude Code.
- **npx** để chạy Portal CLI. Các workflow gọi CLI bằng `npx @spotify/portal-cli <lệnh>`. npx đi kèm Node.js, nhưng README không nêu phiên bản Node cụ thể.
- Quyền truy cập **Spotify Portal** của tổ chức bạn, vì bước setup cấu hình xác thực. README không mô tả chi tiết cách cấp tài khoản, bạn hỏi quản trị viên Portal nếu chưa có.
- Với Cursor: quyền đăng ký repo vào marketplace của team Cursor.
- README không nói gì về hệ điều hành hay phần cứng. Chưa có thông tin riêng cho Windows.

```note
Plugin này kết nối vào hệ thống nội bộ của công ty. Trước khi cho trợ lý chạy action, hãy hỏi quản trị viên Portal về quyền của tài khoản bạn và luôn đọc kỹ bản xem trước (dry-run) trước khi xác nhận.
```

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

```steps
- Mở công cụ | Chọn Claude Code, Codex, Cursor hoặc pi, mở terminal tương ứng
- Thêm marketplace | Đăng ký repo spotify/portal-ai-plugins
- Cài plugin | Cài portal (và shunt nếu dùng Claude Code, không bắt buộc)
- Mở phiên mới | Bắt đầu session hoặc task mới để plugin được nạp
- Chạy setup | Cấu hình xác thực Portal CLI
```

### Cách A: Claude Code

Mở terminal (PowerShell trên Windows, Terminal trên macOS), chạy từng lệnh. Lệnh đầu thêm marketplace, lệnh hai cài plugin chính, lệnh ba cài shunt nếu bạn muốn tiết kiệm token (có thể bỏ qua).

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

Sau đó mở một phiên Claude Code mới và gõ:

```text
/portal:setup
```

Chỗ người mới hay vấp: phải mở **phiên mới** sau khi cài, nếu không lệnh `/portal:setup` sẽ không xuất hiện.

### Cách B: Codex

Thêm marketplace rồi mở 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 và nhờ:

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

### Cách C: Cursor

Cursor không dùng lệnh. Bạn đăng ký repo spotify/portal-ai-plugins vào marketplace của team Cursor, rồi vào **Cursor Settings → Plugins** để cài Spotify Portal. Bước này thường cần quyền quản trị team, nên nếu không thấy mục đăng ký, hãy nhờ người quản lý team.

### Cách D: pi

Một lệnh duy nhất để cài:

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

Mở phiên mới và chạy:

```text
/skill:setup
```

### Về Portal CLI

Bạn không cần cài CLI riêng. Các workflow tự gọi CLI qua lệnh dưới đây. Bạn chỉ cần biết để hiểu trợ lý đang làm gì phía sau.

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

Bước setup sẽ kiểm tra các lệnh bắt buộc `auth`, `actions`, `owner`, `search` và `service` trước khi đi tiếp.

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

Cách chắc nhất là dùng workflow **doctor**. Nó chạy chẩn đoán chỉ đọc và kiểm tra bốn thứ: plugin, CLI, xác thực và khả năng dùng action. Bạn có thể nhờ trợ lý bằng một câu như:

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

Nếu cả bốn mục đều ổn, bạn đã sẵn sàng. Nếu có mục báo lỗi, làm theo gợi ý trợ lý đưa ra, thường là chạy lại setup. README không mô tả định dạng kết quả chính xác, nên mình không hứa màn hình cụ thể nào. Dấu hiệu tốt đơn giản là setup chạy xong không báo thiếu lệnh nào trong năm lệnh `auth`, `actions`, `owner`, `search`, `service`.

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

### Lập trình viên mới nhận một dịch vụ lạ

Bạn vừa chuyển team và được giao một dịch vụ chưa từng đụng tới. Thay vì mò trong catalog, bạn nhờ trợ lý dùng workflow service:

```text
Tóm tắt vận hành cho dịch vụ payments-api: ai sở hữu, tình trạng, sự cố gần đây và tài liệu.
```

Bạn nhận một bản tóm tắt ngắn với các thông tin Portal có sẵn: chủ sở hữu, sức khỏe, sự cố, tài liệu. Chỗ nào Portal chưa có dữ liệu thì bản tóm tắt sẽ không có, đừng kỳ vọng nó tự suy đoán. Tên dịch vụ ở đây chỉ là ví dụ của mình.

> Hỏi catalog bằng câu thường nhanh hơn nhiều so với đoán đúng từ khóa.
>
> — Ông T

### Nhân viên vận hành tìm tài liệu kỹ thuật

Bạn đang trực và cần biết quy trình khôi phục một hệ thống. Dùng workflow search:

```text
Tìm trong Portal tài liệu hướng dẫn khôi phục dịch vụ khi cơ sở dữ liệu bị đầy.
```

Trợ lý tìm trong catalog và tài liệu kỹ thuật, trả danh sách kết quả liên quan. Bạn mở đúng tài liệu cần đọc thay vì lục từng trang.

### Kỹ sư chạy một action của Portal

Công ty bạn có sẵn action trong Portal, ví dụ tạo tài nguyên hay kích hoạt một quy trình. Bạn nhờ:

```text
Liệt kê các action Portal mình được phép dùng, rồi cho mình xem trợ giúp của action đầu tiên và chạy thử (dry-run).
```

Workflow actions sẽ khám phá, giải thích cách dùng, cho xem trước và chỉ chạy thật khi bạn xác nhận. Hãy luôn đọc kỹ bản xem trước. Với người mới, đây là cách học action an toàn nhất.

### Đội nền tảng thay đổi hàng loạt bằng Fleetshift

Giả sử bạn cần áp một thay đổi lên nhiều repo. Bạn nhờ trợ lý tạo shift từ mục tiêu và xem trước:

```text
Tạo một Fleetshift shift với mục tiêu: nâng phiên bản thư viện X lên bản mới ở các repo được chọn. Cho mình xem dry-run trước.
```

Sau khi duyệt, bạn nhờ chạy shift, theo dõi tiến độ, xem lỗi nếu job thất bại, rồi cuối cùng mở PR cho các đích đã xong. Mỗi bước là một workflow riêng (create, run, check, troubleshoot, create-prs), và các bước chỉ đọc như check và troubleshoot không làm thay đổi gì. Bước mở PR cần bạn xác nhận.

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

### Không thấy lệnh /portal:setup sau khi cài

Thường do bạn chưa mở phiên mới. Thoát và bắt đầu session hoặc task mới, rồi thử lại. Với Codex, kiểm tra trong `/plugins` xem Spotify Portal đã cài chưa.

### Lỗi npx không tìm thấy

Plugin gọi Portal CLI qua `npx`, nên máy cần có Node.js. Nếu terminal báo không nhận lệnh npx, hãy cài Node.js từ trang chính thức, mở lại terminal rồi chạy lại setup. README không nêu phiên bản Node tối thiểu, nếu gặp lỗi lạ hãy chạy doctor để xem chi tiết.

### Xác thực thất bại hoặc không có quyền

Chạy lại workflow setup và làm theo hướng dẫn đăng nhập. Nếu vẫn bị từ chối, nhiều khả năng tài khoản của bạn chưa có quyền trong Portal. Hãy hỏi quản trị viên Portal của tổ chức, đừng thử dùng tài khoản của người khác.

### Cài shunt nhưng không dùng được trong Codex hay Cursor

Hiện shunt chỉ hỗ trợ Claude Code. Trên các công cụ khác, bạn chỉ dùng plugin portal.

### Action không chạy hoặc chạy sai ý

Dừng lại, dùng bản xem trước (dry-run) và phần trợ giúp của action để kiểm tra tham số. Không xác nhận khi chưa hiểu bản xem trước. Nếu nghi ngờ lỗi của CLI, workflow feedback cho phép bạn gửi phản hồi tới đội Portal.

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

**Điểm mạnh:** cài đơn giản, hỗ trợ nhiều công cụ AI phổ biến, các workflow chia nhỏ dễ hiểu, có nhiều lớp an toàn (chỉ đọc, dry-run, xác nhận) và là sản phẩm chính thức của Spotify dưới giấy phép Apache-2.0.

**Giới hạn:** plugin chỉ có ích nếu tổ chức của bạn dùng Spotify Portal và bạn có tài khoản. Nếu không, bạn chưa có lý do cài. README cũng chưa ghi rõ phiên bản Node, hệ điều hành hỗ trợ hay chi phí liên quan. Shunt mới dành cho Claude Code. Plugin cũng không thay thế việc bạn đọc kỹ và chịu trách nhiệm với những gì mình xác nhận.

**Khi nào chọn cách khác:** nếu bạn chỉ cần tra cứu thỉnh thoảng, giao diện web của Portal có thể đủ. Nếu công ty không dùng Portal, hãy tìm plugin dành cho hệ thống bạn đang có. Còn nếu đội bạn đã dùng Portal hằng ngày và làm việc trong Claude Code, Codex, Cursor hay pi, bộ plugin này đáng thử vì giúp bạn khỏi chuyển qua lại giữa các cửa sổ.

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

### Spotify Portal AI Plugins có miễn phí không?

Repo dùng giấy phép Apache-2.0, bạn tải và cài được. Tuy nhiên README không nói về chi phí của Spotify Portal hay của các công cụ AI đi kèm, nên chưa có thông tin về phần đó. Bạn hỏi tổ chức mình về quyền dùng Portal.

### Plugin này chạy trên những công cụ nào?

README hướng dẫn cài cho Claude Code, Codex, Cursor và pi. Plugin shunt hiện chỉ dành cho Claude Code. Với Cursor, bạn đăng ký repo vào marketplace của team rồi cài trong Cursor Settings → Plugins.

### Mình cần cài riêng Portal CLI không?

Không có bước cài riêng trong README. Các workflow gọi CLI bằng lệnh npx @spotify/portal-cli, nên máy bạn cần có npx (đi kèm Node.js). Bước setup sẽ kiểm tra các lệnh auth, actions, owner, search và service.

### Có chạy được trên Windows không?

README không nói rõ về hệ điều hành. Các lệnh cài đều là lệnh của công cụ AI và npx nên về nguyên tắc không phụ thuộc hệ điều hành, nhưng chưa có thông tin xác nhận chính thức riêng cho Windows.

### Plugin có tự ý thay đổi gì trong hệ thống của mình không?

Theo README, workflow doctor, check-shift và troubleshoot-shift là chỉ đọc. Với action thì có trợ giúp, dry-run và xác nhận, còn việc mở PR cũng cần bạn xác nhận. Dù vậy bạn vẫn nên đọc kỹ bản xem trước trước khi đồng ý.

### shunt là gì và có cần cài không?

Shunt là plugin tùy 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 hay sinh code mẫu sang các chế độ AiKA chạy mô hình rẻ hơn để tiết kiệm token. Bạn không cần cài nó để dùng plugin portal.

### Plugin này khác gì dùng thẳng Portal CLI?

Plugin bọc Portal CLI thành các workflow cho trợ lý AI, nên bạn nhờ bằng ngôn ngữ tự nhiên và có thêm các lớp bảo vệ như dry-run, xác nhận. Nếu bạn quen CLI thì vẫn dùng thẳng được. README không so sánh chi tiết hơn.
