Runtime không tìm thấy Skill hoặc Agent

Dùng trang này khi cài Kit thành công nhưng runtime không liệt kê hoặc nhận diện Skill hay Agent mong đợi.

Khớp runtime session với bản cài

Xác nhận bốn thông tin từ output cài đặt ban đầu:

1. Tên Kit.
2. Runtime đích: claude-code, codex, cursor, dsh, grok, pi hoặc omp.
3. Scope: project hiện tại hoặc --global.
4. Các Skill đã chọn, gồm mọi filter --skills hoặc --exclude-skills.

Project install được discover từ project đó. Global install được discover từ user profile của runtime. Mở session runtime mới sau khi cài để nó tải inventory hiện tại, rồi dùng bề mặt discovery mà runtime đó hỗ trợ.

Ví dụ, gọi Skill tên ak:cook bằng cú pháp riêng của từng runtime:

/ak:cook Check this project   # Claude Code
$ak:cook Check this project   # Codex

Agent dùng bề mặt khác. Claude Code dispatch subagent đã cài; Codex tải Agent được định nghĩa bằng TOML và cung cấp runtime tool agent_<slug> tương ứng. Không có cú pháp gọi / hoặc $ không có nghĩa là Agent bị thiếu.

Với Pi, bản cài project được discover qua Skill portable dưới .pi/skills/, Agent dưới .pi/agents/, rule dưới .pi/rules/ và extension dưới .pi/extensions/. Bản cài global ghi trực tiếp dưới profile PI_CODING_AGENT_DIR hoặc ~/.pi/agent đang hoạt động; đừng tìm thêm đoạn .pi/ dưới profile đó. Pi không có tuyến ak run --target pi trong bản phát hành này.

Với Oh My Pi, hãy phân biệt discovery của bản cài với dispatch trực tiếp. Bản cài project cho runtime discover Skill portable dưới .omp/skills/ak-<slug>/, với name: ak-<slug> ở top-level trong mỗi SKILL.md đã projection, cùng Agent và rule dưới .omp/. Alias trong body như /ak:cook và $ak:cook được giữ nguyên. ak run <kit>/<skill> --target omp resolve rồi dispatch riêng một Skill mà không thay đổi selector đó. Oh My Pi sở hữu backend và credential đã cấu hình, vì vậy chỉ có file chưa chứng minh runtime đã tải nội dung.

Với DeepSeek Harness, bản cài project ghi Skill dưới .dsh/skills/, còn bản cài user ghi dưới ${DSH_HOME:-~/.dsh}/skills/. Setup resolve AGENTKIT_DSH_BIN hoặc dsh và để model, xác thực cùng sandbox cho runtime sở hữu. ak run <kit>/<skill> --target dsh resolve rồi dispatch riêng một Skill mà không thay đổi inventory đã cài.

Kiểm tra destination khớp delivery đã chọn:

Với bản cài OMP global, phân giải root theo cùng thứ tự như AgentKit: AGENTKIT_OMP_HOME, OMP_HOME, PI_CODING_AGENT_DIR, rồi ~/.omp/agent. Kiểm tra skills/<name>/SKILL.md, agents/<name>.md, rules/<name>.md và block AGENTKIT-OMP theo Kit trong AGENTS.md. Export không được hỗ trợ dưới .agentkit/adapters/omp/<kit>/sidecars/ được giữ để quan sát lifecycle; sự tồn tại của chúng không biến chúng thành bề mặt OMP đang hoạt động.

OMP trong project đã trust cũng discover .agents/skills của project. Nếu các dạng canonical như ak:advise và ak-advise xung đột, .omp/skills của project che bản .agents/skills với bản cài OMP project. Khi dùng bản cài OMP global từ project đó, .agents/skills của project che bản trong profile. Cảnh báo cài đặt không bỏ qua emission OMP, xóa hoặc viết lại Skill, thay đổi .agents hay setting OMP, yêu cầu --force hoặc báo exit 6.

