hermes-skills/project-knowledge-base/SKILL.md

---
name: project-knowledge-base
description: "Seed and maintain a project-scoped Qdrant knowledge base from web research so a future agent (or audit) can review a software project's setup against authoritative external docs. Covers workspace scoping, multi-source ingestion, issues+resolutions extraction, and audit-query patterns."
version: 1.0.0
category: research
author: hermes
metadata:
  hermes:
    tags: [knowledge-base, qdrant, rag, project-audit, setup-review, research, web-search]
    category: research
    related_skills:
      - local-vector-memory
      - ecosystem-surveillance
      - searxng-smart-search
      - llm-wiki
      - obsidian
---

# Project Knowledge Base (Qdrant + Web Research)

Build a **queryable, project-scoped knowledge base in Qdrant** for a specific software project — populated from authoritative web sources — so that a future session can audit the project's setup against current best practices, debug recurring issues with known resolutions, or onboard a new agent quickly.

## When to Use

Trigger this skill when the user says any of:
- "do multiple deep web searches to add more details about X" (where X is a software project, framework, or tool the user is running)
- "later I want to review our setup using this KB"
- "build a knowledge base for project X"
- "find known issues and fixes for X"
- "so we can audit our X setup later"

**Not for:**
- Generic fact-gathering about a non-software topic (use `ecosystem-surveillance`)
- Markdown-only notes (use `llm-wiki`)
- Setting up the Qdrant stack itself (use `local-vector-memory` first)
- Single-file Q&A (use `web_search` directly)

## The Core Distinction from Related Skills

| Skill | Output | Intent | Scope |
|---|---|---|---|
| `ecosystem-surveillance` | Single markdown research artifact | "What's the current state of X?" | Broad, time-bounded |
| `llm-wiki` | Interlinked markdown files | Personal/team knowledge compilation | Whole domain |
| `local-vector-memory` | Qdrant collection + tooling | Storage infrastructure | Generic |
| **`project-knowledge-base`** | **Qdrant collection of structured docs** | **"Audit my project against authoritative sources"** | **One project, persistent** |

## Workflow

### Phase 1: Scope and Scaffolding

1. **Confirm the project name and target collection.** Default convention: `<project>_kb` (matches existing pattern: `hermes_kb`, `comfyui_kb`, `nuntius_kb`).
2. **Check the collection doesn't already exist or already has data:**
   ```python
   # Via mcp_better_qdrant tools
   mcp_better_qdrant_list_collections()
   mcp_better_qdrant_search(query="<project>", collection="<project>_kb", embeddingService="ollama", limit=5)
   ```
   If existing data is junk or off-topic, ask user before deleting. Never silently overwrite.
3. **Verify collection dimensions match the active Ollama embedder** (this stack: `snowflake-arctic-embed2:latest` = 1024-dim). See `local-vector-memory` "Critical pitfall — vector size hardcode" — the `better-qdrant-mcp-server` auto-creates at 768-dim if collection is missing.

### Phase 2: Topic Decomposition (todo list before searching)

Before running any searches, write a `todo` list of topic areas. The user is not going to read the whole result — they want a **structured KB that covers the project end-to-end**, not a freeform dump. Typical topic set for a software project:

1. Architecture / system overview / directory structure
2. Configuration reference (config.yaml, env vars, settings)
3. Core feature deep-dive (memory, skills, plugins, etc. — one doc per major feature)
4. Integration / API docs (MCP, providers, external services)
5. CLI / slash command reference
6. Security / approval model
7. Operational patterns (cron, delegation, multi-agent, etc.)
8. FAQ / troubleshooting / known issues + resolutions  ← **REQUIRED, not optional**
9. Index / overview doc with cross-references

The user often says "include all issues and resolutions" — that means **every doc must end with a "Common Issues + Resolutions" section**, and there should be a dedicated FAQ/troubleshooting doc as topic #8.

### Phase 3: Multi-Source Research Pattern

For each topic, layer the sources:

1. **Official docs first** (highest authority). For Hermes Agent, that's `hermes-agent.nousresearch.com/docs/...`. Get the full page with `mcp_searxng_web_url_read` — these are the canonical statements.
2. **DeepWiki / official repo docs** for architecture and code-level detail.
3. **Community deep-dives** (Rost Glukhov, Petronella, Blake Crosley, MACGPU blog, NxCode, etc.) for production experience, gotchas, and 2026-current context.
4. **Reddit / forum threads** for known issues and "what works in practice."
5. **GitHub releases / issues** for breaking changes and version-specific gotchas.

