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. 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 INLINECODE3
• 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

CODEBLOCK0

3. Start Ollama

CODEBLOCK1

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

4. Install the plugin

Add to your openclaw.json:

CODEBLOCK2

5. Add your docs

Create your skills and protocols in:

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

Configuration

Option	Default	Description
INLINECODE13	INLINECODE14	Directories to scan for protocol docs (recursive, 1 level)
INLINECODE15

["skills"] | Directories to scan for skill docs | | toolsFiles | ["TOOLS.md"] | Individual files to always include in the index | | pinnedDocs | [] | Docs always injected first, regardless of score | | maxResults | 3 | Max ranked docs to inject per run (pinned docs don't count toward this) | | maxDocLines | 100 | Truncate injected docs to N lines (0 = no limit) | | minScore | 0.3 | Cosine similarity threshold (0–1). Lower = more permissive. Tune via debug logs. | | embedModel | nomic-embed-text:latest | Ollama embedding model | | ollamaBaseUrl | http://localhost:11434 | Ollama 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 | 10000 | Timeout for embedding requests (ms) | | minPromptLength | 20 | Minimum prompt length to trigger preflight. Short prompts skip embedding. |

Pinned Docs

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

CODEBLOCK3

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

Tuning the Threshold

Enable debug logging in OpenClaw to see similarity scores:

CODEBLOCK4

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: INLINECODE40
• 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 INLINECODE45
• 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:

CODEBLOCK5

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. 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.