| 1 | # Skills |
| 2 | |
| 3 | ### Config sources and priority |
| 4 | |
| 5 | Winner per skill name (highest first): |
| 6 | |
| 7 | 1. **project** — `<workspace>/{.reasonix,.agents,.agent,.claude}/skills/` |
| 8 | 2. **custom** — `[skills].paths` (and plugin package skill roots) |
| 9 | 3. **global** — `<Reasonix home>/skills` and home convention dirs |
| 10 | 4. **builtin** — shipped skills (including this guide) |
| 11 | |
| 12 | Same name: higher scope wins; lower scopes are **shadowed**. `[skills].disabled_skills` hides a name from List/Read entirely. |
| 13 | |
| 14 | Discovery conventions: `.reasonix`, `.agents`, `.agent`, `.claude` (see `config.ConventionDirs`). Layouts: `<name>/SKILL.md` or flat `<name>.md` (Claude flat files need skill frontmatter). |
| 15 | |
| 16 | ### Checks |
| 17 | |
| 18 | | Entry | How | |
| 19 | | --- | --- | |
| 20 | | CLI | `reasonix doctor capabilities` → Skills section | |
| 21 | | Desktop | Settings → Skills; Settings → Diagnostics | |
| 22 | | Chat / agent | `/skills` picker, `/reasonix-guide`, `run_skill` | |
| 23 | |
| 24 | ### Symptom → cause → fix |
| 25 | |
| 26 | | Symptom | Likely cause | Fix | |
| 27 | | --- | --- | --- | |
| 28 | | Skill missing from index | Disabled, shadowed, wrong root, or catalog preview limit | Search/list through `use_capability`; then check `skill.shadowed`, disabled names, and discovery roots | |
| 29 | | Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional | |
| 30 | | Flat Claude file ignored | No skill frontmatter under `.claude/skills` | Add `description:` / `runAs:` frontmatter or use `SKILL.md` folder | |
| 31 | | Body never loads | Expected: bodies are on-demand | Invoke via `/name` or `run_skill` | |
| 32 | |
| 33 | ### Ordered triage |
| 34 | |
| 35 | 1. `reasonix doctor capabilities --json` → Skills |
| 36 | 2. Confirm name not in `disabled_skills` |
| 37 | 3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots |
| 38 | 4. Missing description: skill may load but index placeholder is weak — add `description:` |
| 39 | 5. Reopen session / Refresh Skills after config changes |
| 40 |