跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

reasonix-guide

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.

esengine · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add esengine/DeepSeek-Reasonix --skill reasonix-guide

技能说明


name: reasonix-guide 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." runAs: inline

Reasonix self-diagnostics guide

This skill is inlined. Prefer evidence over guessing.

First action

  1. Run a static capability report (no network, no MCP subprocesses):
reasonix doctor capabilities --json
  1. Only if the user explicitly allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:
reasonix doctor capabilities --live --timeout 5s --json
  1. 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):

  1. project — <workspace>/{.reasonix,.agents,.agent,.claude}/skills/
  2. custom — [skills].paths (and plugin package skill roots)
  3. global — <Reasonix home>/skills and home convention dirs
  4. 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: .reasonix, .agents, .agent, .claude (see config.ConventionDirs). Layouts: <name>/SKILL.md or flat <name>.md (Claude flat files need skill frontmatter).

Checks

EntryHow
CLIreasonix doctor capabilities → Skills section
DesktopSettings → Skills; Settings → Diagnostics
Agent/skill list, /reasonix-guide, run_skill

Symptom → cause → fix

SymptomLikely causeFix
Skill missing from indexDisabled, shadowed, missing description, wrong rootCheck report codes skill.shadowed, skill.missing_description, disabled list, discovery roots
Builtin overriddenProject/global same nameRename or remove user skill; disable if intentional
Flat Claude file ignoredNo skill frontmatter under .claude/skillsAdd description: / runAs: frontmatter or use SKILL.md folder
Body never loadsExpected: bodies are on-demandInvoke via /name or run_skill

Ordered triage

  1. reasonix doctor capabilities --json → Skills
  2. Confirm name not in disabled_skills
  3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots
  4. Missing description: skill may load but index placeholder is weak — add description:
  5. Reopen session / Refresh Skills after config changes

Commands (slash templates)

Priority

config.CommandDirsForRoot: home convention commands → Reasonix 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

SymptomCauseFix
Wrong bodyShadowed by later dirCheck command.shadowed winners
Missing commandWrong dir / extensionPlace *.md under a scanned commands/ root
Parse failUnreadable fileFix 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>/.reasonix/settings.json — loaded automatically
  • Plugin packages: installed enabled packages
  • Global: <Reasonix 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

SymptomCauseFix
Project hooks silentWrong workspace / restart requiredConfirm the project path and restart Reasonix after saving
Matcher never firesNon-anchored assumption / bad regexFix match (hook.invalid_matcher)
Command missingEmpty command / missing context fileFix settings entry
Malformed JSONInvalid settings.jsonRepair JSON (file yields no hooks, no crash)

MCP servers

Merge order

config.LoadForRoot merges:

  1. User/project TOML [[plugins]] (higher name wins vs later sources when already defined)
  2. Project .mcp.json servers not already in TOML
  3. 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

ModeBehavior
Static doctorConfig validity, command path / URL shape, start intent — no subprocess
CLI --liveIsolated Host via boot.PluginSpecsForRoot + plugin.Start; auto-start only; concurrency 4; always Close
Desktop runtimeRead active tab Host only

Symptom → cause → fix

SymptomCauseFix
Not connected`auto_start
阅读完整来源 ↗