Kiểm tra adapter, không chỉ sự tồn tại của tệp

ak doctor --json
ak doctor --adapter claude-code --json
ak doctor --adapter codex --json
ak doctor --adapter cursor --json

Chạy lệnh cho target đã cài. Tệp tồn tại không chứng minh registration hoặc cấu hình runtime hợp lệ. Kiểm tra các adapter check và data.healthy; doctor mặc định vẫn thoát 0 khi báo cáo không khỏe. Trên Codex, dùng doctor như tín hiệu về sức khỏe adapter, không phải bằng chứng duy nhất cho Skill inventory đã cài; hãy xác minh discovery ngay trong runtime.

Bản phát hành này chưa có nhóm check doctor với prefix pi_ hoặc omp_. Với Pi, hãy xác minh đúng path .pi/ trong project hoặc path dưới profile global ở trên rồi mở session Pi mới; đừng xem output doctor chung là bằng chứng Pi đã tải projection.

Bản phát hành này chưa có nhóm check doctor với prefix omp_. Với OMP, chạy ak doctor --json không filter để kiểm tra sức khỏe AgentKit dùng chung, đọc data.healthy, sau đó xác minh đúng path project hoặc global ở trên và mở một session OMP mới. Không xem kết quả rỗng từ ak doctor --adapter omp là bằng chứng projection OMP khỏe mạnh.

Hãy đọc codex_install_provenance như phân loại toàn bộ home, không phải check inventory Kit. ${CODEX_HOME:-~/.codex} là root dùng chung do người dùng sở hữu, vì vậy dòng này khỏe khi root chứa nội dung người dùng và không yêu cầu marker AgentKit cho toàn bộ home. Marker cũ không phải bằng chứng ownership hiện tại, còn thiếu marker không phải lý do để init, thay thế hoặc xóa Codex home. Manifest cùng ownership record theo Kit mới quản lý nội dung AgentKit.

Với bản cài Claude Code, dùng audit chỉ đọc đúng mode như mô tả trong Lỗi cài Kit. Nếu audit thoát 1, hãy xử lý drift được báo trước khi debug runtime discovery.

Đọc các bề mặt hook Claude đang active

Các check Claude Code hook_registration và hook_log kiểm tra mọi install surface đang active mà chúng quy được trong context hiện tại: scope user hoặc project, cùng delivery native hoặc plugin. Trong JSON, chi tiết registration liệt kê kit, scope, mode, đường dẫn manifest hoặc settings và registration bị thiếu dưới details.surfaces; chi tiết hook log liệt kê từng log active dưới details.logs.

Hook log chưa tồn tại vẫn là trạng thái khỏe trên surface mới và không chứng minh Skill hoặc Agent bị thiếu. Warning registration nêu surface bị ảnh hưởng. Khi Doctor in một lệnh sửa duy nhất không mơ hồ, hãy dùng đúng target, scope và delivery mode đó; nếu không, sửa rõ từng surface được nêu thay vì refresh route khác.

Khôi phục activation plugin Claude

Chỉ có file plugin chưa đủ để activate plugin Claude Code. Nếu bản cài cảnh báo không tìm thấy CLI claude, hãy chạy theo thứ tự hai lệnh đầy đủ được in trong cảnh báo:

claude plugin marketplace add "<marketplace-source>" --scope <project-or-user>
claude plugin install <kit>@<marketplace> --scope <project-or-user>

Dùng đúng source, plugin reference và cùng scope trong output cài đặt. Lệnh đầu đăng ký marketplace; lệnh thứ hai ghi nhận bản cài plugin trong Claude Code. Sau đó đóng và mở lại Claude Code trong đúng project. Cũng phải mở session Claude Code mới sau khi chuyển giữa native delivery và plugin delivery; session đang chạy không tải lại mode đó.

Khôi phục tool Agent của Codex

