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

name, description, version, category, author, metadata

name	description	version	category	author	metadata
project-knowledge-base	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.	1.0.0	research	hermes	hermes tags category related_skills knowledge-base qdrant rag project-audit setup-review research web-search research 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:

   # 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:

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

# 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:

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)