Agent không nhận skill: kiểm tra đường dẫn, tệp và runtime

Ghi tên và phiên bản agent, thư mục đang mở, ID skill, cách cài, đường dẫn đích và thông báo lỗi nguyên văn. Dùng một skill để thử trước; thay nhiều thư mục hoặc cấu hình cùng lúc khiến khó biết thay đổi nào có tác dụng.

• Không có trong danh sách: kiểm tra discovery và phạm vi.
• Có trong danh sách nhưng agent bỏ qua: kiểm tra mô tả, tên gọi và chế độ invocation.
• Agent đọc runbook rồi lỗi: kiểm tra helper, runtime, đầu vào và quyền.

Record the agent and version, open directory, skill ID, installation method, destination and exact error. Start with one skill. Changing several paths or settings at once hides which change affected the outcome.

• Absent from the list: investigate discovery and scope.
• Listed but ignored: check its description, name and invocation mode.
• Runbook read, then failure: inspect helpers, runtime, inputs and permissions.

1. Đúng đường dẫn và máy: Codex hiện dùng .agents/skills; Claude Code dùng .claude/skills. Phạm vi cá nhân nằm dưới home tương ứng. Một skill trên laptop chưa chắc tồn tại trong container, SSH host hoặc phiên cloud.
2. Đúng cấu trúc: cần skills/ten-skill/SKILL.md, không thêm một tầng thư mục giải nén ngoài ý muốn. Kiểm tra cả chữ hoa của SKILL.md trên hệ thống phân biệt hoa thường.
3. Frontmatter hợp lệ: các dấu --- phải bao quanh metadata; name và description cần giá trị có nghĩa. Không sao chép cả dấu code fence Markdown vào tệp.
4. Phạm vi phiên làm việc: mở đúng repository và thử một phiên mới nếu ứng dụng chưa cập nhật danh sách. Với monorepo, kiểm tra vị trí thư mục con theo tài liệu agent.
5. Symlink còn nguồn: nếu cài bằng link, xác nhận clone VAS chưa bị di chuyển hoặc xóa. Một liên kết tồn tại vẫn có thể trỏ tới tệp đã mất.

1. Correct path and machine: current Codex uses .agents/skills; Claude Code uses .claude/skills. Personal locations sit under the corresponding home directory. A laptop installation may not exist in a container, SSH host or cloud session.
2. Correct structure: expect skills/skill-name/SKILL.md, without an accidental extra archive directory. Check filename case on case-sensitive systems.
3. Valid frontmatter: surround metadata with ---; provide meaningful name and description values. Do not paste Markdown code fences into the file.
4. Session scope: open the correct repository and try a new session if the list is stale. For monorepos, check nested-directory behavior in the agent documentation.
5. Live symlink target: a link installation needs its source clone. A symlink can exist even when its target has disappeared.

from pathlib import Path

skill = Path("/absolute/path/to/project/.agents/skills/webapp-testing/SKILL.md")
print("Resolved path:", skill.resolve())
print("Runbook exists:", skill.is_file())
print("Skill folder is a link:", skill.parent.is_symlink())

Thử gọi trực tiếp theo giao diện agent: Codex CLI/IDE hỗ trợ chọn skill bằng $ hoặc /skills; Claude Code có /ten-skill cho skill cho phép gọi trực tiếp. Sau đó đối chiếu tên và đường dẫn runbook mà agent đọc.

Nếu gọi trực tiếp được nhưng tự chọn không ổn, xem lại description: nó có nêu đúng tác vụ đang yêu cầu không? Trong Claude Code, kiểm tra thêm disable-model-invocation và user-invocable. Đừng suy ra quy tắc của một agent áp dụng giống hệt cho agent khác.

Nếu có nhiều bản trùng tên ở các phạm vi, xác định bản được nạp trước khi cập nhật hoặc gỡ. Tránh cài thêm một bản thứ ba để thử vận may.

Try explicit invocation in the supported interface: Codex CLI/IDE offers $ selection or /skills; Claude Code supports /skill-name for user-invocable skills. Compare the loaded name and runbook path with the intended installation.

If explicit invocation works but automatic matching does not, check whether the description covers the requested task. In Claude Code, inspect disable-model-invocation and user-invocable too. Do not assume one application implements another application’s invocation rules.

When duplicate names exist across scopes, identify the loaded copy before updating or removing anything. Adding another duplicate makes diagnosis harder.

Đây thường là vấn đề môi trường thực thi. Một runbook có thể cần scripts/, references/ hoặc assets đi kèm. Chỉ copy SKILL.md có thể làm thiếu thành phần; kiểm tra tệp cụ thể được nhắc trong thông báo lỗi và inventory nguồn.

Phân biệt thiếu tệp với thiếu package, trình duyệt, Docker, tài khoản hay quyền mạng. Ví dụ, webapp-testing được nhận diện không có nghĩa Playwright và browser runtime đã sẵn sàng. Chỉ thiết lập phần còn thiếu sau khi thống nhất phạm vi và quyền.

./vas status phản ánh thông tin mà CLI quản lý, không kiểm tra thay cho discovery của agent. Nếu thiếu receipt hợp lệ, không tự sửa manifest để ép gỡ tệp. Kiểm tra cách cài và quyền sở hữu thư mục trước.

This is usually an execution-environment problem. A runbook can depend on bundled scripts, references or assets. Copying only SKILL.md may omit them; inspect the exact missing path and source inventory.

Distinguish missing files from missing packages, browsers, Docker, accounts or network access. Discovering webapp-testing does not establish that Playwright and a browser runtime are ready. Provision only the missing prerequisites within the agreed scope.

./vas status reports CLI-managed information; it does not verify native agent discovery. If a valid receipt is absent, do not fabricate manifest entries to force removal. Check the installation method and directory ownership first.

Agent / version:
Working directory and execution environment:
Skill ID and resolved SKILL.md path:
Installation method and scope:
Expected behavior:
Observed error:
One change attempted:
Result of repeating the original check:
Remaining blocker: