Chuyển tới nội dung
THứ HAI, THáNG 11 16, 2026TIN TỨC CÔNG NGHỆ ĐỘC LẬP, ĐÁNH GIÁ & HƯỚNG DẪN THỰC TẾ
GIỚI THIỆU
MỚI NHẤT /

Agent Skills và MCP server: cách cài đặt, cập nhật và sửa lỗi trong OpenCode, Claude Code, Codex và các AI agent khác

ĐỌC HƯỚNG DẪN
Tác nhân AIGM / 997

Agent Skills và MCP server: cách cài đặt, cập nhật và sửa lỗi trong OpenCode, Claude Code, Codex và các AI agent khác

Kỹ năng tác nhân và máy chủ MCP giải thích đơn giản: cài đặt, cập nhật và sửa trong OpenCode, Claude Code, Codex, với CLI npx skills từng bước.

Agent skills and MCP servers explained: a tech.grahammiranda.com title card with SKILL.md, npx skills, MCP servers and .agents/skills, and a terminal running npx skills check and opencode mcp add

Một agent lập trình AI vừa mới ra khỏi hộp giống như một nhân viên mới xuất sắc trong buổi sáng đầu tiên đi làm. Nó biết suy luận, viết mã và chạy lệnh, nhưng nó không biết nhóm của bạn làm việc thế nào, và nó không có chìa khóa vào các hệ thống của bạn. Agent skills và MCP server lấp đúng hai khoảng trống đó. Một skill là một cuốn cẩm nang bằng văn bản mà agent lấy xuống khỏi giá khi một nhiệm vụ cần đến. Một MCP server là một bộ chìa khóa: một chương trình nhỏ cho phép agent dùng thứ mà trước đây nó không thể chạm tới, chẳng hạn như các issue GitHub của bạn, một trình duyệt thật hay tài liệu được cập nhật.

Hướng dẫn này giải thích cả hai bằng ngôn ngữ dễ hiểu, rồi chỉ cho bạn cách cài đặt, cập nhật, gỡ bỏ và xử lý sự cố chúng trong OpenCode, Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot và Hermes Agent. Phần lớn nội dung hoạt động giống nhau ở mọi nơi, vì cả hai giờ đều là tiêu chuẩn mở. Về phía skills, một công cụ dòng lệnh nhỏ gắn kết mọi thứ lại với nhau, npx skills, và tôi sẽ đi qua nó từng lệnh một.

Tôi không được đào tạo để làm lập trình viên. Tôi điều hành một công ty IT nhỏ ở Đức và xây dựng phần mềm bằng các AI agent, nên tôi học phần lớn những thứ này theo cách mà có lẽ bạn cũng sẽ làm: bằng cách làm hỏng mọi thứ. Phần 6 được dựng từ chính các phiên terminal của tôi trên một chiếc Mac và một chiếc Raspberry Pi, kể cả lần mà công cụ báo với tôi rằng mọi skill của tôi đều mới nhất trong khi nó chưa kiểm tra nổi một cái nào.

Mọi thứ dưới đây đã được kiểm chứng với tài liệu chính thức của từng agent và, với kỹ năng CLI, với mã nguồn đã công bố của các phiên bản 1.5.18 đến 1.8.1, vào ngày 15 tháng 11 năm 2026. Những công cụ này thay đổi hàng tuần: riêng tuần này CLI đã phát hành hai bản, và OpenCode đạt 2.3.0 vào ngày 13 tháng 11. Số phiên bản và hành vi được ghi chú ở những chỗ dễ thay đổi. Hãy kiểm tra chúng trước khi dựa vào.

Tiết lộ: Không công ty nào được nhắc trong bài này tài trợ, xem xét hay phê duyệt bài viết, và bài không chứa liên kết tiếp thị nào. Sản phẩm chỉ được nêu tên trong văn bản; các hình ảnh dùng logo của chính tôi.


TL;DR — Agent Skills và MCP server trong mười gạch đầu dòng

  • Một skill là một thư mục có SKILL.md tệp: một tên và một mô tả ở trên cùng, hướng dẫn bên dưới, cùng các script hoặc tệp tham chiếu tùy chọn. Agent chỉ đọc phần mô tả cho đến khi một nhiệm vụ cần đến skill, nên một skill không dùng tốn khoảng 100 token trong sự chú ý của agent.
  • Một MCP server cung cấp cho agent những công cụ mới, chẳng hạn như GitHub, một trình duyệt hay tài liệu trực tiếp. Phần mô tả công cụ có thể đi kèm mọi yêu cầu, nên chỉ kết nối những server bạn dùng. Claude Code giờ hoãn chúng đến khi cần, còn OpenCode nhóm chúng theo server.
  • Quy tắc chung: quy tắc nội bộ cho mọi nhiệm vụ nằm trong AGENTS.md; kiến thức cần cho một số nhiệm vụ trở thành một skill; truy cập trực tiếp vào một hệ thống cần một MCP server; và nếu đã có một công cụ dòng lệnh tốt, một skill dạy agent dùng công cụ đó thường rẻ hơn một server.
  • Cả hai đều là tiêu chuẩn mở thuộc Agentic AI Foundation của Linux Foundation: MCP từ tháng 12 năm 2025, Agent Skills từ ngày 22 tháng 10 năm 2026. Một skill viết cho một agent thường hoạt động được trong các agent khác.
  • .agents/skills là thư mục dùng chung. Codex, OpenCode, Cursor, Gemini CLI và GitHub Copilot đều đọc .agents/skills trong một dự án và ~/.agents/skills trong thư mục home của bạn. Claude Code chỉ đọc .claude/skills, còn Hermes Agent đọc ~/.hermes/skills cùng mọi thư mục bạn thêm vào.
  • npx skills là npm dành cho kỹ năng. CLI mã nguồn mở của Vercel (phiên bản 1.8.1) cài kỹ năng vào 79 tác nhân: npx skills add owner/repo, -g cho mọi dự án, -a opencode -a claude-code để chọn tác nhân, npx skills ls để liệt kê và npx skills remove để gỡ cài đặt.
  • Để xem kỹ năng của bạn có phải bản mới nhất không, hãy chạy npx skills@latest check. Từ phiên bản 1.7.5 (2 tháng 11 năm 2026), nó chỉ báo cáo; npx skills update sẽ cài đặt. Ở các phiên bản trước, check âm thầm chạy cập nhật.
  • Đừng chỉ tin vào dấu tích xanh. Khi giới hạn 60 yêu cầu ẩn danh mỗi giờ của GitHub chặn mọi lần kiểm tra trên máy Mac của tôi, CLI vẫn in ra “Mọi kỹ năng toàn cục đều đã cập nhật”. Hãy chạy gh auth login hoặc đặt GITHUB_TOKEN, và đọc các dòng ✗.
  • Đừng bao giờ dùng sudo với kỹ năng hay tác nhân, và đừng chạy CLI từ thư mục home của bạn. Root có thư mục home riêng, nên sudo tạo ra một kho kỹ năng thứ hai, vô hình; và từ ~ CLI nhầm thư mục home của bạn là một dự án.
  • Hãy đối xử với kỹ năng và máy chủ MCP như phần mềm bạn cài đặt. Một cuộc kiểm tra hồi tháng 2 năm 2026 trên 3.984 kỹ năng công khai phát hiện lỗ hổng bảo mật ở 36,82% trong số đó và xác nhận 76 trường hợp có mã độc. Hãy đọc trước khi cài, ưu tiên kỹ năng từ chính nhà sản xuất công cụ, ghim phiên bản, và để các công cụ rủi ro ở chế độ “ask”.

Tổng quan về bốn khối cấu thành

Khối cấu thành Là gì, trong một dòng Hãy hình dung nó như Khi tác nhân đọc nó Giá bán Ví dụ
AGENTS.md (CLAUDE.md in Claude Code) Một tệp Markdown chứa quy tắc nội bộ cho một dự án Sổ tay nhân viên Vào đầu mỗi phiên, đọc toàn bộ Toàn bộ độ dài của nó, trong mọi yêu cầu “Dùng chính tả Anh-Anh. Chạy kiểm thử trước khi nói là xong.”
Kỹ năng Một thư mục có một SKILL.md công thức, cùng các script và tài liệu tham khảo tùy chọn Một thẻ công thức trong bìa hồ sơ Tên và mô tả ở đầu; công thức đầy đủ chỉ khi một tác vụ cần đến Khoảng 100 token mỗi kỹ năng cho đến khi nó’ được dùng “Cách chúng tôi viết ghi chú phát hành”
máy chủ MCP Một chương trình nhỏ trao cho tác nhân những công cụ mới Một bộ chìa khóa và bộ chuyển đổi Danh sách công cụ ở đầu (trừ khi tác nhân của bạn hoãn lại); từng công cụ khi được gọi Mô tả công cụ, thường có trong mọi yêu cầu Các issue trên GitHub, trình duyệt thật, tài liệu thư viện hiện hành
Plugin hoặc tiện ích mở rộng Một gói kỹ năng, máy chủ MCP và đôi khi cả hook Một bộ dụng cụ chào mừng Tùy thuộc vào những gì’ bên trong Tổng của các phần Superpowers, bộ dụng cụ khởi đầu của một nhà cung cấp
Giải thích skill tác nhân và máy chủ MCP: AGENTS.md như cuốn sổ tay luôn được nạp, skill như thẻ công thức chỉ nạp khi cần, máy chủ MCP như công cụ cho GitHub, trình duyệt và tài liệu trực tiếp, còn plugin là các gói
Bốn khối xây dựng, một tác nhân. Sổ tay luôn mở, thẻ công thức được lấy ra khi cần, và máy chủ MCP là chìa khóa cho mọi thứ bên ngoài terminal.

Mục lục


Phần 1 — Kỹ năng tác nhân và máy chủ MCP, giải thích dễ hiểu

Bức tranh về nhân viên mới

Hãy tưởng tượng bạn thuê một người xuất sắc. Ngày đầu tiên, bạn’ sẽ đưa cho họ ba thứ: một cuốn sổ tay ngắn ghi các quy tắc mọi người đều tuân theo, một bìa hồ sơ đựng công thức cho những việc nhóm bạn làm theo cách riêng của mình, và một bộ chìa khóa cùng thẻ ra vào để họ vào được những hệ thống cần thiết. Bạn’ cũng sẽ trao cho một số người bộ dụng cụ chào mừng gói vài công thức và chìa khóa lại với nhau.

Tác nhân AI cần đúng như vậy, và mỗi phần giờ đều có tên chuẩn:

  • Sổ tay là AGENTS.md (Claude Code gọi phiên bản của nó là CLAUDE.md).
  • Các công thức là kỹ năng.
  • Chìa khóa là máy chủ MCP.
  • Các bộ dụng cụ chào mừng là plugin, được gọi là tiện ích mở rộng trong một số tác nhân.

Phần còn lại của hướng dẫn này nói về các công thức và những chìa khóa, vì đó chính là nơi tập trung phần lớn sự nhầm lẫn.

Skill là gì

Một skill là một thư mục. Bên trong là một tệp bắt buộc, SKILL.md, và tùy chọn bất cứ thứ gì khác mà công việc cần:

release-notes/
├── SKILL.md          ← required: name, description, instructions
├── references/       ← optional: longer documents, read only when needed
├── scripts/          ← optional: code the agent can run
└── assets/           ← optional: templates, images, data files

Việc SKILL.md tệp có một tiêu đề ngắn nằm giữa hai --- dòng (tiêu đề đó được gọi là front matter), sau đó là các hướng dẫn thông thường:

---
name: release-notes
description: Writes App Store "What's New" notes from recent commits. Use when asked for release notes, a changelog or "what's new" text.
---

# Release notes

1. Read the commits since the last git tag.
2. Keep only changes a user would notice.
3. Write three to five short bullets in plain English, under 400 characters in total.

Tiêu chuẩn mở yêu cầu hai trường. Trường đặt tên chỉ được dùng chữ thường, số và dấu gạch nối, dài tối đa 64 ký tự và phải khớp với tên thư mục. Trường mô tả có thể dài tới 1.024 ký tự và nên nói rõ skill làm gì và dùng khi nào, vì phần mô tả chính là căn cứ để tác nhân quyết định có mở skill ra hay không.

Vì sao bạn có thể cài hàng chục skill: mẹo ba lớp

Skill được nạp theo từng lớp, mà tiêu chuẩn gọi là progressive disclosure. Hãy hình dung một giá sách:

  1. Phần bìa sau. Khi một phiên bắt đầu, tác nhân chỉ đọc tên và phần mô tả của từng skill. Đặc tả dành khoảng 100 token cho mỗi skill. (Token tương đương một từ ngắn hoặc một phần của từ; đó là đơn vị mà các mô hình dùng để đếm bộ nhớ làm việc của mình.)
  2. Chương sách. Khi một tác vụ khớp với phần mô tả, tác nhân sẽ đọc toàn bộ SKILL.md. Tiêu chuẩn khuyến nghị giữ nó dưới 5.000 token và 500 dòng.
  3. Phần phụ lục. Tệp tham chiếu và script chỉ được nạp khi phần hướng dẫn trỏ tới chúng.

