Semantix self-diagnostics guide
This skill is inlined. Prefer evidence over guessing.
First action
- Run a static capability report (no network, no MCP subprocesses):
bashsemantix-agent doctor capabilities --json
- Only if the user explicitly allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:
bashsemantix-agent doctor capabilities --live --timeout 5s --json
- 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.
Do not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report.
Skills
Config sources and priority
Winner per skill name (highest first):
- project —
<workspace>/{.semantix,.agents,.agent,.claude}/skills/ - custom —
[skills].paths(and plugin package skill roots) - global —
<Semantix home>/skillsand home convention dirs - builtin — shipped skills (including this guide)
Same name: higher scope wins; lower scopes are shadowed. [skills].disabled_skills hides a name from List/Read entirely.
Discovery conventions: .semantix, .agents, .agent, .claude (see config.ConventionDirs). Layouts: <name>/SKILL.md or flat <name>.md (Claude flat files need skill frontmatter).
Checks
| Entry | How |
|---|---|
| CLI | semantix-agent doctor capabilities → Skills section |
| Desktop | Settings → Skills; Settings → Diagnostics |
| Agent | /skill list, /semantix-guide, run_skill |
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| Skill missing from index | Disabled, shadowed, missing description, wrong root | Check report codes skill.shadowed, skill.missing_description, disabled list, discovery roots |
| Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional |
| Flat Claude file ignored | No skill frontmatter under .claude/skills | Add description: / runAs: frontmatter or use SKILL.md folder |
| Body never loads | Expected: bodies are on-demand | Invoke via /name or run_skill |
Ordered triage
semantix-agent doctor capabilities --json→ Skills- Confirm name not in
disabled_skills - Confirm winner Path/Scope; if shadowed, inspect lower-priority roots
- Missing description: skill may load but index placeholder is weak — add
description: - Reopen session / Refresh Skills after config changes
Commands (slash templates)
Priority
config.CommandDirsForRoot: home convention commands → Semantix home commands → project convention commands. Later directory overrides earlier on name clash (command.Load).
Name from path: git/commit.md → /git:commit (slashes → :).
Checks
CLI/Desktop Diagnostics → Commands; invoke /name in chat.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Wrong body | Shadowed by later dir | Check command.shadowed winners |
| Missing command | Wrong dir / extension | Place *.md under a scanned commands/ root |
| Parse fail | Unreadable file | Fix permissions / encoding (command.read_failed) |
Hooks
Events (11)
PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, Stop, PostLLMCall, SessionStart, SessionEnd, SubagentStop, Notification, PreCompact.
Blocking (exit 2 can gate the loop): PreToolUse, UserPromptSubmit. Others warn or contribute context only.
Sources
- Project:
<workspace>/.semantix/settings.json— loaded automatically - Plugin packages: installed enabled packages
- Global:
<Semantix home>/settings.json(always)
Match field is an anchored regex: file does not match read_file; use .*file or *. Timeout is milliseconds (defaults 5s gating / 30s other).
Checks
/hooks, Settings → Hooks, Diagnostics → Hooks.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Project hooks silent | Wrong workspace / restart required | Confirm the project path and restart Semantix after saving |
| Matcher never fires | Non-anchored assumption / bad regex | Fix match (hook.invalid_matcher) |
| Command missing | Empty command / missing context file | Fix settings entry |
| Malformed JSON | Invalid settings.json | Repair JSON (file yields no hooks, no crash) |
MCP servers
Merge order
config.LoadForRoot merges:
- User/project TOML
[[plugins]](higher name wins vs later sources when already defined) - Project
.mcp.jsonservers not already in TOML - Enabled plugin packages MCP (skipped if name already defined)
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.
Env/header values may contain secrets — diagnostics list keys only.
Checks
| Mode | Behavior |
|---|---|
| Static doctor | Config validity, command path / URL shape, start intent — no subprocess |
CLI --live | Isolated Host via boot.PluginSpecsForRoot + plugin.Start; auto-start only; concurrency 4; always Close |
| Desktop runtime | Read active tab Host only |
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Not connected | auto_start=false or failed start | Enable / fix command/URL (mcp.command_not_found, mcp.start_failed) |
| No tools | Connected but empty tools/list | Server config or permissions (mcp.no_tools) |
| Wrong source | Shadowed by TOML vs .mcp.json vs package | Inspect report Source / package owner |
| Invalid transport | Bad type | Use stdio/http/sse (mcp.invalid_transport) |
Plugin packages
Manifests
- Native:
semantix-plugin.json - Codex:
.codex-plugin/plugin.json - Claude:
.claude-plugin/plugin.json(+ limited Claude compatibility paths)
State: <Semantix home>/plugin-packages.json. Disabled packages do not contribute skills/hooks/MCP.
Unmapped Claude-only features may appear as compatibility warnings — Semantix does not invent support.
Checks
semantix-agent plugin doctor <name>, Settings → Plugins, Diagnostics → Plugins.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Package missing | Bad root path | Reinstall / fix root (plugin.missing_root) |
| Invalid manifest | Parse failure | Fix JSON/manifest (plugin.invalid_manifest) |
| Skills missing | Disabled package | Enable package |
Instructions (AGENTS.md / SEMANTIX.md)
Load order (ascending specificity)
User global docs → ancestor chain → project docs → project-local (*.local.md).
Recognized names: SEMANTIX.md, AGENTS.md, CLAUDE.md (and *.local.md variants). Multiple files in one directory can load; symlink identity is deduped.
Instructions fold into the system prompt at session boot (cache-stable prefix); Hooks remain runtime event handlers loaded from their configured locations.
Checks
Diagnostics → Instructions; memory Settings; read files on disk.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
| Guidance ignored | Wrong filename / empty file | Use recognized names under correct dir |
| Wrong scope won | Local override | Check load order in report |
Desktop Diagnostics page
- Static report on open; Refresh re-runs static collect
- Copy redacted JSON
- Optional session runtime merge (read-only Host)
- Jump to Settings for MCP / Skills / Plugins / Hooks when issue
settings_tabis set - Never auto-edit config, execute hooks, or auto-reconnect from this page
Safety
- Prefer static diagnostics
- Live MCP may run third-party code and network
- Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths
- Report paths as
<workspace>/…,~/…, or<external>/…
