⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

semantix-guide

gnosil@gnosil⭐ 812 stars· last commit 3d ago· 16 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 812 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Semantix

Cross-session memory for AI coding agents — and a much smaller bill.

Semantic Caching · Adaptive Scheduling · Speculative Prefetch · Cross-Session Learning

License: MIT Version GitHub stars GitHub contributors Website

English · 简体中文 · Quickstart · Technical Overview · Website

A coding agent loses its entire context when a session ends, and a provider's prefix cache hits only on byte-identical prompts — a single edit near the head invalidates everything after it.

Semantix addresses both: a complete coding agent with the memory kernel built in, and a standalone kernel that attaches to an agent already in use.

Quick start

Install — one line, macOS / Linux (arm64 / amd64):

curl -fsSL https://raw.githubusercontent.com/Gnosil/semantix/main/agent-skill/scripts/install.sh | sh

This drops semantix + semantix-agent into ~/.local/bin and turns on cross-session memory. Use it — start the agent inside any project; that folder becomes the workspace:

cd ~/your-project
semantix                 # bare command → launch the coding agent here (first run sets up provider / API key)
semantix search "..."    # any subcommand → the memory kernel (search / extract / inject / verify / usage)

Pin a version or arch with ... | sh -s -- v0.7.2 arm64. Other install methods and the full command reference live in docs/QUICKSTART.md.

Two ways to run it

semantix-agent — the complete agent. A CLI coding agent shipping with the memory kernel built in: extraction, retrieval, injection and the evolution loop are wired at boot, with provider presets for ~50 endpoints.

The kernel — attached to an existing agent. Harness-independent by design; the integration surface is a small set of hooks (tool registration, message interception, session export / event bypass). Three ways in:

PathIntegration costApplies to
Agent skillsemantix install --target claude-codeClaude Code
Tool registrationtwo tool schemas (semantix_lookup / semantix_inject)custom / self-hosted agents
Gatewayone base URL, no code changeany OpenAI-compatible client

Fail-open throughout: on kernel error the agent falls back to its normal execution path.

Cross-session memory

A project's build conventions, test layout and service flags have to be re-established in every new session. Semantix extracts reusable slices from finished sessions — task patterns, project knowledge, tool sequences, verified results — into a local scored library, and reinjects the relevant ones when a similar task appears. Each hit carries its retrieval zone (🟢 hit · 🟡 grey · ⚪ miss) and its source session — real semantix search / dashboard / verify output lives in the reuse visualization walkthrough.

Hits, misses and manual corrections all feed back into slice scores and retrieval thresholds, so precision improves with use rather than volume alone. Type-aware eviction discards stale results first and retains project knowledge.

Cache hit rate and cost

Provider prefix caches match byte-exactly: a hit requires the prompt to be identical to the previous one byte for byte, and a single differing character near the head invalidates everything after it.

The impact of that failure mode is routinely underestimated. Claude Code writes a per-request billing marker into the head of the system prompt. First-party endpoints strip it server-side; third-party endpoints do not, so there the line invalidates the cache from the first token. The spec behind the prefix-hygiene middleware attributes a 133× difference in hit rate to that single header, and records cache spend rising 4–5× when stripping is disabled. semantix-gateway strips it by default.

The design goal is to make the provider cache hittable rather than to work around it:

  • Byte-stable injection — retrieved slices are ordered by ID rather than by score, so semantically similar requests produce byte-identical prefixes.
  • Prefix hygiene — per-request attribution markers are stripped and the tool array is canonicalized by name, removing client enumeration order as a source of invalidation.
  • Provider awareness — a vendor capability table, per-vendor cache lifetimes (DeepSeek's 24-hour on-disk context cache, Anthropic's 5-minute ephemeral window), budget-aware cache_control breakpoint placement, and per-model price tables.
  • L3 result reuse — a verified result is returned without a model call, fail-closed.

Per-provider adaptation

Cache behaviour is determined by the stack serving the model rather than by the model itself, and the spread is wide enough to require per-stack adaptation.

EndpointPrompt-cache hit, steady turnWhere the number comes from
DeepSeek99.8%provider-reported cache tokens
GLM97.5%week-long spike; ~97.6% telemetry ceiling

Both are per-turn prompt-token hit rates — hit / (hit + miss) over cache token counts returned by the provider, not estimates. semantix-agent displays the current turn's rate alongside the session average in its status line, so the figure is verifiable on any workload.

A week-long GLM study measured the same model behind different hosts and found cache lifetimes differing several-fold: one stack held a prefix for 1–8 minutes with real expiry in (8, 12]; another maintained 96–98% for 120 seconds and had fallen to 28% at 301 seconds. This is why the TTL table is per-vendor rather than a single global value, and why GLM hit-rate telemetry carries a documented ~97.6% reporting ceiling — trailing partial blocks never count as cached.

Method and raw runs: docs/reports/glm-spike-week.md · docs/reports/glm-p0-1-prefix-audit.md.

Beyond caching, the scheduler learns tool-usage patterns to parallelize eligible calls and to prefetch read-only context during model wait time.

Measured

  • 79.8% cost saved on a synthetic replay comparison — methodology in docs/reports/m0-cost-comparison.md
  • 80% cache hit rate (L3/L2) on a small demo library (4 extracted sessions) — the one-screen semantix dashboard snapshot is captured in the reuse visualization walkthrough
  • A replay gate (semantix verify) enforces ≥ 70% relevance; validating that hit rate on real user sessions is the open v1.0 gate — #58

These are replay / demo measurements, not production benchmarks. The full evidence trail — and everything else technical — lives in docs/TECHNICAL-OVERVIEW.md.

Try it in 30 seconds

Installed via the one-liner above? Extract slices from a past session, then reuse them — this is the memory kernel at work:

semantix extract --input session.jsonl --db .semantix/project.db --project demo
semantix search  --query "fix failing go test" --db .semantix/project.db
semantix inject  --query "fix failing go test" --db .

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • harness/skill/builtincontent/semantix-guide/SKILL.md8.5 KB1a2d76de7fb7upstream ↗
    ---
    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
    ```
    
    2. 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
    ```
    
    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.
    
    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
    
    | 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
    
    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
    
    | 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:
    
    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
    
    | 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_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>/…`
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/gnosil-semantix-harness-skill-builtincontent-semantix-guide.md

// REPO STATS

812 stars
16 open issues
Last commit: 3d ago