Đó là lý do một trăm skill không dùng đến tốn ít hơn nhiều so với một cuốn sổ tay quy tắc dài. Tuy vậy nó không miễn phí: các phần mô tả cộng dồn lại, và các tác nhân đặt giới hạn cho chúng. Codex giới hạn danh sách skill ban đầu ở 2% bộ nhớ làm việc của mô hình (8.000 ký tự nếu không xác định được kích thước), còn Claude Code cắt phần liệt kê mỗi skill ở 1.536 ký tự. Hãy cài những gì bạn sẽ dùng.

Máy chủ MCP là gì

MCP, tức Model Context Protocol, là một tiêu chuẩn mở để kết nối các tác nhân AI với công cụ và dữ liệu. Anthropic giới thiệu nó vào tháng 11 năm 2024 và chuyển giao cho Agentic AI Foundation mới của Linux Foundation vào tháng 12 năm 2025, cùng với AGENTS.md của OpenAI và goose của Block.

Một máy chủ MCP là một chương trình nhỏ nói với tác nhân của bạn rằng: “đây là những công cụ tôi cung cấp”. Một máy chủ GitHub có thể cung cấp create_issue và search_code; một máy chủ trình duyệt cung cấp navigate và take_screenshot; một máy chủ tài liệu cung cấp query_docs. Tác nhân của bạn là MCP client: nó hiển thị danh sách cho mô hình, và khi mô hình muốn dùng một công cụ, tác nhân kiểm tra quyền của bạn, yêu cầu máy chủ chạy công cụ đó rồi chuyển kết quả trở lại.

Máy chủ có hai loại:

  • Máy chủ cục bộ chạy trên chính máy tính của bạn. Tác nhân khởi động chúng bằng một lệnh như npx @playwright/mcp@latest và giao tiếp với chúng qua đầu vào và đầu ra của chương trình (tên kỹ thuật là stdio).
  • Máy chủ từ xa chạy trên máy tính của nhà cung cấp. Bạn kết nối bằng một địa chỉ web, chẳng hạn https://mcp.context7.com/mcp, và thường đăng nhập qua trình duyệt hoặc dán khóa API. Tên kỹ thuật của kết nối này là Streamable HTTP.

Điểm mấu chốt là thế này. Mỗi công cụ đều có tên, mô tả và danh sách tham số, được viết để mô hình đọc. Trừ khi tác nhân của bạn hoãn chúng lại, những mô tả đó sẽ đi kèm mọi yêu cầu, và hai mươi máy chủ với mười công cụ mỗi cái khiến mọi câu trả lời chậm hơn, tốn kém hơn và kém tập trung hơn. Phần 7 cho thấy mỗi tác nhân xử lý việc này ra sao.

AGENTS.md và plugin, khái quát

AGENTS.md là một tệp Markdown đơn giản trong thư mục gốc của dự án, được tác nhân đọc khi bắt đầu mỗi phiên: mục đích của dự án, các lệnh, những điều không thể thương lượng. OpenCode, Codex, Cursor và GitHub Copilot đọc trực tiếp tệp này. Claude Code đọc CLAUDE.md thay vào đó, và tài liệu của nó gợi ý một CLAUDE.md chỉ đơn giản nhập tệp kia bằng một dòng như @AGENTS.md. Vì nó được tải mỗi lần, hãy giữ nó ngắn gọn và chuyển mọi thứ dành riêng cho tác vụ vào skill.

Plugin gộp các phần còn lại. Một plugin Claude Code có thể chứa skill, tác nhân phụ, hook (script chạy theo sự kiện), cùng máy chủ MCP và LSP. Codex, Cursor, GitHub Copilot CLI và Hermes Agent cũng có plugin, còn Gemini CLI gọi chúng là extension. Phần 9 sẽ nói về chúng.

Bảng thuật ngữ bỏ túi

Thuật ngữ Nghĩa ở đây
Agent (hoặc harness) Chương trình bạn trò chuyện cùng: OpenCode, Claude Code, Codex, v.v. Nó chạy mô hình, đọc tệp và gọi công cụ
Mô hình AI đảm nhiệm phần suy nghĩ, chẳng hạn GLM, Claude hay GPT
Cửa sổ ngữ cảnh Bộ nhớ làm việc của mô hình cho một yêu cầu. Mọi thứ bạn tải vào đều tranh nhau chỗ trong đó
Token Đơn vị mà mô hình dùng để đếm văn bản; xấp xỉ một từ ngắn hoặc một phần của từ
Kỹ năng Một thư mục có một SKILL.md tệp dạy tác nhân một công việc
Front matter Phần tiêu đề ở đầu SKILL.md, nằm giữa hai --- dòng
máy chủ MCP Một chương trình cung cấp công cụ cho tác nhân thông qua Model Context Protocol
Công cụ Một hành động mà máy chủ MCP cung cấp, chẳng hạn create_issue
stdio / Streamable HTTP Cách tác nhân giao tiếp với máy chủ cục bộ và máy chủ từ xa
OAuth Luồng “Đăng nhập bằng…” trong trình duyệt, cấp cho tác nhân một token mà bạn không phải dán mật khẩu
Phạm vi dự án / phạm vi toàn cục Chỉ cài cho một dự án, hoặc cho mọi dự án trên máy tính của bạn
Tệp khóa Một biên nhận liệt kê những gì bạn đã cài, cài từ đâu và dấu vân tay của từng skill
Liên kết tượng trưng Một lối tắt đến thư mục. CLI skills giữ một bản thật duy nhất và liên kết các tác nhân đến đó

Phần 2 — Kỹ năng, máy chủ MCP hay AGENTS.md? Bài kiểm tra năm câu hỏi

Khi bạn muốn tác nhân làm một việc gì đó tốt hơn, hãy đặt những câu hỏi này theo thứ tự và dừng lại ở câu “có” đầu tiên. Câu hỏi 4 là câu duy nhất có phần hỏi tiếp:

  1. Nó có phải đúng cho mọi tác vụ trong dự án này không? Đưa nó vào AGENTS.md. “Dùng chính tả Anh-Anh” và “chạy kiểm thử trước khi nói xong” thuộc về đây.
  2. Nó có bắt buộc phải được thực thi, chứ không chỉ là gợi ý? Dùng một quy tắc quyền hoặc một hook. Skill và AGENTS.md đều là chỉ dẫn, và mô hình có thể bỏ qua chỉ dẫn. “Không bao giờ push lên main” cần một deny quy tắc.
  3. Đây có phải là kiến thức chỉ cần cho một số tác vụ không? Hãy viết hoặc cài một skill. Quy trình phát hành, danh sách kiểm tra khi review, giọng điệu thương hiệu và quy trình làm việc test-first của bạn đều là skill.
  4. Tác nhân có cần truy cập trực tiếp vào một hệ thống nằm ngoài các tệp của nó không? Báo cáo sự cố của bạn nằm sau một trang đăng nhập, một trình duyệt mà nó có thể điều khiển, một ứng dụng quản lý dự án. Nếu đúng vậy, hãy hỏi câu 5 trước khi bạn với tới một máy chủ.
  5. Đã có sẵn một công cụ dòng lệnh tốt cho hệ thống đó chưa? Nếu có, một skill dạy tác nhân dùng công cụ đó thường tốt hơn một máy chủ: tác nhân vốn đã biết chạy lệnh, một CLI không tốn gì cho đến khi được dùng, và đầu ra của nó có thể được lọc trước khi đến mô hình. Nếu không có CLI tốt, nếu tác nhân của bạn không chạy được lệnh, hoặc nếu công việc mang tính tương tác (như điều khiển trình duyệt), hãy thêm một máy chủ MCP.

Đây là bài kiểm tra áp dụng cho mười mong muốn thường ngày:

Bạn muốn tác nhân… Dùng Tại sao
Luôn dùng chính tả Anh-Anh AGENTS.md Áp dụng cho mọi tác vụ
Không bao giờ push lên nhánh main Một quy tắc quyền Phải được thực thi, không chỉ gợi ý
Viết ghi chú phát hành theo cách bạn thích Một skill Kiến thức, thỉnh thoảng mới cần
Tuân theo quy trình làm việc test-first nghiêm ngặt Một skill (Superpowers có sẵn một cái) Một quy trình cho một số tác vụ
Đọc và tạo issue trên GitHub Một skill dạy gh, hoặc máy chủ MCP của GitHub gh thì rẻ hơn; máy chủ phù hợp với những tác nhân không chạy được lệnh
Tra cứu tài liệu hiện hành của một thư viện Một máy chủ MCP (Context7) hoặc CLI của nó với một skill (ctx7) Cả hai cách đều có dữ liệu trực tiếp
Nhấp qua ứng dụng web của bạn và chụp ảnh màn hình Một máy chủ MCP (Playwright) Nó cần một trình duyệt đang chạy mà tác nhân có thể điều khiển
Kiểm tra các vụ sập đêm qua Một máy chủ MCP (Sentry) Dữ liệu trực tiếp sau lớp đăng nhập
Tạo báo cáo PDF từ mẫu của bạn Một skill có script và mẫu bên trong assets/ Một quy trình cộng với công cụ đi kèm
Tránh xa .env tệp của bạn Một quy tắc quyền Điều đó phải được thực thi

Skill và máy chủ MCP không phải đối thủ. Một số thiết lập tốt nhất kết hợp cả hai: skill giải thích thời điểm và cách cách dùng công cụ của máy chủ, còn máy chủ làm phần việc. Codex còn cho phép skill khai báo những máy chủ MCP mà nó phụ thuộc, trong một trường tùy chọn agents/openai.yaml tệp.

Skill, máy chủ MCP hay AGENTS.md: quy trình năm câu hỏi đưa quy tắc cho mọi tác vụ vào AGENTS.md, quy tắc bắt buộc vào quyền, kiến thức chuyên môn vào skill, và quyền truy cập hệ thống trực tiếp vào một skill CLI hoặc một máy chủ MCP
Năm câu hỏi, hỏi theo thứ tự. Phần lớn mong muốn hóa ra lại là skill; máy chủ chỉ xứng chỗ khi tác nhân cần truy cập trực tiếp mà không có công cụ dòng lệnh nào đủ tốt.

Phần 3 — Mỗi tác nhân tìm kỹ năng ở đâu

Mọi tác nhân đều tìm ở hai loại vị trí. Thư mục dự án nằm trong kho mã của bạn, nên skill đi theo mã nguồn và đồng đội của bạn cũng có chúng. Thư mục cá nhân nằm trong thư mục home của bạn và áp dụng cho mọi dự án trên máy. Hầu hết công cụ gọi các bản cài cá nhân là toàn cục.

Năm 2026, các tác nhân hội tụ về một vị trí chung: .agents/skills trong một dự án và ~/.agents/skills trong thư mục home của bạn. Đặt một skill ở đó và hầu hết tác nhân sẽ tìm thấy mà không cần thêm gì.

Agent Thư mục dự án Thư mục cá nhân Tự gọi một skill Điều cần biết
OpenCode .opencode/skills, .agents/skills, .claude/skills ~/.config/opencode/skills, ~/.agents/skills, ~/.claude/skills Nhắc @skill-id trong prompt của bạn ID chính là tên thư mục. Kiểm soát skill bằng skill quyền
Claude Code .claude/skills ~/.claude/skills /skill-name Không đọc .agents/skills. Skill của plugin hiện dưới dạng /plugin-name:skill-name
Codex .agents/skills, trong mọi thư mục từ nơi bạn khởi động lên tới gốc kho mã ~/.agents/skills, cộng với /etc/codex/skills dành cho quản trị viên $skill-name, hoặc /skills Đi kèm một $skill-installer
Gemini CLI .agents/skills, .gemini/skills ~/.agents/skills, ~/.gemini/skills /skills list; mô hình sẽ xin phép bạn trước khi kích hoạt một cái .agents/skills sẽ thắng khi hai skill trùng tên
Cursor .agents/skills, .cursor/skills (và đọc .claude/skills và .codex/skills) ~/.agents/skills, ~/.cursor/skills /skill-name A paths giới hạn skill chỉ với các tệp khớp
GitHub Copilot .github/skills, .agents/skills, .claude/skills ~/.copilot/skills, ~/.agents/skills Tải skill khi thấy phù hợp Hoạt động trong Copilot CLI, agent trên cloud và chế độ agent trong VS Code và JetBrains
Hermes Agent .hermes/skills, .agents/skills, sau khi bạn chạy hermes skills trust ~/.hermes/skills, cùng mọi thư mục được liệt kê trong skills.external_dirs /skill-name, và tối đa năm cái liên tiếp Quét mọi bản cài từ hub để tìm nội dung độc hại

Đường dẫn lấy từ tài liệu của từng agent’ ngày 15 tháng 11 năm 2026. Các agent’ thêm vị trí mới thường xuyên; hãy kiểm tra trang skills của agent bạn nếu thứ gì đó không’ hiện ra.