Skill và Agent Codex có đường discovery riêng. Skill là file native dưới .agents/skills và không cần AgentKit MCP server. Agent là file TOML được AgentKit runtime đã đăng ký cung cấp thành tool agent_<slug>.

Kiểm tra codex_mcp_registration trong báo cáo doctor Codex. Nếu check này báo thiếu [mcp_servers.ak-agent-runtime], hãy đăng ký một lần:

ak doctor --adapter codex --json
ak codex-agent-runtime register
ak codex-agent-runtime serve --list-only

Registration cập nhật ${CODEX_HOME:-~/.codex}/config.toml theo cách idempotent và giữ các MCP server entry khác. Lệnh list-only chỉ đọc và phải liệt kê các Agent mong đợi trước khi tiếp tục.

Với Agent ở scope project, chạy check từ thư mục project, nơi Codex khởi chạy runtime. Không cần thêm flag: runtime phục vụ <dir>/.codex/agents/ gần nhất tại hoặc phía trên thư mục làm việc của nó. Việc tìm kiếm dừng ở repository root (thư mục đầu tiên có .git), trước thư mục home của bạn và ở gốc filesystem.

Runtime chỉ phục vụ Agent của project khi cấu hình Codex của bạn đánh dấu project đó, hoặc repository root chứa nó, là trusted, cùng quy tắc Codex dùng để tải layer .codex của project. AgentKit không ghi trust này. Output list-only hiển thị kết quả trên dòng project agents::

• project agents: <dir> nghĩa là thư mục được phục vụ. Các Agent của nó được liệt kê với hậu tố (project).
• project agents: skipped (<reason>) nghĩa là đã tìm thấy thư mục nhưng không phục vụ. Với project untrusted hoặc chưa được ghi nhận, lý do sẽ hướng dẫn cách trust: khởi động Codex trong project đó và chấp nhận trust prompt, hoặc đổi trust_level của project đó thành "trusted" trong cấu hình Codex.

Agent của project thay thế Agent người dùng cùng tên trong ~/.codex/agents/, còn Agent người dùng vẫn thắng Agent Kit được stage theo plugin. Thư mục .codex hoặc .codex/agents là symlink hoặc Windows junction được báo là link và bị bỏ qua, còn file TOML dạng link bên trong thư mục project bị bỏ qua. Nếu vẫn không thấy Agent mong đợi, hãy xử lý scope hoặc trust mismatch thay vì sao chép file TOML. Sau khi đăng ký, trust hoặc sửa scope, đóng và mở session Codex mới để tải lại cấu hình MCP.

Nếu Codex không tìm thấy ak:team

Projection Engineer có ak:team dưới dạng Codex Skill tại <project>/.agents/skills/ak-team/ hoặc ~/.agents/skills/ak-team/. Gọi Skill bằng:

$ak:team <template> <context> [flags]

Nếu Codex không discover Skill, hãy xác nhận Engineer Skill đã được chọn, kiểm tra install path cùng scope rồi mở session Codex mới. Chỉ discover được Skill chưa chứng minh runtime hỗ trợ thực thi: workflow cần live team creation, shared work, messaging, waiting, graceful shutdown và cleanup. Nếu thiếu hoặc lỗi bất kỳ capability bắt buộc nào, $ak:team phải hard-stop và báo observed error thay vì âm thầm dùng ordinary Codex subagent thay thế.

Nếu bản cài báo Hooks bị bỏ

Trên target Codex, bản cài thành công có thể chứa đúng dòng tóm tắt này:

[!] Hook groups not projected: 1 group - see warnings

Đây là chẩn đoán partial projection được hỗ trợ, không phải lỗi cài đặt bị che. Nó có nghĩa là hook group được nêu dùng matcher cho các Claude tool không có tương đương trong namespace tool của Codex, nên group đó và các handler được nêu không được project. Các hook tương thích khác cùng Skill hoặc Agent đã cài là kết quả riêng; hãy kiểm tra các dòng tương ứng trong cùng install summary.

