AGENT SKILL

diagnosing-skills

Use to diagnose and fix ZCode skill configuration problems in the ZCode client. Applies when a skill is not discovered, is installed but does not trigger automatically, is shadowed by a higher-precedence skill of the same name, is disabled by configuration, has a SKILL.md frontmatter error, fails to load because its description is too long, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect skills in the client, common pitfalls, and a step-by-step localization and repair workflow.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 253
Forks
20

01 前言 Front Matter

name
diagnosing-skills
description
Use to diagnose and fix ZCode skill configuration problems in the ZCode client. Applies when a skill is not discovered, is installed but does not trigger automatically, is shadowed by a higher-precedence skill of the same name, is disabled by configuration, has a SKILL.md frontmatter error, fails to load because its description is too long, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect skills in the client, common pitfalls, and a step-by-step localization and repair workflow.

03 SKILL.md 正文

Diagnosing Skill Configuration

Goal: reduce any skill problem to a single concrete fix. A skill "loading successfully" and a skill "triggering" are two different things — distinguish them first.

A person inspects skills in Settings → Skills and the / menu (the Skills group); an agent inspects by reading the skill files at the locations below.

1. Discovery order (earlier locations take precedence)

  1. Explicitly configured roots
  2. User ~/.zcode/skills
  3. User ~/.agents/skills
  4. Workspace .zcode/skills (from the current directory up to the repository root; every level counts, and a deeper location wins)
  5. Workspace .agents/skills
  6. Enabled plugin roots (lowest precedence)

Within a level, .zcode is scanned before .agents. A skill's identity is its file path, so same-named skills at different paths are all discovered, but only the first in discovery order is loaded — higher-precedence copies shadow the rest. Directories beginning with . (except .system) and node_modules are skipped.

2. SKILL.md format (two-tier failure model)

A skill is a directory containing a SKILL.md. Frontmatter is a ----delimited block of flat key: value lines (indented keys are ignored; use > or | for multi-line values). The recognized keys are name, description, when_to_use, license, and metadata.

Fails to load (the skill is dropped): frontmatter is present but name is missing, description is missing, or description exceeds 1024 characters.

Loads but may not trigger: no frontmatter at all — name defaults to the directory name and description is empty, leaving the model nothing to match on; a malformed line is skipped.

Triggering: a skill's name, description (truncated to ~250 characters), and when_to_use are presented to the model, which decides on its own whether to invoke the skill. There is no keyword matcher — a description that clearly states "when to use this" is what makes a skill discoverable to the model.

3. How to inspect skills

  • In the client: Settings → Skills lists every discovered skill and its group, including a Plugin Skills group for plugin-provided ones. In the input box, type / and open the Skills group to see what is available and search by keyword.
  • As an agent: read the SKILL.md at each location in discovery order. The file that would actually load is the first one whose frontmatter name (or the plugin's plugin:skill qualified name) matches — if that is not the file you edited, you have found a shadow.

4. Common pitfalls (symptom → cause → fix)

  1. Not discovered — wrong directory — absent from the Skills list. It is not directly under a discovery root, or the file is not named SKILL.md (case-sensitive on Linux). → Move the skill directory under a real root: ~/.zcode/skills/<name>/SKILL.md or <repo>/.zcode/skills/<name>/SKILL.md.
  2. Skipped inside a dot-directory — a skill under, for example, ~/.zcode/skills/.foo/ never appears. Directories beginning with . (except .system) are excluded. → Rename to remove the leading ..
  3. Not triggering — weak or empty description — it appears but the model never invokes it. Without frontmatter the description is empty, and it is truncated to ~250 characters when presented. → Add a frontmatter description and when_to_use, front-loading the trigger wording within the first ~250 characters.
  4. Shadowed by a higher-precedence skill of the same name — your edits have no effect. On load the first same-named skill wins; user overrides workspace overrides plugin, and a deeper working-directory location overrides the repository root. → Find the higher-precedence copy in discovery order and rename or remove it.
  5. Disabled by configuration — a known-good skill disappears entirely. The configuration disables it by absolute path. → In ~/.zcode/cli/config.json (or the workspace .zcode/config.json), set that path's enable to true or remove the override.
  6. Frontmatter parse error or wrong shape — name/description missing or garbled. The parser reads only top-level scalars; indented keys are ignored, and multi-line values need > or |. → Keep name/description as top-level scalars and use description: > with an indented continuation for long text.
  7. Missing SKILL.md — the directory exists but the skill never appears. → Ensure the file is named exactly SKILL.md.
  8. Description too long (over 1024 characters) — the skill is dropped. → Trim description under 1024 characters and move detail into the body.
  9. An .agents copy is shadowed by a same-named .zcode copy — it is discovered but the .zcode copy is what loads, because .zcode is scanned first within a level. → Remove the .zcode duplicate or rename one.
  10. A plugin skill disappears because the plugin is disabled or suppressed — a disabled plugin contributes no skill roots. → Enable the plugin in Settings → Plugin Management, or remove it from the suppressed-built-ins list.
  11. Path-versus-name confusion — a skill is invoked by name or plugin:skill, not by file path and not with a leading /. → Reference the exact name.
  12. The whole skill subsystem is off — no skills appear and the skill tool reports it is not configured. The skill feature or skills.enabled is false. → Set both to true (both default to true).

5. Localization workflow (in order; stop when the cause is found)

  1. Is the subsystem on? In ~/.zcode/cli/config.json (and the workspace file) confirm the skill feature and skills.enabled; either being false disables discovery — pitfall 12.
  2. Is it discovered at all? Check Settings → Skills, and read the skill files from the same working directory the session runs in (discovery is relative to it). Absent entirely → pitfalls 1, 2, 5, 7, 10, or 12.
  3. Check for load failures. A skill present on disk but not listed usually has a frontmatter problem: missing name/description, an over-long description, or a malformed frontmatter line — pitfalls 6 and 8.
  4. Which file actually wins? Walk the discovery order for the name and compare the first matching SKILL.md to the file you edited. A mismatch means shadowing — pitfalls 4 and 9.
  5. Is it disabled? Look in both configuration files for the skill's absolute path with enable: false.
  6. A plugin skill? If the name is plugin:skill, confirm the plugin is enabled and not suppressed.
  7. Discovered but will not trigger? Inspect the description/when_to_use; empty or overly long/truncated → pitfall 3.

04 同仓库更多 Skills

ZCodium-project
ZCodium-project/ZCodium

plugin-mcp-ping

E2E workspace Plugin skill marker

★ 253
ZCodium-project
ZCodium-project/ZCodium

zcode-configuration-guide

Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect, or needs routing to a specific diagnostic skill.

★ 253
ZCodium-project
ZCodium-project/ZCodium

diagnosing-plugins

Use to diagnose and fix ZCode plugin and marketplace problems in the ZCode client. Applies when a plugin is not listed, adding a marketplace or installing a plugin fails, a plugin is enabled but its skills or commands are missing, a built-in plugin still appears after being disabled, a plugin is not enabled as expected, a plugin.json manifest has a parse error, a plugin name is invalid, a dependency is unresolved or blocked across marketplaces, or a sensitive configuration value cannot be entered in the interface. Provides the plugin lifecycle, manifest schema, how to manage plugins in the client, and a step-by-step localization and repair workflow.

★ 253
ZCodium-project
ZCodium-project/ZCodium

diagnosing-mcp

Use to diagnose and fix ZCode MCP (Model Context Protocol) server configuration problems in the ZCode client. Applies when an MCP server will not connect, its tools (mcp__server__tool) do not appear, it shows as disabled or failed, connections time out, a command cannot be found, template variables are not expanded, or a server defined in a configuration file has no effect. Provides configuration locations, how to inspect status in Settings, common pitfalls, and a step-by-step localization and repair workflow.

★ 253
ZCodium-project
ZCodium-project/ZCodium

diagnosing-hooks

Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds versus milliseconds), the command and process field styles are mixed, a hook's JSON output fails validation, a hook blocks the session unexpectedly, or configuration-file hooks are not enabled. Provides configuration sources, the hooks.json schema, how to inspect hooks in the client, and a step-by-step localization and repair workflow.

★ 253
ZCodium-project
ZCodium-project/ZCodium

diagnosing-commands

Use to diagnose and fix ZCode custom slash-command (/command) configuration problems in the ZCode client. Applies when a command is missing, is overridden by a higher-precedence command of the same name, has a frontmatter parse error, is dropped for having an empty body, has an invalid name, does not substitute $ARGUMENTS/$1, uses a colon rather than a slash for nested names, has a misspelled frontmatter key, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect commands in the client, common pitfalls, and a step-by-step localization and repair workflow.

★ 253