Ba chi tiết giúp tránh nhầm lẫn

  • Claude Code là ngoại lệ. Nó chỉ đọc .claude/skills và ~/.claude/skills. CLI skills lo việc này giúp bạn bằng cách tạo một liên kết từ thư mục Claude Code’ tới bản dùng chung. Nếu bạn tự sao chép skill bằng tay, bạn’ sẽ phải tự đặt chúng (hoặc một symlink) vào thư mục của Claude Code.
  • Hermes Agent giữ thư viện riêng của mình. Thư mục chính của nó là ~/.hermes/skills. Để nó cũng đọc thư mục dùng chung, hãy thêm nó trong ~/.hermes/config.yaml:

yaml skills: external_dirs: - ~/.agents/skills

Hoặc cài bằng CLI skills và thêm -a hermes-agent. Chọn một cách thôi, đừng chọn cả hai, nếu không bạn’ sẽ có mỗi skill hai lần. – Tên trùng nhau gây ra những bất ngờ âm thầm. Mỗi agent có quy tắc riêng cho việc bản sao nào thắng. OpenCode đăng ký các thư mục theo một thứ tự cố định và cái cuối cùng thắng, còn thư mục của dự án bạn’ .opencode/skills thì đứng cuối cùng. Claude Code làm ngược lại: một skill cá nhân thắng một skill dự án cùng tên. Gemini CLI ưu tiên workspace hơn user và .agents hơn .gemini, còn Codex thì hiển thị cả hai. Cách khắc phục thì nhàm chán mà đáng tin: đừng’ giữ hai skill trùng tên.

OpenCode có hai điểm thêm đáng biết. Một tệp Markdown đơn lẻ ở ngay đầu một thư mục skills (chẳng hạn skills/review.md) cũng được tính là một skill, và một kỹ năng mảng trong opencode.jsonc có thể thêm thư mục phụ, thậm chí cả một danh mục skill trên web. Hướng dẫn OpenCode của tôi đi sâu hơn vào quyền của skill.

Nơi tác nhân AI tìm skill: thư mục dùng chung .agents/skills được Codex, OpenCode, Cursor, Gemini CLI và GitHub Copilot đọc, kèm liên kết cho .claude/skills của Claude Code và ~/.hermes/skills của Hermes Agent
Một thư mục dùng chung phủ hầu hết các tác nhân. Claude Code luôn cần một liên kết, còn Hermes Agent cần một liên kết cho kỹ năng toàn cục; công cụ CLI skills tạo cả hai.

Phần 4 — kỹ năng CLI: npm cho kỹ năng tác nhân, từng bước

Bạn có thể cài kỹ năng bằng cách sao chép thư mục qua lại, và với một hai cái thì cách đó ổn. Vượt qua mức ấy, bạn cần một trình quản lý gói: thứ biết mỗi tác nhân tìm ở đâu, giữ một bản sao thay vì năm, nhớ mỗi kỹ năng đến từ đâu, và báo cho bạn khi có phiên bản mới hơn. Đó chính là thứ mà kỹ năng làm được. Đây là công cụ dòng lệnh mã nguồn mở (MIT) từ Vercel Labs, bạn chạy nó với npx skills, và danh mục kỹ năng công khai của nó nằm tại skills.sh.

Những dữ kiện quan trọng tính đến ngày 15 tháng 11 năm 2026:

  • Phiên bản 1.8.1, phát hành ngày 11 tháng 11. Nó tiến rất nhanh: từ 1.7.5 lên 1.8.1 chỉ mất chín ngày.
  • Nó cần Node.js 22.20 trở lên.
  • Nó hỗ trợ 79 tác nhân, bao gồm OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot và Hermes Agent.
  • Nó cài đặt từ GitHub (owner/repo), GitLab, Azure Repos, bất kỳ địa chỉ Git nào, một thư mục cục bộ, hoặc liên kết tải trực tiếp tới một SKILL.md hoặc một tệp lưu trữ.

Bước 0 — Kiểm tra Node.js, và luôn yêu cầu phiên bản mới nhất

node --version      # cần v22.20.0 trở lên

Nếu lệnh đó in ra một phiên bản cũ hơn hoặc “command not found”, hãy cài bản LTS hiện tại từ nodejs.org. Trên máy Mac có Homebrew, brew install node cũng dùng được. Trên Raspberry Pi, phiên bản trong danh sách gói riêng của hệ điều hành thường quá cũ, nên hãy dùng bộ cài được liên kết từ chính trang đó.

Sau đó hãy biến một thói quen thành tự động: gõ npx skills@latest thay vì chỉ npx skills cho bất cứ việc gì mang tính kiểm tra hay cập nhật. Còn npx thì có thể dùng lại bản sao nó đã tải về từ nhiều tuần trước, và với công cụ này, phiên bản bạn chạy sẽ làm thay đổi điều các lệnh thực hiện (Phần 5 giải thích ví dụ lớn nhất).

Bước 1 — Xem trước khi cài

npx skills@latest add vercel-labs/agent-skills --list

--list hiển thị mọi kỹ năng trong kho kèm mô tả và không cài gì cả. Sau đó mở kho đó trong trình duyệt và đọc SKILL.md của bất cứ thứ gì bạn sắp cài, cùng mọi script đi kèm. Trên skills.sh, trang của mỗi kỹ năng cũng hiển thị kết quả kiểm tra bảo mật (Phần 11).

Bước 2 — Cài một kỹ năng cho các tác nhân bạn dùng

# Một kỹ năng, cho OpenCode và Claude Code, trong dự án hiện tại
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode -a claude-code

# Cùng kỹ năng đó cho mọi dự án trên máy này
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -a claude-code

# Ghim một thẻ phát hành hoặc một commit đầy đủ, để việc cập nhật diễn ra có chủ đích
npx skills add owner/[email protected] --skill my-skill

Bỏ qua --skill và -a và CLI sẽ hỏi bạn theo kiểu tương tác: kỹ năng nào, tác nhân nào, và liên kết hay sao chép. Đây là nơi mọi thứ được đặt:

Phạm vi Bản sao thật duy nhất Liên kết cho các tác nhân có thư mục riêng Bản ghi những gì bạn đã cài
Dự án (mặc định) ./.agents/skills/<name> ví dụ ./.claude/skills/<name> cho Claude Code ./skills-lock.json
Toàn cục (-g) ~/.agents/skills/<name> ví dụ ~/.claude/skills/<name>, ~/.hermes/skills/<name> ~/.agents/.skill-lock.json

CLI giữ một bản thật duy nhất trong .agents/skills, mà hầu hết tác nhân đọc trực tiếp, và tạo liên kết (symlink, thực chất là lối tắt) cho những tác nhân tìm ở nơi khác. Một bản nghĩa là một lần cập nhật. Nếu hệ thống của bạn không xử lý symlink tốt, điều có thể xảy ra trên Windows, hãy thêm --copy để có các bản sao độc lập thay thế.

Bước 3 — Xem những gì đã cài

npx skills ls              # kỹ năng của dự án này
npx skills ls -g           # kỹ năng toàn cục của bạn
npx skills ls -a opencode  # chỉ những gì OpenCode nhận
npx skills ls --json       # dạng máy đọc được, dành cho script

Với skill của dự án, các phiên bản hiện tại cũng hiển thị một trạng thái: được theo dõi (khớp với tệp lock), đã sửa đổi (bạn hoặc tác nhân đã sửa nó), không được theo dõi (không có mục trong tệp lock, ví dụ skill bạn tự viết) hoặc bị thiếu (có trong tệp lock nhưng không có trên đĩa).

Bước 4 — Tìm skill

npx skills find                    # tìm kiếm tương tác
npx skills find seo                # tìm theo từ khóa
npx skills find react --owner vercel   # chỉ kho của một tổ chức

Hoặc duyệt skills.sh, nơi xếp hạng skill theo số lượt cài và nhóm chúng theo chủ đề. Skill được cài nhiều nhất ở đó hiện nay là find-skills từ chính kho của Vercel, dạy tác nhân của bạn tự tìm skill. Số lượt cài thay đổi hằng ngày, nên hãy coi bảng xếp hạng là một gợi ý, không phải một đánh giá.

Bước 5 — Dùng thử một skill mà không cần cài

npx skills use vercel-labs/agent-skills@web-design-guidelines

Lệnh này in ra một prompt dựng sẵn cho skill đó, bạn có thể pipe hoặc dán vào một tác nhân trên cùng máy. Thêm --agent claude-code và CLI khởi động Claude Code với skill đã nạp. Đây là cách tốt để thử một skill trước khi nó trở thành một phần trong thiết lập của bạn.

Bước 6 — Gỡ skill

npx skills remove web-design-guidelines            # khỏi dự án này
npx skills rm --global web-design-guidelines       # khỏi kỹ năng toàn cục của bạn
npx skills remove --agent claude-code my-skill     # chỉ khỏi một agent
npx skills remove vercel-labs/agent-skills         # mọi thứ từ nguồn đó
npx skills remove                                  # chọn từ danh sách

npx skills remove --all gỡ mọi skill được ghi trong tệp lock và bỏ qua những thư mục mà nó không cài, ví dụ skill bạn tự viết, nên nó sẽ không xóa công việc của chính bạn.

Bước 7 — Tự tạo skill của bạn

npx skills init my-skill tạo ra my-skill/SKILL.md từ một mẫu. Phần 10 sẽ đi qua một ví dụ đầy đủ.

Toàn bộ công cụ trên một thẻ

Tôi muốn… Lệnh
Xem một kho có những gì npx skills@latest add owner/repo --list
Cài một skill vào dự án này npx skills add owner/repo --skill name
Cài cho mọi dự án add -g
Chọn các tác nhân add -a opencode -a claude-code (hoặc --agent '*' cho tất cả)
Cài đặt không hỏi gì add -y
Ghim một phiên bản npx skills add owner/[email protected] --skill name
Liệt kê các skill đã cài npx skills ls · npx skills ls -g
Tìm kiếm npx skills find keyword
Kiểm tra bản cập nhật (chỉ đọc) npx skills@latest check · add -g hoặc -p
Cài bản cập nhật npx skills update · -g · -p · -y · hoặc nêu tên các skill
Gỡ bỏ npx skills remove name · add -g cho toàn cục
Khôi phục skill của dự án từ tệp lock của nó npx skills install
Bắt đầu một skill mới npx skills init name

Các lệnh cho skills 1.8.1. npx skills install (một bí danh của experimental_install) và lệnh experimental_sync cho các skill đi kèm trong gói npm đều được đánh dấu là thử nghiệm và có thể thay đổi.

Bảng tóm tắt CLI npx skills: các lệnh add, list, find, use, check, update, remove và init cùng những cờ hữu ích nhất, vị trí cài đặt theo dự án và toàn cục, và hai tệp lock
CLI skills trên một tấm thẻ. Hai thói quen làm nên phần lớn công việc: --list trước khi bạn cài đặt, và @latest mỗi khi bạn kiểm tra hoặc cập nhật.

Tệp lock là gì, và tôi có nên commit nó không?

Tệp lock giống như một biên lai. Với mỗi skill, nó ghi lại nguồn gốc và một dấu vân tay của thư mục đó (về mặt kỹ thuật là một hash: một mã ngắn thay đổi mỗi khi bất kỳ tệp nào trong thư mục thay đổi). CLI lưu hai loại:

  • skills-lock.json trong một dự án. Hãy commit nó vào Git. Trên một máy khác, hoặc cho một đồng nghiệp, npx skills install khôi phục đúng những skill đó, và --frozen-lockfile (mặc định trong CI) từ chối tiếp tục nếu có bất cứ điều gì khác biệt. Điều đó khiến skill của một dự án có thể tái lập được, giống như package-lock.json làm với mã nguồn.
  • ~/.agents/.skill-lock.json cho các skill toàn cục của bạn. Nó thuộc về tài khoản người dùng của bạn (hoặc nằm tại $XDG_STATE_HOME/skills/.skill-lock.json nếu bạn đã đặt biến đó). Đừng sửa tệp này bằng tay, và lưu ý rằng mỗi người dùng trên một máy tính đều có tệp riêng, điều này quan trọng ở Phần 6.

Về telemetry, gói gọn

CLI gửi dữ liệu sử dụng ẩn danh. Theo tài liệu của nó, tên kho GitHub và tên skill chỉ được đưa vào khi GitHub xác nhận kho đó là công khai; các loại nguồn khác cũng có thể được nêu tên. Để tắt tính năng này, hãy thêm export DISABLE_TELEMETRY=1 (hoặc DO_NOT_TRACK=1) vào hồ sơ shell của bạn. Thao tác đó cũng tắt các lần tra cứu kiểm tra bảo mật mà CLI thực hiện cho các skill công khai, nên hãy cân nhắc xem bạn coi trọng cái nào hơn.

Những trình cài đặt khác bạn sẽ gặp

CLI skills không phải là cách duy nhất. Một số tác nhân và công cụ có trình cài đặt riêng, và tất cả đều tuân theo cùng một chuẩn mở:

Công cụ Ví dụ Nên biết
GitHub CLI (gh skill, phiên bản 2.90 trở lên, dạng xem trước) gh skill install owner/repo skill-name --agent claude-code gh skill preview hiển thị một skill trước khi bạn cài đặt nó; --pin khóa một phiên bản
Hermes Agent hermes skills install <identifier> Hub của nó bao gồm skills.sh, và mọi bản cài đặt đều được quét bảo mật
Gemini CLI gemini skills install <git-url> --scope workspace cho một dự án; sẽ hỏi ý kiến trừ khi bạn truyền --consent
Codex $skill-installer <name> Một skill hệ thống tích hợp sẵn
Claude Code /plugin install name@marketplace Plugin gộp skill cùng máy chủ MCP và hook (Phần 9)