Con số này đếm matcher group, không phải tệp hoặc script. Output cài đặt JSON báo cùng giới hạn trong hooksDropped và droppedHookSummaries. Warning theo sau nêu event, matcher và handler bị ảnh hưởng.

Với Engineer, group PostToolUse có matcher Agent|Task|TodoWrite|TodoRead gọi session-state.cjs không được project, vì vậy group này không refresh task-state giữa session. Các group tương thích Edit|Write và * vẫn còn, và task-state vẫn refresh tại các ranh giới turn và subagent Stop cùng SubagentStop được hỗ trợ. Không thử lại với --force, sao chép cấu hình hook Claude sang Codex hoặc xóa home của runtime để loại bỏ cảnh báo.

Link ở Codex hooks root bị từ chối

Codex home do wrapper quản lý chỉ được liên kết leaf hooks cuối cùng tới ~/.codex/hooks canonical của user đã resolve, dưới dạng symlink POSIX hoặc directory junction trên Windows. AgentKit dùng path canonical đó cho command Hook, thao tác ghi, rollback và ownership. Parent có link, hoặc leaf resolve ra bất kỳ đích nào khác thư mục hooks canonical của user, đều bị từ chối.

Hãy kiểm tra CODEX_HOME đã cấu hình, leaf hooks và target sau khi resolve. Sửa wrapper hoặc layout filesystem; không dùng --force, thay parent bằng link khác hoặc redirect leaf tới thư mục writable tùy ý.

Hook Codex lỗi trên Windows

Hook .cjs đủ điều kiện bên trong Codex home đã resolve có thể chạy từ đường dẫn có khoảng trắng qua sibling shim .cmd do AgentKit quản lý. Đường dẫn có khoảng trắng bên ngoài Codex home, đường dẫn có metacharacter của cmd.exe, basename shim không phải ASCII hoặc argument được bake không an toàn hay không phải ASCII vẫn không được hỗ trợ và sẽ tạo warning. Đường dẫn không có khoảng trắng tiếp tục dùng lệnh trực tiếp.

Không di chuyển hook bên ngoài vào Codex home hoặc sửa tay shim được generate như một workaround. Hãy giữ warning cùng diagnostics đã che dữ liệu nhạy cảm.

Ở global scope, AgentKit chỉ merge registration do nó sở hữu vào ~/.codex/hooks.json dùng chung, giữ cấu trúc của user hoặc nguồn khác, và xóa cấu trúc rỗng do AgentKit sở hữu khi owner cuối cùng rời đi. Không sửa tay ownership sidecar hoặc xóa rộng tệp hooks dùng chung.

Kiểm tra scope cấu hình

Từ cùng thư mục project với runtime session, chạy:

ak config prefs resolve
ak config prefs validate

Tệp project ghi đè preference người dùng. Preference tắt hook có thể thay đổi hành vi hook, nhưng không cài Skill hoặc Agent đang thiếu. Xem Lỗi cấu hình trước khi sửa tệp.

Sau khi đổi nơi lưu hook state hoặc cài lại hook registration, hãy restart session của runtime bị ảnh hưởng trước khi kiểm tra. Session cũ có thể vẫn giữ hook inventory và state path trước đó.

Xác minh kết quả

Sự cố được giải quyết khi báo cáo doctor cho adapter khỏe, audit áp dụng được không có drift và session runtime mới trong đúng scope liệt kê hoặc nhận diện item mong đợi. Nếu các check đều đạt nhưng discovery vẫn thất bại, export gói đã che dữ liệu nhạy cảm:

ak diagnostics export --json > agentkit-diagnostics.json

Ghi lại Kit, target, scope, các Skill đã chọn và phiên bản runtime cùng báo cáo.

Trang liên quan

• Lỗi cài Kit
• Cài Kit
• Lỗi cấu hình

hooksDeferred là tập con của hooksDropped: harness bridge chưa project được subscription này, không đồng nghĩa runtime không hỗ trợ. Đọc summary để phân biệt deferred và unsupported.