diagnosing-skillslisted

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.
phoben/agent-skills · ★ 0 · AI & Automation · score 70

Install: claude install-skill phoben/agent-skills

# 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` ex