Agent skill

Semantix Guide

by Gnosil in Gnosil/semantix

Troubleshoot and configure Semantix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project…

MITAuto-check passedAgent Workflows

Install Semantix Guide

skills CLI
$ npx skills add Gnosil/semantix --skill semantix-guide -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Gnosil/semantix semantix-guide --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Gnosil/semantix.git skills-src && mkdir -p .claude/skills && cp -r skills-src/harness/skill/builtincontent/semantix-guide .claude/skills/semantix-guide && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
semantix-guide
GitHub stars
821
Token cost
~2.1k tokens
SKILL.md length
880 words
Files
1
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Troubleshoot and configure Semantix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project…

  • Works in 3 steps: Run a static capability report (no… → Only if the user explicitly allows… → On desktop, open Settings → Diagnostics…
  • The user asks how to configure
  • SKILL.md covers First action, Skills, Commands (slash templates) and Hooks, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Semantix Guide is an agent skill from Gnosil/semantix. Troubleshoot and configure Semantix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (semantix-agent.toml + .mcp.json + plugin packages, autostart), 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.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Agent Workflows, covering MCP servers and Agent instruction files. It works with Model Context Protocol. The repository describes itself as: semantic agent kernel which make agent efficient and self-evolve. The licence is MIT.

When your agent uses it

  • The user asks how to configure
  • Debug missing skills/commands/hooks/MCP/plugins
  • Diagnose capability loading

Example prompts

  • “/semantix-guide”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Run a static capability report (no network, no MCP subprocesses)
  2. Only if the user explicitly allows starting third-party MCP servers (may network and pass configured env/headers), run live probe
  3. On desktop, open Settings → Diagnostics for the same report model. The desktop "include current session runtime" toggle only reads the…

What it can do on your machine

Read from SKILL.md and the folder at commit bb8db89. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Semantix Guide loads about 2.1k tokens when it runs. Until then it costs about 129 tokens; SKILL.md has 880 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~129
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Gnosil/semantix at commit bb8db89, republished under its MIT licence (© Gnosil). 880 words, ~2,147 tokens.

Download SKILL.mdSave it as .claude/skills/semantix-guide/SKILL.md (or your agent's skills folder).
name
semantix-guide
description
Troubleshoot and configure Semantix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (semantix-agent.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

Semantix self-diagnostics guide

This skill is inlined. Prefer evidence over guessing.

First action

  1. Run a static capability report (no network, no MCP subprocesses):
bash
semantix-agent 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:
bash
semantix-agent 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>/{.semantix,.agents,.agent,.claude}/skills/
  2. custom — [skills].paths (and plugin package skill roots)
  3. global — <Semantix 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: .semantix, .agents, .agent, .claude (see config.ConventionDirs). Layouts: <name>/SKILL.md or flat <name>.md (Claude flat files need skill frontmatter).

Checks
EntryHow
CLIsemantix-agent doctor capabilities → Skills section
DesktopSettings → Skills; Settings → Diagnostics
Agent/skill list, /semantix-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. semantix-agent 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 → 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
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>/.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
SymptomCauseFix
Project hooks silentWrong workspace / restart requiredConfirm the project path and restart Semantix 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.

Show full SKILL.md (326 more words)Show less
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 connectedauto_start=false or failed startEnable / fix command/URL (mcp.command_not_found, mcp.start_failed)
No toolsConnected but empty tools/listServer config or permissions (mcp.no_tools)
Wrong sourceShadowed by TOML vs .mcp.json vs packageInspect report Source / package owner
Invalid transportBad typeUse 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
SymptomCauseFix
Package missingBad root pathReinstall / fix root (plugin.missing_root)
Invalid manifestParse failureFix JSON/manifest (plugin.invalid_manifest)
Skills missingDisabled packageEnable 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
SymptomCauseFix
Guidance ignoredWrong filename / empty fileUse recognized names under correct dir
Wrong scope wonLocal overrideCheck 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_tab is 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>/…

© Gnosil, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in harness/skill/builtincontent/semantix-guide of Gnosil/semantix.

Open the folder on GitHubat commit bb8db89

Compare with similar skills

Semantix Guide next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Semantix Guide compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Semantix Guide this skillGnosil/semantix821—~2.1kAutomated safety check: PassMIT
Agent Setup Health Audittw93/Waza7.2k—~5.2kAutomated safety check: NotesMIT
Working With Claude Code Docsobra/superpowers-developing-for-claude-code142—~1.5kAutomated safety check: PassNone
Agnixagent-sh/agnix445—~874Automated safety check: PassApache-2.0
Claude Docs Consultantcentminmod/my-claude-code-setup2.7k—~959Automated safety check: PassMIT
Clawmemyoloshii/ClawMem210—~7.5kAutomated safety check: PassMIT

Similar skills

  • Audits a project's agent configuration, instruction drift, hooks, MCP and AI maintainability, then reports prioritized findings with evidence and next actions.

    7.2k GitHub stars~5.2k tokensUpdated yesterday
    Agent WorkflowsAuto-check: notes
  • Working With Claude Code Docs

    obra/superpowers-developing-for-claude-code

    Looks up official Claude Code documentation stored as reference files instead of guessing about CLI commands, configuration, or plugin APIs.

    142 GitHub stars~1.5k tokensUpdated 10 mo ago
    Agent WorkflowsAuto-check passed
  • Agnix

    agent-sh/agnix

    A skill your agent uses when user asks to 'lint agent configs', 'validate skills', 'check CLAUDE.md', 'validate hooks', 'lint MCP'.

    445 GitHub stars~874 tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Claude Docs Consultant

    centminmod/my-claude-code-setup

    Consult official Claude Code documentation from code.claude.com using selective fetching.

    2.7k GitHub stars~959 tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Clawmem

    yoloshii/ClawMem

    ClawMem operational reference for agents at query time — the 3-rule escalation gate, MCP tool routing, the 4 query-optimization levers, pipeline behavior (query vs intentsearch), composite scoring…

    210 GitHub stars~7.5k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed
  • AI Bom

    cdxgen/cdxgen

    Generates AI-BOM, MCP inventory, AI skill inventory, and AI authorship provenance documents with cdxgen, cataloging models, inference services, Hugging Face purls, MCP servers and their…

    1.1k GitHub stars~2.5k tokensUpdated today
    Agent WorkflowsAuto-check passed

Categories

Questions about Semantix Guide

What does Semantix Guide do?

Troubleshoot and configure Semantix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project…. Semantix Guide is an agent skill from Gnosil/semantix.md / instruction docs.

When should I use Semantix Guide?

Semantix Guide fits situations like: the user asks how to configure; debug missing skills/commands/hooks/MCP/plugins; diagnose capability loading.

How do I install Semantix Guide in Claude Code?

Run `npx skills add Gnosil/semantix --skill semantix-guide -a claude-code`. Or copy the skill folder (harness/skill/builtincontent/semantix-guide in Gnosil/semantix) into .claude/skills/semantix-guide in your project. Claude Code loads it when a task matches its description.

How do I install Semantix Guide in Codex?

Run `npx skills add Gnosil/semantix --skill semantix-guide -a codex`. Or copy the skill folder (harness/skill/builtincontent/semantix-guide in Gnosil/semantix) into .agents/skills/semantix-guide in your project. Codex loads it when a task matches its description.

Can I use Semantix Guide in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Gnosil/semantix --skill semantix-guide -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/semantix-guide, .gemini/skills/semantix-guide, .github/skills/semantix-guide and .opencode/skills/semantix-guide in your project.

What does Semantix Guide need to run?

SKILL.md names no scripts, command-line tools or credentials: Semantix Guide is instructions for the agent only.

Does Semantix Guide access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Semantix Guide safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Semantix Guide use?

Semantix Guide is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Semantix Guide use?

About 2.1k tokens (SKILL.md is roughly 8.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Semantix Guide?

Skills that share tags, products or a category with Semantix Guide: Agent Setup Health Audit (tw93/Waza, 7.2k stars), Working With Claude Code Docs (obra/superpowers-developing-for-claude-code, 142 stars), Agnix (agent-sh/agnix, 445 stars) and Claude Docs Consultant (centminmod/my-claude-code-setup, 2.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Semantix Guide?

Gnosil (a GitHub user) maintains it in Gnosil/semantix, which has 821 GitHub stars. The repository was last updated on October 5, 2026.

Source: Gnosil/semantix on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.