Một quy tắc ngăn được phần lớn rắc rối: cập nhật một skill bằng đúng công cụ bạn đã dùng để cài nó. Mỗi trình cài đặt lưu hồ sơ riêng, và không cái nào biết cái khác đã làm gì.


Phần 5 — “Gói kỹ năng của tôi đã được cập nhật hai ngày trước. Làm sao tôi biết mình đã có nó?”

Đó chính là câu hỏi của tôi khi Superpowers, thư viện skill phổ biến của Jesse Vincent, công bố một bản cập nhật. npx skills ls chỉ liệt kê tên, không liệt kê phiên bản, nên nó không thể cho bạn biết. Đây là cách CLI thực sự biết.

Cách bước kiểm tra hoạt động

Khi bạn cài một skill, CLI lưu dấu vân tay của thư mục đó vào tệp khóa. Khi bạn kiểm tra, nó hỏi nguồn (thường là GitHub) dấu vân tay của cùng thư mục đó ở thời điểm hiện tại. Cùng dấu vân tay: đã cập nhật. Khác: có bản cập nhật. Nó không so sánh số phiên bản hay ngày tháng, đó là lý do nó vẫn hoạt động với cả những skill không có cả hai thứ đó.

cd /tmp                        # hoặc một thư mục dự án, nhưng đừng bao giờ là thư mục home của bạn
npx skills@latest check -g     # skill toàn cục của bạn

cd ~/code/my-app
npx skills@latest check -p     # skill của dự án này

Kết quả thường thấy ở phiên bản 1.8.1 trông như sau:

↑ brainstorming has an update
↑ writing-plans has an update
2 skill(s) can be updated; run npx skills update to install

check cũng báo cáo các skill của dự án mà tệp không còn khớp với tệp lock (có thay đổi cục bộ), và nó thoát với mã lỗi mỗi khi có thứ gì đó lỗi thời hoặc bị sửa, nên bạn có thể dùng nó để chặn một bản build CI đã bị lệch.

check đã thay đổi trong tháng 11, nên hãy chạy phiên bản mới nhất

Từ phiên bản 1.7.5 (2 tháng 11 năm 2026), check chỉ báo cáo. Ở các phiên bản trước, từ ít nhất 1.5.18 đến 1.7.4, check chỉ đơn giản là một tên khác của update: nó hỏi “Update scope?” và cài đặt bản cập nhật ngay trong lúc chạy. Nếu bạn đã dùng npx skills check trước tháng 11 và tự hỏi tại sao nó lại đang “cập nhật” mọi thứ, thì đó là lý do. Dùng npx skills@latest check và bạn sẽ có hành vi chỉ đọc.

Hai chi tiết nữa khiến nhiều người vấp:

  • check tự chọn một phạm vi. Nếu thư mục bạn đang ở có một skills-lock.json tệp, hoặc một .agents/skills thư mục có chứa skill, nó sẽ kiểm tra dự án skill; nếu không thì nó kiểm tra toàn cục các skill toàn cục. Thêm -g hoặc -p để nói rõ bạn muốn cái nào.
  • Không có tùy chọn “cập nhật mọi thứ từ một kho lưu trữ”. Hoặc cập nhật mọi thứ trong một phạm vi, hoặc nêu tên từng skill.

Sau đó cập nhật

npx skills update                      # hỏi: dự án, toàn cục hay cả hai
npx skills update -g                   # mọi kỹ năng toàn cục
npx skills update -p                   # mọi kỹ năng của dự án
npx skills update brainstorming writing-plans -g   # chỉ những cái này
npx skills update -y                   # không hỏi gì: dự án nếu bạn đang trong một dự án, ngược lại là toàn cục

Hãy đọc các thay đổi trước khi cập nhật bất cứ thứ gì quan trọng. Mở lịch sử commit của kho lưu trữ trên GitHub và xem những gì đã thay đổi trong các thư mục skill: một bản cập nhật là những chỉ dẫn mới mà tác nhân của bạn sẽ làm theo với quyền của bạn.

Nếu bạn cài nó dưới dạng plugin, hãy cập nhật nó như một plugin

Nhiều bộ skill giờ được phân phối dưới dạng plugin, và Superpowers là một ví dụ điển hình. README của nó liệt kê một cách cài khác nhau cho gần như mọi tác nhân:

Agent Cài Superpowers, theo README của nó Cách nó cập nhật
Claude Code /plugin install superpowers@claude-plugins-official Tự động, từ marketplace chính thức của Anthropic
Codex CLI /plugins, tìm “superpowers”, rồi Install Plugin Qua trình quản lý plugin
Cursor /add-plugin superpowers trong chat Agent Qua trình quản lý plugin
Gemini CLI gemini extensions install https://github.com/obra/superpowers gemini extensions update superpowers
GitHub Copilot CLI copilot plugin marketplace add obra/superpowers-marketplace, sau đó copilot plugin install superpowers@superpowers-marketplace Qua trình quản lý plugin
Hermes Agent hermes plugins install obra/superpowers --enable Qua trình quản lý plugin
OpenCode Thêm "superpowers@git+https://github.com/obra/superpowers.git" vào plugin danh sách trong opencode.json, như hướng dẫn cài đặt OpenCode của nó mô tả Khi khởi động lại; xóa bộ nhớ đệm gói của OpenCode nếu phiên bản mới không xuất hiện, hoặc thêm #v5.0.3-style tags để ghim

Từ README của Superpowers và hướng dẫn cài đặt OpenCode của nó, kiểm tra ngày 15 tháng 11 năm 2026.

Tôi đã cài Superpowers trên Mac của mình bằng npx skills -g, nên bản của tôi cập nhật qua skills CLI. Như vậy thì ổn. Điều không ổn là cài cùng một gói qua hai kênh: bạn sẽ có hai bản sao của mọi skill dưới những cái tên giống hệt nhau, và không có cách nào biết tác nhân sẽ chọn bản nào.

Cách npx skills check hoạt động: tệp lock lưu dấu vân tay của từng thư mục skill, check so sánh nó với chính thư mục đó ở nguồn gốc và báo cáo bản cập nhật, còn update sẽ cài đặt chúng
check so sánh dấu vân tay, không phải số phiên bản. Từ 1.7.5 nó chỉ báo cáo; update là lệnh thực sự thay đổi mọi thứ.

Phần 6 — Năm vấn đề thực tế từ Mac và Raspberry Pi của tôi, và cách khắc phục

Mọi chuyện trong phần này đã xảy ra với tôi vào mùa hè năm 2026, trên phiên bản 1.5 của CLI. Mỗi vấn đề sau đó đều đã được đối chiếu với mã nguồn của bản phát hành hiện tại, 1.8.1, để bạn biết cái nào đã được sửa và cái nào vẫn còn gây khó chịu. Kết quả đầu cuối là thật; tôi đã rút gọn và bỏ tên máy.

Vấn đề 1: “Mọi skill toàn cục đều đã cập nhật”, khi không có gì được kiểm tra

Trên Mac của tôi, npx skills check cho ra kết quả này:

graham@mac my-app % npx skills check
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
Checking skills from source: anthropics/skills
│  GitHub API request limit reached; checking existing gh authentication…
  ✗ Failed to fetch tree for anthropics/skills
Checking skills from source: vercel-labs/skills
  ✗ Failed to fetch tree for vercel-labs/skills
…                                  (six more sources, every one ✗)
Checking skills from source: obra/superpowers
  ✗ Failed to fetch tree for obra/superpowers
✓ All global skills are up to date

Chuyện gì đã xảy ra. Để kiểm tra một kho, CLI hỏi API của GitHub danh sách tệp của kho đó. GitHub cho phép 60 yêu cầu ẩn danh mỗi giờ mỗi địa chỉ internet, và hạn mức của tôi cho giờ đó đã cạn (công cụ nói vậy ngay dòng đầu), nên mọi lần tra cứu đều thất bại. Dòng cuối chỉ đếm những bản cập nhật mà công cụ tìm thấy, và nó không tìm thấy cái nào, nên nó in ra một dấu tích xanh. Bản cũ còn cố mượn đăng nhập của GitHub CLI ở phía sau (đó là dòng “checking existing gh authentication”); vì mọi yêu cầu vẫn thất bại, rõ ràng không có đăng nhập nào để mượn.

Đã được sửa chưa? Một phần. Phiên bản 1.8.1 cố gắng nhiều hơn trước khi bỏ cuộc: trước tiên là ẩn danh, rồi đến token từ môi trường của bạn, rồi đến đăng nhập của chính GitHub CLI qua gh api, và với kiểm tra cập nhật thì tải Git thuần như phương án cuối. Nhưng mã nguồn 1.8.1 cho thấy khi một nguồn vẫn không kiểm tra được, dòng tóm tắt vẫn chỉ đếm những bản cập nhật mà nó tìm thấy. Vẫn có thể có một dấu tích xanh bên dưới những dấu gạch chéo đỏ, nên hãy đọc các dòng ✗.

Cách khắc phục. Cho CLI một đăng nhập, việc này nâng giới hạn lên 5.000 yêu cầu mỗi giờ:

  1. Dễ nhất: cài GitHub CLI và chạy gh auth login. Các phiên bản hiện tại của skills CLI yêu cầu gh thực hiện lệnh gọi API và không bao giờ nhìn thấy thông tin đăng nhập của bạn.
  2. Hoặc dùng token: tạo một token truy cập cá nhân tinh chỉnh với quyền chỉ đọc đối với các kho công khai, rồi thêm nó vào hồ sơ shell của bạn (~/.zshrc trên Mac, ~/.bashrc trên Raspberry Pi):

bash export GITHUB_TOKEN="github_pat_…" # read-only, public repositories

Sau đó hãy mở một terminal mới. Hãy đối xử với token như mật khẩu: đừng bao giờ dán nó vào chat, vào một skill hay vào tệp bạn commit. 3. Nâng cấp và kiểm tra lại: npx skills@latest check -g.

Vấn đề 2: sudo đã cho tôi hai kho skill và một lỗi npm

Trên chiếc Raspberry Pi của tôi, tôi đã quen tay gõ sudo su trước tiên. Đây là những gì nó tạo ra:

graham@pi:~ $ sudo su
root@pi:/home/graham# npx skills update
npm error config prefix cannot be changed from project config: /home/graham/.npmrc.
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
…
Found 6 global update(s)
…
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

Và một lát sau, quay lại với người dùng thường của tôi:

graham@pi:~ $ ls ~/.agents/skills | wc -l
7
graham@pi:~ $ sudo ls /root/.agents/skills | wc -l
37

Chuyện gì đã xảy ra. sudo su biến bạn thành root, và root có thư mục home riêng, /root. Skill được lưu theo từng người dùng, nên skill toàn cục của root nằm trong /root/.agents/skills và của tôi trong /home/graham/.agents/skills. Mọi lần cài đặt toàn cục tôi từng thực hiện bằng root đều rơi vào kho của root: 37 skill ở đó, 7 ở của tôi. Nếu các tác nhân của bạn chạy dưới người dùng thường, vốn là thiết lập phổ biến, thì mọi thứ trong kho của root đều vô hình với chúng.

Lỗi npm có cùng nguyên nhân. Khi là root, tệp cài đặt cá nhân của npm là /root/.npmrc, nên /home/graham/.npmrc nằm trong thư mục tôi đang ở bị đọc thành một dự án tệp cài đặt thay thế. Mã của chính npm từ chối cho một tệp dự án thay đổi prefix cài đặt đó, và ghi log đúng lỗi ấy. Có một rủi ro thứ ba bạn không thấy ngay: bất cứ thứ gì root ghi vào trong thư mục home của bạn sẽ thuộc sở hữu của root, và người dùng thường của bạn không thể cập nhật nó về sau.

Cách khắc phục.

  1. Rời khỏi root: type exit. Từ giờ, hãy chạy CLI và các tác nhân của bạn dưới chính người dùng của bạn.
  2. Tìm xem các tác nhân của bạn dùng người dùng nào. Thư mục home nào chứa cài đặt của chúng mới là thư mục quan trọng:

bash ls -d ~/.claude ~/.config/opencode ~/.hermes 2>/dev/null sudo ls -d /root/.claude /root/.config/opencode /root/.hermes 2>/dev/null

  1. Cài lại skill của root dưới chính người dùng của bạn, từ nguồn gốc của chúng. Sao chép các tệp sang sẽ mang theo quyền sở hữu của root và các bản ghi cũ. Cài lại sẽ ghi một tệp lock sạch. Đầu tiên hãy liệt kê các nguồn root đã dùng:

bash sudo grep '"source"' /root/.agents/.skill-lock.json | sort -u

Sau đó, từ một thư mục dự án hoặc /tmp, hãy chạy npx skills add <owner/repo> -g -a <your agents> cho mỗi cái bạn vẫn muốn giữ. 4. Trả lại các thư mục của chính bạn cho bạn, phòng khi root đã ghi vào chúng:

bash sudo chown -R "$(id -un)":"$(id -gn)" ~/.agents ~/.claude ~/.hermes ~/.config/opencode 2>/dev/null

  1. Chỉ khi mọi thứ chạy được dưới tài khoản của bạn, hãy xóa bản sao của root bằng sudo rm -rf /root/.agents.

Nếu bạn dùng sudo vì cài đặt npm toàn cục sẽ thất bại nếu thiếu nó, hãy sửa điều đó thay vào: trỏ prefix của npm vào một thư mục bạn sở hữu (npm config set prefix ~/.npm-global, rồi thêm ~/.npm-global/bin vào PATH). Đó gần như chắc chắn là điều mà prefix dòng trong tệp .npmrc của riêng tôi đang làm.

Vấn đề 3: chạy từ thư mục home của bạn, và nó trở thành một “dự án”

Quay lại với tài khoản của mình, trong thư mục home:

graham@pi:~ $ npx skills check
Need to install the following packages:
[email protected]
Ok to proceed? (y) y
…
Global Skills
No global skills tracked in lock file.
Install skills with npx skills add <package> -g
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

Chuyện gì đã xảy ra. CLI coi một thư mục là dự án nếu nó chứa một skills-lock.json tệp hoặc một .agents/skills thư mục có skill bên trong. Thư mục home của bạn chứa ~/.agents/skills, vì đó là nơi các skill toàn cục sống, nên từ ~ CLI thấy một dự án. Và nếu bạn từng chạy npx skills add trong thư mục home của bạn không cần -g, bạn đã tạo một bản cài đặt dự án thật ở đó, với ~/skills-lock.json, mà thư mục skill của nó chính là thư mục mà bản cài đặt toàn cục dùng. Đó chính là những gì đã xảy ra trên chiếc Pi của tôi: bảy skill được theo dõi như một “dự án” trong thư mục home của tôi, và không có gì cả trong tệp lock toàn cục của riêng tôi.

“Không có skill toàn cục nào được theo dõi trong tệp lock” có ba nguyên nhân phổ biến: bạn chưa bao giờ cài bằng -g, bạn đã cài bằng -g dưới một người dùng khác (root, thông qua sudo), hoặc tệp lock đã bị xóa. Nếu bạn đọc ở đâu đó rằng một generate-lock lệnh sẽ dựng lại nó, thì lệnh đó không tồn tại: không có lệnh như vậy trong phiên bản 1.5 hay 1.8.

Cách khắc phục.

  • Chạy CLI từ một thư mục dự án hoặc /tmp, không bao giờ từ ~, và truyền -g hoặc -p để nó không thể đoán.
  • Để gỡ rối một “dự án” nằm trong thư mục home, hãy cài lại những skill bạn muốn bằng -g từ một thư mục khác (chúng nằm ở cùng một chỗ, giờ được ghi vào tệp lock toàn cục của bạn), rồi xóa ~/skills-lock.json. Đừng chạy npx skills remove từ ~ cho việc này: trong thư mục home của bạn, thư mục dự án và thư mục toàn cục là cùng một thư mục.

Vấn đề 4: “Không tìm thấy kỹ năng phù hợp” vì dấu hai chấm

graham@pi:~ $ npx skills remove ckm:banner-design ckm:brand ckm:design \
  ckm:design-system ckm:slides ckm:ui-styling
◇  Found 7 unique installed skill(s)
■  No matching skills found for: ckm:banner-design, ckm:brand, ckm:design, ckm:design-system, ckm:slides, ckm:ui-styling

Chuyện gì đã xảy ra. Những kỹ năng đó hiển thị dưới dạng ckm:banner-design, nhưng dấu hai chấm là ký tự rủi ro trong tên thư mục, nên CLI đã lưu chúng dưới dạng ckm-banner-design: nó chuyển tên thành chữ thường và biến mọi thứ không phải chữ cái, chữ số, dấu chấm và dấu gạch dưới thành dấu gạch nối. Phiên bản 1.5.18 so sánh nguyên văn những gì tôi gõ với tên thư mục, nên không có gì khớp.

Đã được sửa chưa? Có. Các phiên bản hiện tại chuyển đổi dữ liệu bạn nhập theo cùng cách trước khi so sánh, nên ckm:brand và ckm-brand cả hai đều dùng được, và khi không có gì khớp, 1.8.1 in ra những tên được đã cài đặt.

Cách khắc phục. Chạy npx skills ls (hoặc ls ~/.agents/skills) để xem tên thật, hoặc chạy npx skills remove không có đối số rồi chọn từ danh sách. Cũng hãy kiểm tra phạm vi: khi ở trong thư mục dự án, gỡ một kỹ năng được ghi trong lock toàn cục giờ sẽ nhắc bạn thêm -g.

Vấn đề 5: sáu kỹ năng lỗi, một kỹ năng từ cùng kho vẫn chạy được

Refreshing 7 skill(s)…
✗ Failed to check for deleted skills from nextlevelbuilder/ui-ux-pro-max-skill
Updating ckm:banner-design…
  ✗ Failed to update ckm:banner-design
…                                  (five more ✗)
Updating ui-ux-pro-max…
  ✓ Updated ui-ux-pro-max

Chuyện gì đã xảy ra. Để cập nhật một kỹ năng, CLI tìm lại nó trong kho nguồn của nó. Sáu trong bảy kỹ năng của tôi từ kho đó không tìm thấy, trong khi kỹ năng thứ bảy cập nhật bình thường. Khi hầu hết kỹ năng từ một nguồn đều lỗi mà một cái vẫn thành công, thì những cái mất tích thường đã bị đổi tên, di chuyển hoặc xoá ở phía nguồn. README của kho đó hôm nay chỉ mô tả một kỹ năng, ui-ux-pro-max, và chỉ nhắc đến banner, nhận diện thương hiệu và slide như các tính năng của một gói trả phí, điều này khớp với việc sáu kỹ năng kia đã rời kho miễn phí.

Cách khắc phục. Xem nguồn hiện cung cấp gì, rồi gỡ những gì đã mất:

npx skills add nextlevelbuilder/ui-ux-pro-max-skill --list
npx skills remove ckm-banner-design ckm-brand ckm-design ckm-design-system ckm-slides ckm-ui-styling

Các phiên bản CLI hiện tại nhận ra những kỹ năng đã bị xoá ở phía nguồn và đề nghị dọn chúng trong lúc cập nhật, đồng thời gỡ các kỹ năng mất tích khỏi tệp lock khi bạn gỡ cài đặt. Nhân tiện, hãy tìm các bản trùng: nếu bạn cũng có một kỹ năng brand đơn giản cạnh ckm-brand, hãy giữ một. Hai kỹ năng có mô tả gần như giống nhau khiến tác nhân chọn nhầm và lãng phí ngân sách danh sách của nó.

Thêm một mục: Claude Code không thấy kỹ năng mà CLI đã cài

  • Kiểm tra liên kết. Claude Code chỉ đọc thư mục của riêng nó, nên ls -la ~/.claude/skills (hoặc .claude/skills trong dự án) phải hiển thị kỹ năng, thường là một liên kết trỏ vào .agents/skills. Một số bản phát hành 1.5 đã sửa lỗi liên kết của Claude Code (1.5.16 và 1.5.20), nên nếu thiếu, hãy cài lại bằng npx skills@latest add … -a claude-code.
  • Kiểm tra xem tệp có mở đầu đúng không. Dòng mở đầu --- của front matter phải là dòng đầu tiên của SKILL.md, nếu không Claude Code sẽ coi toàn bộ tệp là văn bản thuần.
  • Tải lại. Claude Code nhận kỹ năng đã sửa ngay lập tức, nhưng thư mục kỹ năng được tạo sau khi phiên bắt đầu cần /reload-skills. Sau đó /skills liệt kê những gì’ đang được nạp.
Xử lý sự cố npx skills: năm lỗi thật và cách khắc phục, từ thông báo mọi thứ đã cập nhật sai sau khi bị giới hạn tần suất GitHub, đến việc sudo tạo kho skill thứ hai, thư mục home bị coi là dự án và skill bị xóa ở nguồn gốc
Năm lỗi, năm cách khắc phục. Phần lớn đều quy về cùng hai quy tắc: đọc các dòng ✗, và không bao giờ chạy CLI với quyền root hoặc từ thư mục home của bạn.

Phần 7 — Máy chủ MCP không cần thuật ngữ

Điều gì xảy ra khi bạn kết nối một máy chủ

  1. Bạn thêm máy chủ vào cài đặt của tác nhân’ bạn: một lệnh cho máy chủ cục bộ, một địa chỉ web cho máy chủ từ xa.
  2. Khi một phiên bắt đầu, tác nhân khởi chạy máy chủ cục bộ hoặc kết nối tới máy chủ từ xa, và đăng nhập nếu máy chủ yêu cầu.
  3. Máy chủ liệt kê các công cụ của nó, và tác nhân chuyển mô tả của chúng cho mô hình.
  4. Khi một tác vụ cần một công cụ, mô hình yêu cầu công cụ đó, tác nhân của bạn kiểm tra các quy tắc cấp quyền (và có thể hỏi bạn), máy chủ thực hiện công việc, rồi kết quả quay trở lại cuộc hội thoại.

Cục bộ hay từ xa?

Máy chủ cục bộ (stdio) Máy chủ từ xa (Streamable HTTP)
Chạy Trên máy tính của bạn, do tác nhân khởi chạy Trên máy tính’ của nhà cung cấp
Bạn thêm Một lệnh, ví dụ npx @playwright/mcp@latest Một địa chỉ, ví dụ https://mcp.context7.com/mcp
Đăng nhập Thường là khóa API trong một biến môi trường Thường là OAuth trong trình duyệt của bạn, hoặc một khóa trong header
Cần Node.js, Python hoặc Docker, tùy theo máy chủ Kết nối internet
Phù hợp nhất Những thứ trên máy của bạn: trình duyệt, tệp, cơ sở dữ liệu cục bộ Dịch vụ đám mây: GitHub, Sentry, tài liệu, công cụ dự án
Cần lưu ý Nó chạy với toàn bộ quyền của người dùng bạn’ Dữ liệu của bạn được gửi tới nhà cung cấp đó

Bạn vẫn có thể thấy kiểu thứ ba, SSE, trong các hướng dẫn cũ. Tài liệu của Claude Code’ đánh dấu nó là không còn được dùng; hãy dùng địa chỉ HTTP khi máy chủ cung cấp cả hai.

Đôi điều về phiên bản

Đặc tả MCP hiện hành, phát hành ngày 28 tháng 7 năm 2026, là bản sửa đổi lớn nhất kể từ khi giao thức ra đời: phần lõi giờ đây không lưu trạng thái, cho phép máy chủ từ xa chạy sau những bộ cân bằng tải thông thường. Bạn hiếm khi cần bận tâm, vì máy khách và máy chủ thống nhất phiên bản sẽ dùng, và các máy chủ cũ vẫn tiếp tục hoạt động. OpenCode là nơi bạn có thể thấy điều này: mỗi máy chủ có một giao thức cài đặt (legacy theo mặc định, auto, hoặc 2026-07-28), và chỉ bản sửa đổi mới nhất mới dùng được connection pooling.

Hoá đơn ngữ cảnh, và cách giữ nó nhỏ

Mỗi công cụ mà một máy chủ cung cấp đều đi kèm một mô tả viết cho mô hình. Theo cách nói của chính OpenCode, “Công cụ MCP tiêu tốn ngữ cảnh của mô hình, nên chỉ thêm những máy chủ bạn cần.” Hiện có hai tác nhân giảm nhẹ chi phí này theo mặc định:

  • Claude Code dùng tool search. Khi bắt đầu một phiên, nó chỉ tải tên các công cụ và hướng dẫn của từng máy chủ, rồi kéo toàn bộ định nghĩa của một công cụ khi Claude thực sự tìm đến nó.
  • OpenCode dùng Code Mode, cách này nhóm các công cụ của mỗi máy chủ vào một mục thay vì liệt kê từng công cụ riêng lẻ. Tính năng này bật trừ khi bạn đặt "codemode": false cho một máy chủ.

Ở mọi nơi khác, và bên trên các mặc định đó, đây là những gì bạn kiểm soát:

Agent Tắt một máy chủ Ẩn những công cụ bạn không muốn
OpenCode "disabled": true, hoặc /mcps cho một phiên A deny quy tắc trên <server>_<tool> trong mục quyền
Claude Code claude mcp remove <name> (/mcp hiển thị trạng thái) A deny quy tắc quyền trên mcp__<server>__<tool>; ENABLE_TOOL_SEARCH quyết định lượng tải trước
Codex enabled = false enabled_tools và disabled_tools
Gemini CLI gemini mcp disable <name> (thêm --session cho một phiên) includeTools và excludeTools
Cursor Công tắc của máy chủ trong mục Customize (Tuỳ chỉnh) (Quản trị viên có thể đặt danh sách công cụ được phép)
Hermes Agent enabled: false tools.include và tools.exclude

Quy tắc của tôi: hai đến năm máy chủ bạn dùng hằng tuần tốt hơn hai mươi cái bạn có thể dùng một ngày nào đó. Hãy xoá phần còn lại; bạn có thể thêm lại trong một phút.

