| 1 | --- |
| 2 | name: reasonix-guide |
| 3 | description: "Troubleshoot and configure Reasonix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (reasonix.toml + .mcp.json + plugin packages, auto_start), plugin packages (native/Codex/Claude manifests), and AGENTS.md / instruction docs. Use when the user asks how to configure, debug missing skills/commands/hooks/MCP/plugins, or diagnose capability loading." |
| 4 | runAs: inline |
| 5 | --- |
| 6 | |
| 7 | # Reasonix self-diagnostics guide |
| 8 | |
| 9 | This skill is **inlined**. Prefer evidence over guessing. |
| 10 | |
| 11 | ## First action |
| 12 | |
| 13 | 1. Run a **static** capability report (no network, no MCP subprocesses): |
| 14 | |
| 15 | ```bash |
| 16 | reasonix doctor capabilities --json |
| 17 | ``` |
| 18 | |
| 19 | 2. Only if the user **explicitly** allows starting third-party MCP servers (may network and pass configured env/headers), run live probe: |
| 20 | |
| 21 | ```bash |
| 22 | reasonix doctor capabilities --live --timeout 5s --json |
| 23 | ``` |
| 24 | |
| 25 | 3. On desktop, open **Settings → Diagnostics** for the same report model. The desktop "include current session runtime" toggle only **reads** the active tab Host (connected/failed/deferred/disabled); it does **not** start MCP. |
| 26 | |
| 27 | Do not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report. |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## Skills |
| 32 | |
| 33 | ### Config sources and priority |
| 34 | |
| 35 | Winner per skill name (highest first): |
| 36 | |
| 37 | 1. **project** — `<workspace>/{.reasonix,.agents,.agent,.claude}/skills/` |
| 38 | 2. **custom** — `[skills].paths` (and plugin package skill roots) |
| 39 | 3. **global** — `<Reasonix home>/skills` and home convention dirs |
| 40 | 4. **builtin** — shipped skills (including this guide) |
| 41 | |
| 42 | Same name: higher scope wins; lower scopes are **shadowed**. `[skills].disabled_skills` hides a name from List/Read entirely. |
| 43 | |
| 44 | Discovery conventions: `.reasonix`, `.agents`, `.agent`, `.claude` (see `config.ConventionDirs`). Layouts: `<name>/SKILL.md` or flat `<name>.md` (Claude flat files need skill frontmatter). |
| 45 | |
| 46 | ### Checks |
| 47 | |
| 48 | | Entry | How | |
| 49 | | --- | --- | |
| 50 | | CLI | `reasonix doctor capabilities` → Skills section | |
| 51 | | Desktop | Settings → Skills; Settings → Diagnostics | |
| 52 | | Agent | `/skill` list, `/reasonix-guide`, `run_skill` | |
| 53 | |
| 54 | ### Symptom → cause → fix |
| 55 | |
| 56 | | Symptom | Likely cause | Fix | |
| 57 | | --- | --- | --- | |
| 58 | | Skill missing from index | Disabled, shadowed, missing description, wrong root | Check report codes `skill.shadowed`, `skill.missing_description`, disabled list, discovery roots | |
| 59 | | Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional | |
| 60 | | Flat Claude file ignored | No skill frontmatter under `.claude/skills` | Add `description:` / `runAs:` frontmatter or use `SKILL.md` folder | |
| 61 | | Body never loads | Expected: bodies are on-demand | Invoke via `/name` or `run_skill` | |
| 62 | |
| 63 | ### Ordered triage |
| 64 | |
| 65 | 1. `reasonix doctor capabilities --json` → Skills |
| 66 | 2. Confirm name not in `disabled_skills` |
| 67 | 3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots |
| 68 | 4. Missing description: skill may load but index placeholder is weak — add `description:` |
| 69 | 5. Reopen session / Refresh Skills after config changes |
| 70 | |
| 71 | --- |
| 72 | |
| 73 | ## Commands (slash templates) |
| 74 | |
| 75 | ### Priority |
| 76 | |
| 77 | `config.CommandDirsForRoot`: home convention commands → Reasonix home commands → project convention commands. **Later directory overrides earlier** on name clash (`command.Load`). |
| 78 | |
| 79 | Name from path: `git/commit.md` → `/git:commit` (slashes → `:`). |
| 80 | |
| 81 | ### Checks |
| 82 | |
| 83 | CLI/Desktop Diagnostics → Commands; invoke `/name` in chat. |
| 84 | |
| 85 | ### Symptom → cause → fix |
| 86 | |
| 87 | | Symptom | Cause | Fix | |
| 88 | | --- | --- | --- | |
| 89 | | Wrong body | Shadowed by later dir | Check `command.shadowed` winners | |
| 90 | | Missing command | Wrong dir / extension | Place `*.md` under a scanned `commands/` root | |
| 91 | | Parse fail | Unreadable file | Fix permissions / encoding (`command.read_failed`) | |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## Hooks |
| 96 | |
| 97 | ### Events (11) |
| 98 | |
| 99 | `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `PostLLMCall`, `SessionStart`, `SessionEnd`, `SubagentStop`, `Notification`, `PreCompact`. |
| 100 | |
| 101 | **Blocking** (exit 2 can gate the loop): `PreToolUse`, `UserPromptSubmit`. Others warn or contribute context only. |
| 102 | |
| 103 | ### Sources |
| 104 | |
| 105 | - Project: `<workspace>/.reasonix/settings.json` — loaded automatically |
| 106 | - Plugin packages: installed enabled packages |
| 107 | - Global: `<Reasonix home>/settings.json` (always) |
| 108 | |
| 109 | Match field is an **anchored** regex: `file` does **not** match `read_file`; use `.*file` or `*`. Timeout is **milliseconds** (defaults 5s gating / 30s other). |
| 110 | |
| 111 | ### Checks |
| 112 | |
| 113 | `/hooks`, Settings → Hooks, Diagnostics → Hooks. |
| 114 | |
| 115 | ### Symptom → cause → fix |
| 116 | |
| 117 | | Symptom | Cause | Fix | |
| 118 | | --- | --- | --- | |
| 119 | | Project hooks silent | Wrong workspace / restart required | Confirm the project path and restart Reasonix after saving | |
| 120 | | Matcher never fires | Non-anchored assumption / bad regex | Fix match (`hook.invalid_matcher`) | |
| 121 | | Command missing | Empty command / missing context file | Fix settings entry | |
| 122 | | Malformed JSON | Invalid settings.json | Repair JSON (file yields no hooks, no crash) | |
| 123 | |
| 124 | --- |
| 125 | |
| 126 | ## MCP servers |
| 127 | |
| 128 | ### Merge order |
| 129 | |
| 130 | `config.LoadForRoot` merges: |
| 131 | |
| 132 | 1. User/project TOML `[[plugins]]` (higher name wins vs later sources when already defined) |
| 133 | 2. Project `.mcp.json` servers not already in TOML |
| 134 | 3. Enabled **plugin packages** MCP (skipped if name already defined) |
| 135 | |
| 136 | Transports: `stdio` (default), `http` / streamable-http, `sse`. `auto_start=false` skips startup; nil/true = automatic. Tier `eager` blocks boot handshake; empty/background connects without blocking chat. |
| 137 | |
| 138 | Env/header values may contain secrets — diagnostics list **keys only**. |
| 139 | |
| 140 | ### Checks |
| 141 | |
| 142 | | Mode | Behavior | |
| 143 | | --- | --- | |
| 144 | | Static doctor | Config validity, command path / URL shape, start intent — **no** subprocess | |
| 145 | | CLI `--live` | Isolated Host via `boot.PluginSpecsForRoot` + `plugin.Start`; auto-start only; concurrency 4; always Close | |
| 146 | | Desktop runtime | Read active tab Host only | |
| 147 | |
| 148 | ### Symptom → cause → fix |
| 149 | |
| 150 | | Symptom | Cause | Fix | |
| 151 | | --- | --- | --- | |
| 152 | | Not connected | `auto_start=false` or failed start | Enable / fix command/URL (`mcp.command_not_found`, `mcp.start_failed`) | |
| 153 | | No tools | Connected but empty tools/list | Server config or permissions (`mcp.no_tools`) | |
| 154 | | Wrong source | Shadowed by TOML vs `.mcp.json` vs package | Inspect report Source / package owner | |
| 155 | | Invalid transport | Bad `type` | Use stdio/http/sse (`mcp.invalid_transport`) | |
| 156 | |
| 157 | --- |
| 158 | |
| 159 | ## Plugin packages |
| 160 | |
| 161 | ### Manifests |
| 162 | |
| 163 | - Native: `reasonix-plugin.json` |
| 164 | - Codex: `.codex-plugin/plugin.json` |
| 165 | - Claude: `.claude-plugin/plugin.json` (+ limited Claude compatibility paths) |
| 166 | |
| 167 | State: `<Reasonix home>/plugin-packages.json`. Disabled packages do not contribute skills/hooks/MCP. |
| 168 | |
| 169 | Unmapped Claude-only features may appear as compatibility warnings — Reasonix does not invent support. |
| 170 | |
| 171 | ### Checks |
| 172 | |
| 173 | `reasonix plugin doctor <name>`, Settings → Plugins, Diagnostics → Plugins. |
| 174 | |
| 175 | ### Symptom → cause → fix |
| 176 | |
| 177 | | Symptom | Cause | Fix | |
| 178 | | --- | --- | --- | |
| 179 | | Package missing | Bad root path | Reinstall / fix root (`plugin.missing_root`) | |
| 180 | | Invalid manifest | Parse failure | Fix JSON/manifest (`plugin.invalid_manifest`) | |
| 181 | | Skills missing | Disabled package | Enable package | |
| 182 | |
| 183 | --- |
| 184 | |
| 185 | ## Instructions (AGENTS.md / REASONIX.md) |
| 186 | |
| 187 | ### Load order (ascending specificity) |
| 188 | |
| 189 | User global docs → ancestor chain → project docs → project-local (`*.local.md`). |
| 190 | |
| 191 | Recognized names: `REASONIX.md`, `AGENTS.md`, `CLAUDE.md` (and `*.local.md` variants). Multiple files in one directory can load; symlink identity is deduped. |
| 192 | |
| 193 | Instructions fold into the system prompt at session boot (cache-stable prefix); |
| 194 | Hooks remain runtime event handlers loaded from their configured locations. |
| 195 | |
| 196 | ### Checks |
| 197 | |
| 198 | Diagnostics → Instructions; memory Settings; read files on disk. |
| 199 | |
| 200 | ### Symptom → cause → fix |
| 201 | |
| 202 | | Symptom | Cause | Fix | |
| 203 | | --- | --- | --- | |
| 204 | | Guidance ignored | Wrong filename / empty file | Use recognized names under correct dir | |
| 205 | | Wrong scope won | Local override | Check load order in report | |
| 206 | |
| 207 | --- |
| 208 | |
| 209 | ## Desktop Diagnostics page |
| 210 | |
| 211 | - Static report on open; Refresh re-runs static collect |
| 212 | - Copy redacted JSON |
| 213 | - Optional session runtime merge (read-only Host) |
| 214 | - Jump to Settings for MCP / Skills / Plugins / Hooks when issue `settings_tab` is set |
| 215 | - **Never** auto-edit config, execute hooks, or auto-reconnect from this page |
| 216 | |
| 217 | --- |
| 218 | |
| 219 | ## Safety |
| 220 | |
| 221 | - Prefer static diagnostics |
| 222 | - Live MCP may run third-party code and network |
| 223 | - Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths |
| 224 | - Report paths as `<workspace>/…`, `~/…`, or `<external>/…` |
| 225 |