Run **3-8 searches per topic** in parallel batches (don't go serially — `mcp_searxng_searxng_web_search` supports parallel calls). Use `searxng-smart-search` defaults: tech/code = `it,science` + `time_range=month` + `min_score=0.2`.

For each topic, **fetch 1-3 full pages** with `mcp_searxng_web_url_read` rather than relying on snippets. Snippets miss the structure (command syntax, table values, pitfall callouts).

### Phase 4: Write Structured Documents to Staging

Don't write to the Qdrant collection directly. Stage first:

1. `mkdir -p /tmp/<project>_kb_staging`
2. Write one markdown doc per topic, numbered `NN_<topic>.md`, with frontmatter:
   ```yaml
   ---
   title: <Project> — <Topic>
   source: <primary URL>
   retrieved: YYYY-MM-DD
   type: official-docs | community | deep-dive | index
   ---
   ```
3. Number `00_index.md` is always the index — built last, references every other doc.
4. Each doc should be **self-contained for one topic** but end with a "Where to look for related issues" pointer to other docs.
5. Each doc must end with **"Common Issues + Resolutions"** with the format:
   ```
   ### <Symptom>
   **Cause:** <root cause>
   **Fix:** <resolution steps>
   ```
   The user explicitly asks for issues + resolutions — this is not optional, it's the audit hook.

### Phase 5: Parallel Index to Qdrant

Once all docs are staged, **parallel-batch** the `mcp_better_qdrant_add_documents` calls — don't serialize. With 12-15 docs, this is 1 turn instead of 12-15.

```python
# Pseudocode for the agent's call pattern
parallel_for doc in staging_docs:
    mcp_better_qdrant_add_documents(
        filePath=doc,
        collection=f"{project}_kb",
        embeddingService="ollama"
    )
```

### Phase 6: Verify Queryability

Run 3-5 **targeted test queries** that should hit specific docs. This is not optional — without verification, you have no evidence the KB is queryable:

```python
queries = [
    "<symptom 1 from FAQ>",
    "<key feature name>",
    "<provider-specific error>",
    "<known gotcha>"
]
for q in queries:
    mcp_better_qdrant_search(query=q, collection=f"{project}_kb", embeddingService="ollama", limit=3)
```

Check the relevance scores — values 0.4+ usually mean the doc is retrievable; below 0.4 means chunking or query is off. The agent should report scores back to the user so they know the audit will work.

### Phase 7: Report

Final report structure (terse, per user style — "1-3 sentences, actionable answer first, no padding"):

- **Total docs / chunks indexed** (the count that landed in Qdrant)
- **Coverage summary** (one line per doc, the topic)
- **Verification evidence** (test queries with scores)
- **What's in the KB** (index of doc titles so the user can `mcp_better_qdrant_search` for any)
- **Suggested next step** ("Ready for the audit — point me at what you want to review first")

## Pitfalls

1. **Don't search for things the user already told you.** If the user says "we have RTX 4090," don't search "does RTX 4090 exist?" — search for what's relevant to the project they're running on it. The KB's value is depth, not breadth.
2. **SearXNG rate-limits after 4-6 queries in quick succession.** If `mcp_searxng_searxng_web_search` returns empty or fails, **switch to `web_search`/`web_extract`** as fallback, or pause and retry. Don't bang on a dead endpoint.
3. **Snippets lie.** The model often hallucinates a useful-looking snippet that isn't actually in the page. Always `mcp_searxng_web_url_read` for the full content of top 1-3 sources per topic before writing the doc.
4. **Authoritative sources > quantity.** 1-2 great sources (official docs, deep-dive blog) per topic beats 10 thin sources. Better to write 12 well-sourced docs than 30 with redundant or low-quality content.
5. **"Common Issues + Resolutions" is required, not optional.** The user explicitly asks for this — it's the audit hook. Every doc must end with that section, and there must be a dedicated FAQ/troubleshooting doc.
6. **Include source provenance in frontmatter.** Every doc must have `source: <primary URL>` and `retrieved: <date>` in the YAML. Future audits need to know when the info was current and where it came from.
7. **Verify before reporting.** Always run test queries after indexing. A "successfully added" response doesn't mean the chunks are retrievable — relevance scores vary, and bad queries can return junk.
8. **Existing collection != good collection.** Check what's already there before adding. If the existing content is low-quality scraped SEO pages (typical for unscoped research), the new docs will be drowned in noise. Ask the user before nuking.
9. **Don't index the index doc twice.** The `00_index.md` references the others but is itself useful content — index it, but don't waste chunks on it being mostly pointers. Keep it tight.
10. **The user wants depth in work, brevity in delivery.** Final report should be 5-15 lines max — not a per-doc walkthrough. The user reads the KB via search, not your summary.

## Anti-Patterns

- **Single mega-doc.** Don't dump everything into one file. The Qdrant chunker will produce incoherent chunks, and the user can't selectively search.
- **Skipping verification.** "Successfully added" is not the same as "queryable." Always test.
- **Padding the index doc.** The index is a navigation aid, not a re-summary. One line per doc with a one-sentence description.
- **Including environment-dependent failures as "issues."** If `uv` isn't installed on the user's box, that's a setup fact, not a KB issue. Only include real product bugs, version-specific gotchas, or design gotchas (like the memory frozen-snapshot pattern).
- **Hallucinated fixes.** If you didn't see a fix in a real source, don't write one. "Common Issues + Resolutions" should be sourced from the docs you actually read. Unsourced fixes rot.

## Output Structure (what the user sees at the end)

```
Done. <project>_kb has N docs (M chunks) covering: [topic list].
Verified queryable: [test query] → [score], [test query] → [score].
Each doc has a "Common Issues + Resolutions" section. Ready for audit — point me at what to review.
```

## Related Skills

- `local-vector-memory` — load first; this skill assumes the Qdrant stack is set up
- `searxng-smart-search` — the search layer; provides defaults
- `ecosystem-surveillance` — sibling pattern for time-bounded research, not project audit
- `llm-wiki` — markdown-first alternative when Qdrant isn't desired
- `obsidian` — if the user also wants to browse the KB in an Obsidian vault (would need parallel markdown export)