Bốn máy chủ nên thử trước

Máy chủ Nó mang lại gì cho tác nhân của bạn Loại Địa chỉ hoặc lệnh Đăng nhập
Context7 Tài liệu hiện hành, theo đúng phiên bản, cho các thư viện và framework phổ biến Từ xa https://mcp.context7.com/mcp Không cần gì; một API key miễn phí sẽ nâng giới hạn
GitHub (chính thức) Issues, pull request, tìm kiếm mã, Actions Từ xa https://api.githubcopilot.com/mcp/ OAuth ở nơi tác nhân của bạn hỗ trợ, hoặc một personal access token
Playwright Một trình duyệt thật mà tác nhân có thể mở, bấm qua và chụp màn hình Cục bộ npx @playwright/mcp@latest Không có
Sentry Lỗi và sự cố thật của bạn Từ xa https://mcp.sentry.dev/mcp OAuth

Tìm thêm ở đâu:

  • Kho chính thức MCP Registry, do những người đóng góp cho giao thức duy trì, liệt kê các máy chủ đã được công bố.
  • Tài liệu của chính các công cụ bạn dùng. Hầu hết dịch vụ nay đều công bố một máy chủ chính thức; hãy tìm “MCP” trong tài liệu của họ.
  • Danh mục của tác nhân bạn dùng. Hermes Agent có hermes mcp catalog, và nhiều plugin Claude Code mang theo máy chủ riêng.

Hãy ưu tiên những máy chủ do chính công ty vận hành dịch vụ công bố. Một máy chủ vô danh mang tên “github-mcp-pro” đáng bị nghi ngờ y như một tiện ích trình duyệt vô danh.

Lựa chọn nhẹ hơn: một công cụ dòng lệnh cộng với một skill

Trước khi thêm một máy chủ, hãy xem liệu một công cụ dòng lệnh có làm được việc đó không. Bản thân Context7 cung cấp cả hai cách: máy chủ MCP ở trên, hoặc một CLI nhỏ kèm skill (npx ctx7 setup --opencode, cái này cần Node.js 22.13 trở lên). Công cụ gh của chính GitHub cộng với một skill ngắn đã đáp ứng phần lớn những gì máy chủ của nó làm được.

Máy chủ là hợp lý khi tác nhân của bạn không chạy được lệnh (ví dụ một ứng dụng chat trên máy tính), dịch vụ không có CLI tốt, hoặc công việc mang tính tương tác, như điều khiển trình duyệt. CLI cộng với một skill là hợp lý khi công cụ đã tồn tại: nó không tốn gì cho đến khi được dùng, và đầu ra của nó có thể được cắt bớt trước khi đến mô hình. Bài Hướng dẫn OpenCode của tôi lập luận tương tự cho việc phát triển ứng dụng.


Phần 8 — Thêm máy chủ MCP trong sáu tác nhân: công thức sao chép và dán

Mỗi công thức đều thêm cùng hai máy chủ: Context7 (từ xa) và Playwright (cục bộ). Thay bằng bất kỳ máy chủ nào khác theo cùng cách đó. Khi một tác nhân vừa có lệnh vừa có tệp cài đặt, lệnh đó chỉ đơn giản ghi tệp cho bạn.

OpenCode

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add playwright -- npx @playwright/mcp@latest
opencode mcp list

Thêm --global để làm cho một máy chủ có mặt trong mọi dự án. Trong opencode.jsonc phần thiết lập tương tự trông như sau:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false
        // With a free API key, add:
        // "headers": { "Authorization": "Bearer {env:CONTEXT7_API_KEY}" }
      },
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp@latest"]
      }
    }
  }
}
  • Thông tin bí mật được nhập dưới dạng {env:NAME}; OpenCode không tự mở rộng một $NAME.
  • Máy chủ từ xa tự động thử OAuth; oauth: false dành cho các máy chủ dùng khóa hoặc không dùng khóa. Đăng nhập bằng opencode mcp auth <name>, và qua SSH, hãy dán URL callback từ trang trình duyệt bị lỗi vào prompt.
  • Trong một phiên, /mcps kết nối, ngắt kết nối hoặc đăng nhập vào máy chủ.
  • Mỗi công cụ trở thành một hành động quyền có tên <server>_<tool>, nên { "action": "playwright_*", "resource": "*", "effect": "ask" } khiến mọi thao tác trình duyệt phải hỏi trước.

Claude Code

claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list

Việc -- ngăn cách các tùy chọn của Claude Code với lệnh riêng của máy chủ. Máy chủ mặc định ở phạm vi cục bộ (bạn, trong dự án này). Thêm --scope user cho tất cả dự án của bạn, hoặc --scope project để ghi một .mcp.json tệp bạn có thể commit cho nhóm của mình:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • .mcp.json mở rộng ${VAR} và ${VAR:-default}, để khóa nằm trong môi trường của bạn, không nằm trong Git.
  • /mcp bên trong một phiên sẽ hiển thị trạng thái của từng máy chủ và xử lý đăng nhập OAuth.
  • Claude Code hỏi trước khi dùng máy chủ từ .mcp.json, để một kho lưu trữ được clone không thể lặng lẽ thêm máy chủ của riêng nó.

Codex

Codex lưu máy chủ trong ~/.codex/config.toml, hoặc trong .codex/config.toml bên trong một dự án bạn đã đánh dấu là tin cậy:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
  • Máy chủ từ xa cũng có thể được thêm bằng codex mcp add context7 --url https://mcp.context7.com/mcp, và codex mcp login <name> chạy đăng nhập OAuth.
  • Với khóa, bearer_token_env_var = "CONTEXT7_API_KEY" đọc nó từ môi trường của bạn.
  • Điều chỉnh một máy chủ bằng enabled_tools và disabled_tools; startup_timeout_sec (mặc định 10 giây) giúp các máy chủ chậm khởi động.

Gemini CLI

gemini mcp add -t http context7 https://mcp.context7.com/mcp
gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list

gemini mcp add ghi vào cài đặt của dự án theo mặc định; thêm -s user cho mọi dự án. Trong settings.json:

{
  "mcpServers": {
    "context7": { "httpUrl": "https://mcp.context7.com/mcp" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
  }
}
  • httpUrl dành cho Streamable HTTP; url nghĩa là kiểu SSE cũ hơn.
  • Để trust ở chế độ tắt. Đặt thành true, nó bỏ qua mọi bước xác nhận cho máy chủ đó.
  • Gemini CLI loại bỏ những biến trông giống bí mật (tên chứa TOKEN, SECRET, PASSWORD hoặc KEY) khỏi môi trường của máy chủ trừ khi bạn liệt kê chúng trong khối env của nó.
  • OAuth cần trình duyệt trên cùng một máy. Trong thư mục chưa được tin cậy, các máy chủ cục bộ vẫn bị ngắt kết nối cho đến khi bạn chạy gemini trust.

Cursor

Cursor đọc .cursor/mcp.json trong một dự án và ~/.cursor/mcp.json cho mọi thứ:

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • Máy chủ cục bộ cần "type": "stdio".
  • Thông tin bí mật được nhập dưới dạng ${env:NAME}.
  • Bật và tắt máy chủ bằng công tắc của chúng trong Tùy chỉnh.

Hermes Agent

Hermes đọc mcp_servers trong ~/.hermes/config.yaml:

mcp_servers:
  context7:
    url: "https://mcp.context7.com/mcp"
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
  • Chạy /reload-mcp sau khi chỉnh sửa, và hermes mcp test context7 để xem chính xác máy chủ đã trả lời gì.
  • Với các dịch vụ OAuth, thêm auth: oauth vào một mục HTTP. Trên máy không có màn hình, Hermes cung cấp cách dán lại, chuyển tiếp cổng SSH hoặc luồng đăng nhập bằng thiết bị.
  • Hermes chỉ truyền cho máy chủ cục bộ những biến bạn liệt kê trong env cùng một mức cơ sở an toàn, chứ không phải toàn bộ môi trường shell của bạn.
  • Các công cụ xuất hiện dưới dạng mcp_<server>_<tool>; lọc chúng bằng tools.include hoặc tools.exclude.

Kiểm tra nó hoạt động, trong bất kỳ tác nhân nào

Hỏi một câu mà chỉ máy chủ đó trả lời được: “Dùng Context7 để tra cách định nghĩa một route trong phiên bản hiện tại của Next.js, và cho tôi biết bạn đã gọi công cụ nào.” Sau đó yêu cầu một thứ nhìn thấy được: “Mở example.com bằng Playwright và mô tả trang đó.” Nếu tác nhân nói nó không có công cụ như vậy, hãy liệt kê các máy chủ (opencode mcp list, claude mcp list, gemini mcp list, hermes mcp test) và tìm một kết nối thất bại hoặc một lần đăng nhập không bao giờ hoàn tất.

Cách thêm máy chủ MCP trong OpenCode, Claude Code, Codex, Gemini CLI, Cursor và Hermes Agent: cùng một máy chủ Context7 theo định dạng lệnh hoặc cấu hình của từng tác nhân, kèm lệnh cho máy chủ cục bộ
Một máy chủ, sáu phương ngữ. Ý tưởng giống hệt nhau; chỉ tên tệp và dấu ngoặc là thay đổi.

Phần 9 — Plugin: kỹ năng và máy chủ MCP trong một gói

Cài mười skill và ba máy chủ từng cái một thì rất mất công. Plugin gói chúng lại, và hầu hết tác nhân giờ đều có hệ thống plugin theo cách nào đó.

Plugin của Claude Code

Một plugin Claude Code có thể chứa skill, tác nhân phụ, hook, máy chủ MCP và máy chủ ngôn ngữ. Plugin đến từ chợ plugin, đơn giản là các danh mục được lưu trong một kho Git:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Trong một phiên, /plugin install trước tiên mở phần chi tiết của plugin để bạn thấy chính xác nó thêm gì trước khi chọn phạm vi: bạn (mọi dự án), kho lưu trữ này cho mọi người, hoặc kho lưu trữ này chỉ cho bạn. Từ shell của bạn, claude plugin install <name>@<marketplace> làm điều tương tự mà không cần một phiên.

Ba tính năng đáng biết:

  • Chi phí ngữ cảnh được hiển thị. Với các plugin trong chợ chính thức của Anthropic, khung chi tiết ước tính plugin thêm gì vào mỗi tin nhắn và thêm gì khi được dùng. claude plugin details <name> hiển thị con số cho mỗi phiên với bất cứ thứ gì đã cài.
  • Cập nhật. Chợ chính thức của Anthropic tự động cập nhật plugin; chợ của bên thứ ba thì không, trừ khi bạn bật tính năng đó. claude plugin update <name>@<marketplace> cập nhật thủ công một plugin.
  • Plugin không dùng được đánh dấu. Tab Installed nhóm các plugin bạn chưa dùng gần đây, giúp việc dọn dẹp trở nên dễ dàng.

Plugin ở nơi khác

  • Codex phân phối các skill tái sử dụng qua plugin (/plugins trong CLI), và một plugin cũng có thể mang theo các kết nối máy chủ MCP.
  • Gemini CLI gọi chúng là tiện ích mở rộng: gemini extensions install <git-url> và gemini extensions update <name>.
  • GitHub Copilot CLI (copilot plugin install) và Hermes Agent (hermes plugins install) có lệnh plugin, và Cursor có /add-plugin trong Agent chat.
  • OpenCode plugin là các gói JavaScript hoặc TypeScript được liệt kê trong plugin mục cài đặt trong tệp cấu hình của nó, có thể đăng ký skill và tool. Superpowers cài đặt theo cách này.

Hai quy tắc giúp thiết lập plugin luôn gọn gàng

  1. Mỗi gói một kênh. Nếu một gói skill tồn tại cả dưới dạng plugin lẫn dạng skill thường, hãy chọn một. Hai bản sao nghĩa là trùng tên và tác nhân sẽ chọn bản mà nó thấy trước.
  2. Cập nhật ở nơi bạn đã cài. skills CLI không biết gì về plugin, và trình quản lý plugin cũng không biết gì về ~/.agents/skills.

Phần 10 — Viết kỹ năng đầu tiên trong mười phút

Skill đầu tiên tốt nhất là skill giải quyết một việc bạn làm đi làm lại. Đây là một skill dựng từ Phần 6: một skill cho phép bất kỳ tác nhân nào kiểm tra cập nhật cho skill của bạn một cách an toàn, mà không bao giờ dùng sudo hay tin mù vào dấu tick xanh.

Bước 1 — Tạo thư mục

mkdir -p ~/skills-drafts && cd ~/skills-drafts
npx skills init skills-housekeeping

Lệnh đó tạo ra skills-housekeeping/SKILL.md từ một mẫu. Thay nội dung của nó bằng đoạn này:

---
name: skills-housekeeping
description: Kiểm tra các skill tác nhân đã cài để tìm bản cập nhật và trục trặc với skills CLI npx, rồi giải thích kết quả bằng tiếng Anh dễ hiểu. Dùng khi được hỏi liệu skill đã mới nhất chưa, để cập nhật skill, hoặc khi một skill đã cài có vẻ bị thiếu.
metadata:
  author: graham-miranda
  version: "1.0"
---

# Skills housekeeping

## Quy tắc
- Không bao giờ chạy bất kỳ lệnh nào với sudo.
- Không bao giờ chạy `npx skills update` hoặc `npx skills remove` mà không hỏi trước.
- Chạy lệnh từ /tmp hoặc một thư mục dự án, không bao giờ từ thư mục home.

## Kiểm tra
1. Chạy `cd /tmp && npx skills@latest check -g` cho skill toàn cục.
2. Nếu dự án hiện tại có tệp skills-lock.json, chạy thêm `npx skills@latest check -p` trong thư mục dự án.
3. Coi mọi dòng bắt đầu bằng ✗ là "chưa kiểm tra", kể cả khi một dòng phía sau nói mọi thứ đã mới nhất.

## Báo cáo
- Liệt kê skill có cập nhật, skill có thay đổi cục bộ, và mọi thứ không thể kiểm tra.
- Nếu bất kỳ bước kiểm tra nào thất bại, gợi ý `gh auth login`, hoặc một GITHUB_TOKEN chỉ có quyền đọc các kho công khai.
- Hỏi trước khi cập nhật. Sau đó chạy `npx skills update -g` (hoặc `-p`) và báo cáo những gì đã thay đổi.

Bước 2 — Đối chiếu với tiêu chuẩn

  • Tên: skills-housekeeping chỉ dùng chữ thường và dấu gạch nối, dưới 64 ký tự, và khớp với tên thư mục. Cả ba điều đều bắt buộc.
  • Mô tả: nó nói gì skill làm gì và thời điểm khi nào dùng nó, và chứa những từ người ta thực sự gõ (“đã mới nhất”, “cập nhật skill”, “bị thiếu”). Phần mô tả là thứ duy nhất tác nhân thấy trước khi quyết định, nên nó gánh phần lớn công việc. Tiêu chuẩn cho phép tối đa 1.024 ký tự; hãy nhắm tới một hoặc hai câu.
  • Độ dài: thấp hơn nhiều so với mức 500 dòng được khuyến nghị. Khi một skill phình ra, hãy chuyển chi tiết sang references/ và trỏ tới nó từ phần hướng dẫn.

Dự án Agent Skills công bố một trình kiểm tra tham chiếu, skills-ref, công cụ này kiểm tra front matter và các quy tắc đặt tên: skills-ref validate ./skills-housekeeping.

Bước 3 — Cài cho mọi tác nhân cùng lúc

skills CLI cũng cài được từ một thư mục cục bộ:

npx skills add ./skills-housekeeping -g -a opencode -a claude-code -a codex

Như vậy bản sao thật nằm trong ~/.agents/skills/skills-housekeeping (được OpenCode và Codex đọc trực tiếp) và thêm một liên kết trong ~/.claude/skills cho Claude Code.

Bước 4 — Kiểm tra

Hỏi bằng lời đơn giản: “Các kỹ năng của tôi đã cập nhật chưa?” Một kỹ năng được mô tả tốt sẽ tự động được nhận ra. Nếu không, hãy gọi nó bằng tên để loại trừ vấn đề nạp: @skills-housekeeping trong OpenCode, /skills-housekeeping trong Claude Code, $skills-housekeeping trong Codex. Nếu nó nạp được khi gọi tên nhưng không bao giờ tự kích hoạt, vấn đề nằm ở phần mô tả: hãy thêm những cụm từ bạn thực sự dùng.

Bước 5 — Chia sẻ

Đẩy thư mục lên một kho GitHub, lý tưởng nhất là trong một skills/ thư mục (skills/skills-housekeeping/SKILL.md). Sau đó ai cũng có thể cài đặt bằng npx skills add your-name/your-repo. CLI tìm kỹ năng trong skills/ và trong các thư mục tác nhân phổ biến, sâu tối đa ba cấp.

Phần bổ sung riêng cho từng tác nhân, và khi nào nên tránh

Một số tác nhân hiểu thêm những trường front matter bổ sung. Claude Code có disable-model-invocation (chỉ bạn mới kích hoạt được kỹ năng) và context: fork (chạy nó trong một tác nhân con); Cursor có paths (chỉ với các tệp khớp); OpenCode có thể ẩn một kỹ năng khỏi mô hình bằng metadata đặt thành opencode/autoinvoke: false. Chúng hữu ích, nhưng thứ đi được khắp nơi là các trường chuẩn. Tài liệu của chính Claude Code ghi rằng ngoài Claude Code, trong các tệp tải lên claude.ai hay Skills API, chỉ các trường chuẩn được chấp nhận và bất cứ thứ gì khác đều là lỗi. Với những kỹ năng bạn chia sẻ, hãy dùng đặt tên, mô tả, license, compatibility, metadata và trường thử nghiệm allowed-tools.

Cấu trúc của một skill tác nhân: phần front matter của SKILL.md được đọc lúc khởi động, khoảng 100 token, hướng dẫn được đọc khi tác vụ phù hợp, còn tài liệu tham chiếu, script và tài nguyên chỉ được đọc khi cần
Ba lớp: nhãn, công thức và phụ lục. Chỉ lớp đầu tiên luôn được nạp, đó là lý do phần mô tả tốt quan trọng hơn những hướng dẫn dài.

Phần 11 — Giữ an toàn: kỹ năng và máy chủ đều là phần mềm

Dễ nghĩ rằng một kỹ năng chỉ là “một tệp Markdown”. Thật ra không phải. Đó là những hướng dẫn mà tác nhân của bạn sẽ làm theo với quyền của bạn, thường kèm các tập lệnh mà nó sẽ chạy trên máy bạn. Và một máy chủ MCP cục bộ là một chương trình chạy dưới danh nghĩa bạn.

Những con số của năm nay thật đáng lo. Nghiên cứu ToxicSkills của Snyk, công bố tháng 2 năm 2026, đã quét 3.984 kỹ năng tác nhân công khai: 36,82% có ít nhất một lỗ hổng bảo mật, 13,4% có lỗ hổng nghiêm trọng, và 76 kỹ năng chứa mã độc đã được xác nhận. Rắc rối tập trung ở ClawHub, chợ cộng đồng của OpenClaw, nơi một cuộc kiểm tra trước đó với 2.857 kỹ năng, cũng do Snyk báo cáo, đã tìm ra 341 kỹ năng độc hại, khoảng 12% registry vào thời điểm đó. Ngược lại, 100 kỹ năng phổ biến nhất trên skills.sh không kích hoạt bất kỳ kiểm tra prompt-injection hay mã độc nào của Snyk. Phổ biến không phải bằng chứng, nhưng nó có ích.

MCP có kiểu rủi ro riêng. Tài liệu của Claude Code cảnh báo rằng những máy chủ lấy nội dung từ bên ngoài có thể khiến bạn gặp phải prompt injection: một trang web, bình luận issue hay báo cáo sự cố chứa văn bản nhắm vào tác nhân của bạn thay vì nhắm vào bạn.

Mười thói quen giúp bạn an toàn

  1. Đọc trước khi cài đặt. Dùng npx skills add owner/repo --list, gh skill preview, hoặc chỉ cần mở SKILL.md và các script của nó trên GitHub.
  2. Ưu tiên nhà sản xuất và tác giả có tên tuổi. Skill của Expo dành cho Expo, của Vercel dành cho Next.js, máy chủ MCP chính thức của nhà cung cấp dành cho dịch vụ của chính họ.
  3. Kiểm tra kết quả audit. Mỗi skill trên skills.sh hiển thị kết quả từ ba trình quét: Gen Agent Trust Hub, Socket và Snyk. “Đang chờ” nghĩa là chưa ai xem xét.
  4. Ghim phiên bản cho những gì quan trọng. npx skills add owner/[email protected], hoặc gh skill install … --pin v1.2.3, để bản cập nhật chỉ đến khi bạn chọn.
  5. Xem bản cập nhật như xem code. npx skills check, sau đó đọc các thay đổi trên GitHub, rồi npx skills update.
  6. Kiểm soát skill của bên thứ ba. Trong OpenCode, các quy tắc dùng skill hành động và kết quả khớp cuối cùng sẽ thắng:

jsonc "permissions": [ { "action": "skill", "resource": "*", "effect": "ask" }, { "action": "skill", "resource": "skills-housekeeping", "effect": "allow" }, { "action": "playwright_*", "resource": "*", "effect": "ask" } ]

Hermes Agent quét mọi lần cài đặt từ hub, và --force không thể ghi đè kết luận “nguy hiểm”. Gemini CLI hỏi ý kiến bạn trước khi kích hoạt một skill. 7. Cấp cho máy chủ mức truy cập tối thiểu đủ dùng. Token chỉ đọc, phân quyền chi tiết; token riêng cho từng máy chủ; công cụ ghi và xóa để ở chế độ “hỏi” hoặc bị lọc bỏ. 8. Đừng để bí mật lọt vào skill hay tệp cấu hình được commit. Dùng biến môi trường ({env:NAME} trong OpenCode, ${VAR} trong tệp cấu hình của Claude Code .mcp.json, ${env:NAME} trong Cursor), tuyệt đối không dán khóa vào. 9. Cẩn thận với cấu hình dự án của người khác. Một kho lưu trữ được clone có thể mang theo .mcp.json hoặc skill của riêng nó. Claude Code hỏi trước khi dùng máy chủ của dự án, Gemini CLI giữ máy chủ cục bộ ở trạng thái ngắt kết nối trong thư mục không tin cậy, và Hermes Agent chỉ nạp skill của dự án sau khi hermes skills trust. Đừng bấm qua những lời nhắc đó trong lúc vô thức. 10. Gỡ cài đặt những gì bạn không dùng. Mỗi skill và máy chủ không dùng là bề mặt tấn công mà bạn vẫn phải trả giá bằng ngữ cảnh.

Danh sách kiểm tra bảo mật cho skill tác nhân và MCP: số liệu ToxicSkills của Snyk về 3.984 skill công khai và mười thói quen an toàn, từ đọc trước khi cài và ghim phiên bản đến token đặc quyền tối thiểu
Một skill là những chỉ dẫn mà tác nhân của bạn thực hiện với quyền của bạn. Hãy cài đặt nó với sự cẩn trọng như với bất kỳ phần mềm nào khác.

Phần 12 — Thói quen hai phút mỗi tuần

Skill và máy chủ dần lệch khỏi bản gốc. Một quy trình nhỏ giúp chúng luôn đúng:

# Skill toàn cục, chạy từ một thư mục trung lập
cd /tmp && npx skills@latest check -g

# Từng dự án bạn đang làm việc
cd ~/code/my-app && npx skills@latest check -p

# Sau khi đọc những gì đã thay đổi ở nguồn:
npx skills update -g

Mỗi tháng một lần, dành thêm năm phút:

  • Dọn bớt. npx skills ls -g và gỡ những gì bạn chưa dùng. Trong Claude Code, bảng plugin liệt kê những plugin bạn chưa dùng gần đây.
  • Liệt kê các máy chủ của bạn. opencode mcp list, claude mcp list, gemini mcp list hoặc hermes mcp test cho từng mục. Xóa những gì bạn quên thêm vào.
  • Xoay vòng token mà bạn đã cấp cho các máy chủ, nhất là những máy chủ có quyền ghi.

Hai máy, một bộ thiết lập

Tôi chạy tác nhân trên một chiếc Mac và trên một chiếc Raspberry Pi, và ba thói quen giữ chúng đồng bộ:

  1. Cùng một cách trên cả hai: người dùng bình thường của bạn, không bao giờ sudo, và CLI chạy từ thư mục dự án hoặc /tmp.
  2. Skill của dự án đi theo Git. Commit .agents/skills và skills-lock.json; trên máy kia, npx skills install khôi phục lại đúng những phiên bản như vậy.
  3. Skill toàn cục đến từ một script. Giữ npx skills add … -g các lệnh trong một tệp shell nhỏ rồi chạy nó trên từng máy. Nó cũng là tài liệu ghi lại những gì bạn dựa vào.

Trên máy headless như Pi, hãy đặt GITHUB_TOKEN trong ~/.bashrc để các lần kiểm tra cập nhật không chạm giới hạn ẩn danh. Đăng nhập qua trình duyệt cần cẩn thận: OpenCode cho bạn dán URL callback vào prompt, Hermes Agent có dán lại, chuyển tiếp cổng SSH hoặc device flow, còn luồng OAuth của Gemini CLI cần trình duyệt trên cùng máy.


Phần 13 — Nên chọn thiết lập nào? Năm tình huống

1. “Tôi mới bắt đầu với OpenCode.”

Cài đặt tối đa ba skill và một máy chủ MCP. Context7 là máy chủ đầu tiên đáng thử, và một skill phát hành hoặc review khớp với cách bạn làm việc là skill đầu tiên tốt. Hãy để skill của bên thứ ba ở hỏi trong phần quyền của OpenCode cho đến khi bạn tin chúng. Bài Hướng dẫn OpenCode bao gồm phần còn lại của việc thiết lập.

2. “Tôi dùng OpenCode và Claude Code song song, có thể cả Hermes Agent nữa.”

Cài skill ở phạm vi toàn cục bằng CLI và nêu tên từng tác nhân: npx skills add owner/repo -g -a opencode -a claude-code -a hermes-agent. Một bản sao, ba tác nhân. Các máy chủ MCP không dùng chung một tệp cấu hình, nên hãy thêm từng cái vào từng tác nhân và giữ danh sách ở nơi bạn dễ tìm. Bài so sánh giữa OpenCode, Hermes Agent và OpenClaw giải thích mỗi tác nhân mạnh ở đâu, và bài so sánh harness coding AI so sánh song song 28 tác nhân trong số đó.

3. “Nhóm tôi dùng chung một kho lưu trữ.”

Dùng phạm vi dự án: commit .agents/skills, skills-lock.json, và phần cài đặt MCP (opencode.jsonc, .mcp.json hoặc .cursor/mcp.json) không chứa bí mật nào trong đó. Mỗi người giữ khóa trong môi trường của riêng mình. Trong CI, npx skills install --frozen-lockfile sẽ báo lỗi nếu skill của ai đó bị lệch, và npx skills check -p báo lỗi khi có bản cập nhật đang chờ.

4. “Tác nhân của tôi chạy trên Raspberry Pi hoặc một máy chủ.”

Một người dùng bình thường, không sudo, không bao giờ. Đặt GITHUB_TOKEN, hãy ưu tiên máy chủ từ xa chấp nhận token trong header (hoặc có đăng nhập bằng thiết bị), và chạy kiểm tra hàng tuần từ /tmp. Phần 6 là danh sách kiểm tra của bạn.

5. “Mã của tôi không được rời khỏi máy tôi.”

Dùng chỉ dùng máy chủ MCP cục bộ, và bỏ qua các máy chủ tài liệu từ xa và tìm kiếm mã. Tắt telemetry của CLI (DISABLE_TELEMETRY=1), hãy đọc mọi skill bạn cài, và nhớ rằng bản thân mô hình vẫn có thể là mô hình đám mây: quyền riêng tư phụ thuộc vào nơi mô hình mô hình chạy nữa. Bài hướng dẫn chạy LLM trên MacBook sẽ nói rõ lộ trình hoàn toàn cục bộ thực sự tốn kém những gì.


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

Agent skills là gì?

Agent skill là các thư mục dạy tác nhân AI cách làm một việc cụ thể. Mỗi thư mục chứa một SKILL.md tệp có tên, mô tả và hướng dẫn từng bước, cùng các script và tệp tham chiếu tùy chọn. Tác nhân chỉ đọc phần mô tả khi bắt đầu một phiên, và tải toàn bộ hướng dẫn của skill khi tác vụ khớp. Skill theo một chuẩn mở, nên hầu hết đều hoạt động như nhau trong OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot và Hermes Agent.

MCP server là gì?

Máy chủ MCP là một chương trình nhỏ cung cấp cho tác nhân AI các công cụ mới thông qua Model Context Protocol, một chuẩn mở hiện do Agentic AI Foundation của Linux Foundation quản lý. Máy chủ cục bộ chạy trên máy tính của bạn và do tác nhân khởi chạy; máy chủ từ xa chạy trên máy của nhà cung cấp và được truy cập qua một địa chỉ web, thường kèm đăng nhập bằng trình duyệt. Ví dụ gồm máy chủ chính thức của GitHub, Context7 cho tài liệu cập nhật và Playwright để điều khiển trình duyệt.

Sự khác nhau giữa agent skill và máy chủ MCP là gì?

Skill cho tác nhân biết cách làm: hướng dẫn bằng văn bản về cách hoàn thành một việc, chỉ được tải khi cần. Máy chủ MCP cho tác nhân khả năng: các công cụ tiếp cận hệ thống bên ngoài terminal, như GitHub, trình duyệt hay hệ thống theo dõi lỗi. Dùng skill cho quy trình và quy ước, máy chủ MCP cho truy cập trực tiếp vào một hệ thống, và AGENTS.md cho các quy tắc áp dụng cho mọi tác vụ. Nếu đã có một công cụ dòng lệnh tốt, một skill dạy tác nhân dùng công cụ đó thường rẻ hơn một máy chủ.

Skills có hoạt động giống nhau trong OpenCode, Claude Code và Codex không?

Phần lớn là vậy, vì cả ba đều theo chuẩn Agent Skills. Khác biệt là ở chỗ chúng tìm kiếm. Codex và OpenCode đọc thư mục .agents/skills và ~/.agents/skills dùng chung; OpenCode cũng đọc .opencode/skills và các thư mục của Claude Code. Claude Code chỉ đọc .claude/skills và ~/.claude/skills. Một số trường front matter bổ sung, như context: fork, chỉ hoạt động trong một tác nhân, nên skill dùng chung chỉ nên dùng các trường chuẩn.

Làm sao để cài một skill bằng npx skills?

Chạy npx skills add owner/repo --list để xem các skill mà một kho lưu trữ cung cấp, rồi npx skills add owner/repo --skill skill-name -a opencode -a claude-code để cài một skill cho các tác nhân bạn dùng. Thêm -g để dùng nó trong mọi dự án. Bạn cần Node.js 22.20 trở lên. Nếu không có cờ, CLI sẽ hỏi bạn muốn skill nào, tác nhân nào và muốn liên kết hay sao chép các tệp.

npx skills cài skill vào đâu?

Cài đặt theo dự án đặt bản sao thật trong .agents/skills/<name> bên trong dự án của bạn và ghi lại vào skills-lock.json. Cài đặt toàn cục (-g) đặt nó trong ~/.agents/skills/<name> và ghi lại vào ~/.agents/.skill-lock.json. Các tác nhân đọc .agents/skills sẽ dùng trực tiếp bản sao đó; với các tác nhân có thư mục riêng, như Claude Code (.claude/skills) hoặc Hermes Agent (~/.hermes/skills), CLI tạo một liên kết tới đó.

Làm sao biết skill của tôi đã mới nhất chưa?

Chạy npx skills@latest check -g cho skill toàn cục, hoặc npx skills@latest check -p bên trong một dự án. CLI so sánh dấu vân tay của từng thư mục skill trong tệp lock của bạn với chính thư mục đó ở nguồn gốc, rồi liệt kê mọi skill có bản cập nhật mà không cài gì cả. Từ phiên bản 1.7.5 (2 tháng 11 năm 2026), check chỉ báo cáo; npx skills update sẽ cài đặt. Hãy chạy nó từ một thư mục dự án hoặc /tmp, chứ không phải thư mục home của bạn.

Tại sao npx skills báo mọi skill đều mới nhất khi bước kiểm tra thất bại?

Vì phần tóm tắt chỉ đếm những bản cập nhật mà nó tìm thấy. Nếu giới hạn 60 yêu cầu API ẩn danh mỗi giờ của GitHub chặn mọi lần tra cứu, CLI vẫn in một dòng ✗ cho mỗi nguồn và vẫn có thể kết thúc bằng “Tất cả skill toàn cục đều đã cập nhật”. Đăng nhập bằng gh auth login hoặc đặt một GITHUB_TOKEN để nâng giới hạn lên 5.000 yêu cầu một giờ, hãy nâng cấp bằng npx skills@latest, và luôn đọc các dòng ✗.

Có nên dùng sudo với npx skills không?

Không. Skill được lưu theo từng người dùng, và root có thư mục home riêng, nên sudo cài skill vào /root/.agents/skills, nơi các tác nhân chạy dưới người dùng thường của bạn không bao giờ thấy chúng. Nó cũng có thể để lại các tệp thuộc sở hữu root trong thư mục của bạn và gây lỗi npm như “prefix cannot be changed from project config”. Hãy chạy CLI và các tác nhân của bạn dưới người dùng thường.

Làm sao để thêm một MCP server vào OpenCode?

Chạy opencode mcp add <name> --url <address> cho một máy chủ từ xa, hoặc opencode mcp add <name> -- <command> cho một máy chủ cục bộ, rồi kiểm tra bằng opencode mcp list. Thêm --global để dùng nó trong mọi dự án. Các cài đặt tương tự có thể nằm trong mcp.servers trong opencode.jsonc, với các bí mật được ghi dưới dạng {env:NAME}. Dùng opencode mcp auth <name> để đăng nhập, và /mcps trong một phiên để kết nối hoặc ngắt kết nối các máy chủ.

Nên cài bao nhiêu MCP server?

Chỉ dùng ít như bạn thực sự cần, thường là hai đến năm. Công cụ của mỗi máy chủ đi kèm mô tả mà mô hình phải đọc, việc này tốn ngữ cảnh và có thể làm câu trả lời chậm hơn, kém tập trung hơn. Claude Code hoãn các định nghĩa công cụ đến khi cần và OpenCode nhóm chúng theo máy chủ, điều đó giúp ích, nhưng những máy chủ không dùng vẫn thêm rủi ro và lộn xộn. Hãy gỡ bỏ bất cứ thứ gì bạn chưa dùng trong một tháng.

Cài agent skills có an toàn không?

Chỉ an toàn bằng nguồn gốc của chúng. Một skill là tập chỉ dẫn mà tác nhân của bạn thực hiện với quyền của bạn, thường kèm các script nó chạy. Nghiên cứu tháng 2 năm 2026 của Snyk trên 3.984 skill công khai phát hiện lỗ hổng bảo mật ở 36,82% và xác nhận payload độc hại ở 76 skill. Hãy đọc một skill và các script của nó trước khi cài đặt, ưu tiên skill từ chính nhà sản xuất công cụ, xem kết quả kiểm tra trên skills.sh, ghim phiên bản, và để skill của bên thứ ba ở chế độ “ask” trong phần quyền của tác nhân.

skills-lock.json là gì?

Đó là tệp lock của dự án mà CLI skills ghi khi bạn cài skill vào một dự án. Nó ghi lại từng skill đến từ đâu và dấu vân tay của các tệp. Hãy commit nó vào Git: trên một máy tính khác, npx skills install khôi phục đúng những skill đó, và --frozen-lockfile sẽ thất bại nếu có bất kỳ khác biệt nào. Skill toàn cục có tệp lock riêng tại ~/.agents/.skill-lock.json, mỗi tài khoản người dùng một tệp.

skills.sh là gì?

skills.sh là thư mục công khai các skill tác nhân của Vercel. Nó xếp hạng skill theo số lượt cài, nhóm theo chủ đề và hiển thị kết quả kiểm tra bảo mật từ Gen Agent Trust Hub, Socket và Snyk cho từng skill. Bạn cài skill từ đó bằng npx skills add owner/repo lệnh mà nó hiển thị. Cũng CLI đó, lệnh npx skills find sẽ tìm kiếm thư mục ngay từ terminal của bạn.

Điểm mấu chốt

Agent skills và MCP server trả lời hai câu hỏi khác nhau. Skill trả lời “chúng ta làm việc này ở đây thế nào?”: chúng là những thẻ công thức rẻ, dễ mang theo, chỉ tải khi cần. Máy chủ MCP trả lời “bạn có chạm được tới hệ thống đó không?”: chúng là những chìa khóa mạnh tốn ngữ cảnh và đáng được chăm sóc như bất kỳ phần mềm nào bạn cài. AGENTS.md giữ vài quy tắc áp dụng cho mọi thứ, còn phần quyền thực thi những gì không bao giờ được xảy ra.

Nếu bạn chỉ nhớ năm điều từ hướng dẫn này, hãy nhớ những điều sau:

  1. Đặt các skill dùng chung trong .agents/skills và để npx skills liên kết chúng vào những tác nhân tìm ở nơi khác.
  2. Chạy npx skills@latest check từ thư mục dự án hoặc /tmp, hãy đọc các dòng ✗, và cập nhật một cách có chủ đích.
  3. Đăng nhập GitHub (gh auth login) trên mọi máy có kiểm tra cập nhật.
  4. Đừng bao giờ dùng sudo với skill hay tác nhân.
  5. Bắt đầu với ba skill và một máy chủ, và chỉ thêm khi một tác vụ thực tế cần đến chúng.

Skill và máy chủ biến một chuyên gia tổng quát thông minh thành đồng nghiệp hiểu cách bạn làm việc và có thể chạm tới các công cụ của bạn. Bí quyết là đưa cho nó đúng thứ nó cần, và không thừa thứ nó không cần.


Bạn dùng skill hoặc máy chủ MCP nào mà tôi chưa nhắc tới? Tôi muốn nghe xem những cái nào đã có chỗ đứng lâu dài trong thiết lập của bạn, và những thông báo lỗi nào khiến bạn phải lùng sục. Rất hoan nghênh các chỉnh sửa: bài viết này được cập nhật khi công cụ thay đổi, mà nhìn vào năm nay thì sẽ thay đổi thường xuyên.

Tiết lộ: Không công ty nào được nhắc trong bài này tài trợ, xem xét hay phê duyệt bài viết, và bài không chứa liên kết tiếp thị nào. Sản phẩm chỉ được nêu tên trong văn bản; các hình ảnh dùng logo của chính tôi.

Cập nhật lần cuối: 15 tháng 11, 2026.

Thêm tín hiệu của bạn.

Địa chỉ email của bạn sẽ không được công khai. Các trường bắt buộc được đánh dấu *

viTiếng Việt