Skill Preflight#

A smart plugin for OpenClaw that automatically injects the most relevant skills and protocols into your agent's context before each run. Uses Ollama embeddings — free, offline-capable, no separate embedding API key required.

What It Does#

When you run an agent, this plugin:

1. Scans your skills/ and memory/protocols/ directories for documentation
2. Embeds each doc using nomic-embed-text (via Ollama)
3. Matches the incoming prompt against your docs using cosine similarity
4. Injects only the relevant ones above a configurable threshold
5. Deduplicates within a session (same doc won't be re-injected)

Result: Agents follow custom protocols and skills without burning tokens on irrelevant context.

Requirements#

• OpenClaw ≥ 1.0
• Ollama running locally on http://localhost:11434
• Model: nomic-embed-text (download with ollama pull nomic-embed-text)

Quick Start#

1. Install Ollama#

Download from ollama.com and install.

2. Pull the embedding model#

bash

ollama pull nomic-embed-text

3. Start Ollama#

bash

ollama serve

Leave this running in the background. It listens on http://localhost:11434 by default.

4. Install the plugin#

Add to your openclaw.json:

json

{
  "plugins": {
    "skill-preflight": {
      "enabled": true,
      "config": {
        "minScore": 0.3,
        "maxResults": 3,
        "protocolDirs": ["memory/protocols"],
        "skillsDirs": ["skills"]
      }
    }
  }
}

5. Add your docs#

Create your skills and protocols in:

• skills/ — skill documentation (looks for SKILL.md in subdirs or loose .md files)
• memory/protocols/ — protocol docs ( .md files, 1 level deep)

Configuration#

OptionDefaultDescriptionprotocolDirs``["memory/protocols"]Directories to scan for protocol docs (recursive, 1 level)skillsDirs``["skills"]Directories to scan for skill docstoolsFiles``["TOOLS.md"]Individual files to always include in the indexpinnedDocs``[]Docs always injected first, regardless of scoremaxResults``3Max ranked docs to inject per run (pinned docs don't count toward this)maxDocLines``100Truncate injected docs to N lines (0 = no limit)minScore``0.3Cosine similarity threshold (0–1). Lower = more permissive. Tune via debug logs.embedModel``nomic-embed-text:latestOllama embedding modelollamaBaseUrl``http://localhost:11434Ollama API base URL. For local-only privacy, keep this on localhost, 127.0.0.1, or ::1. If you point it at a remote host, prompt text and indexed doc content are sent to that host for embeddings.requestTimeoutMs``10000Timeout for embedding requests (ms)minPromptLength``20Minimum prompt length to trigger preflight. Short prompts skip embedding.

Pinned Docs#

Pin specific docs so they're always injected first, regardless of relevance score:

json

{
  "plugins": {
    "skill-preflight": {
      "config": {
        "pinnedDocs": ["memory/protocols/house-rules.md", "skills/ethereum/SKILL.md"]
      }
    }
  }
}

Pinned docs appear first and don't count toward maxResults.

Tuning the Threshold#

Enable debug logging in OpenClaw to see similarity scores:

text

skill-preflight: scores — DebuggingProtocol(0.72), EthereumSkill(0.51), MemoryProtocol(0.34), ...

Use this to dial in minScore. If too many irrelevant docs are injected, raise it. If relevant docs are missing, lower it.

Troubleshooting#

"Ollama embedding unavailable"#

• Check Ollama is running: curl http://localhost:11434/api/tags
• Check model is installed: ollama list (should show nomic-embed-text)
• Check timeout: If embedding is slow, increase requestTimeoutMs in config

"Not injecting docs I expect"#

• Enable debug logs in OpenClaw to see scores
• Check file locations: Docs must be in configured protocolDirs or skillsDirs
• Check doc metadata: Docs with status: deprecated or status: archived are skipped
• Verify content: Empty docs or docs with only frontmatter score 0 on all prompts

"Too many/too few docs injected"#

• Adjust minScore (lower threshold = more docs)
• Adjust maxResults (cap on how many ranked docs)
• Use pinnedDocs to always include critical docs

Ollama is slow#

• nomic-embed-text takes ~100–300ms per document on typical hardware
• This is a one-time cost per new doc; embeddings are cached for 1 hour
• For faster iteration during development, raise minScore to reduce docs being embedded

File Format#

Docs are standard Markdown with optional frontmatter:

markdown

---
name: My Custom Skill
description: A brief description of what this does
status: active
---

# My Custom Skill

Detailed instructions, examples, step-by-step procedures...

Frontmatter is optional. If not provided, the first heading or filename is used as the title, and the first few lines become the description.

How It Works Under the Hood#

1. Initialization: Plugin scans configured dirs and builds a doc index
2. Doc caching: Docs are cached for 1 hour to avoid repeated disk reads
3. Embedding: On each agent run, the prompt is embedded via Ollama
4. Ranking: Docs are scored by cosine similarity, top N are selected
5. Deduplication: Tracked per session so the same doc isn't re-injected
6. Injection: Matched docs are formatted and prepended to the prompt context

Privacy & Performance#

• No separate embedding API required — embeddings go through your configured Ollama endpoint

• Local-only when Ollama is local — keep ollamaBaseUrl on localhost, 127.0.0.1, or ::1 if you want docs and prompts to stay on the same machine

• Remote Ollama changes the trust boundary — if ollamaBaseUrl points to another host, the following are sent to that host for embedding:

  • Prompt text from every agent run
  • Full indexed markdown content including secrets, API keys, credentials, and all sensitive data in your docs
  • Any confidential information embedded in your skills, protocols, and tools documentation

• Offline capable — once the Ollama model is downloaded and running locally, no internet is required

• Caching: Docs cached for 1 hour, embeddings cached in memory per session

• Session-aware: Same doc won't be re-injected in a single conversation

License#

MIT

---

Questions? Check the OpenClaw docs at openclaw.ai or report issues on GitHub.